Display - LCD2004


Plugin details

Type: Display

Name: LCD2004


GitHub: P012_LCD.ino

Maintainer: .

Used libraries: .


This plugin can be used to control an I2C connected LCD display. These displays often offer 2 lines of 16 characters or 4 lines of 20 characters for displaying all kinds of information.


After adding the plugin to a Task in the Devices list, it should be configured for proper operation.


Name A unique name should be entered here.

Enabled The device can be disabled or enabled. When not enabled the device should not use any resources.

I2C Options

The available settings here depend on the build used. At least the Force Slow I2C speed option is available, but selections for the I2C Multiplexer can also be shown. For details see the Hardware page

I2C Address: The address the device is using. Most devices allow a configurable address, usually the information on how to set/change that address is available on the printed circuit board, or on the manufacturers website.

Device Settings

Display Size Select the size of the display, either 2x16 characters or 4x20 characters can be selected.


Line 1..4 Up to 4 lines can be pre-configured with text to display. For the 2x16 device size, only Line 1 and 2 will be used. Variables can be used, f.e. to display values provided by a sensor.

Display button A button can be configured to enable the display on demand. This function is enabled by selecting a GPIO pin to monitor. Combined with Inversed login and Display Timeout the display will be automatically turned off after the timeout has expired.

Inversed logic Normally the Display button GPIO pin must be connected to GND to activate the display. With this option checked the signal should be normally connected to ground, and get a high level (3.3V) to turn the display on. This way, f.e. a PIR sensor or touch button that provides an active-high signal can be used.

Display Timeout This defines how long the display will be turned on when the Display button turns it on (or after the start of the display). The timeout unit is seconds.

LCD Command mode


Continue to next line (as in v1.4) Compatible with older versions mode, where text sent via rules, http or mqtt, will wrap over to the next line when longer then the display is wide.

Truncate exceeding message When text to display is too long to fit, the excess won’t be displayed (discarded).

Clear then truncate exceeding message This will first clear the line where the text is to be displayed from the column where it is to start, and then the actual text will be displayed, discarding any text beyond the width of the display.

The Interval setting defines the delay in seconds between updates of the display. When the Line 1..4 fields are used, these lines will be updated with the updated data of any variables used there.

Build Info

To support characters used in the Polish language, add this define: USES_P012_POLISH_CHARS

Supported hardware


Example photo of a 4x20 (LCD2004) display:



When using a 5V powered display with on-board pull-up resistors on the I2C bus, a level-convert should be used to connect to an ESP to avoid damage to the 3.3V I2C bus on the ESP and any other I2C devices connected!

Commands available


Extra information



  • on will turn the display ON.

  • off will turn the display OFF.

  • clear will clear any information from the display.

Using these commands, either from rules, via http or mqtt, the state of the display can be controlled.


The <row> parameter corresponds with the same lines as the plugin configuration has.

The <col> parameter sets the column the text will be displayed.

The <text> parameter must be a single command parameter. Meaning, it must be wrapped in quotes when using a space or comma as text.

If double quote characters are needed, wrap the parameter in single quotes or back quotes.

All template notations can be used, like system variables, or reference to a task value.

Rules Example

The following example displays a running X across the screen, switching between two speeds every screen loop completion.

//Init variables
on System#Boot do
 let,1,20                        //screen columns
 let,2,4                         // screen lines
 let,3,1                         // current line = 1
 let,4,1                         // current column = 1
 let,5,500                       // speed1 ms
 let,6,250                       // speed2 ms
 let,7,[int#5]                   // set current speed to speed1
 loopTimerSet_ms,1,[int#7]       // start timer1 with current speed
 lcd,clean                       // clear screen

//Screen loop
On Rules#Timer=1 do
 lcd,[int#3],[int#4],            // clear screen old position
 if [int#4] < [int#1]            // column < max columns
    let,4,[int#4]+1              // increment column
    let,4,1                      // reset column
    if [int#3] < [int#2]         // line < max lines
      let,3,[int#3]+1            // increment line
      let,3,1                    // reset line  (screen full loop finished)
      asyncevent,changeSpeed     // raise change speed event
 lcd,[int#3],[int#4],X           // draw X on new position

//Change speed
on changeSpeed do
  if [int#7] = [int#5]           // if current speed = speed1
    let,7,[int#6]                // set to speed2
    let,7,[int#5]                // set to speed1
  loopTimerSet_ms,1,[int#7]      // set new timer to current speed

Change log

Changed in version 2021-05-03:

added Inversed logic setting to allow high-active Display button.

Changed in version 2020-09-14:

added Support for characters used in Polish language, define USES_P012_POLISH_CHARS to include those in a build.

Added in version 1.0:

added Initial release version.