LiquidCrystal I2C: a 16x2 LCD on four wires
Most 16x2 and 20x4 character LCDs sold for Arduino come with a small board soldered on the back: a PCF8574 I/O expander that turns the display鈥檚 sixteen pins into four (GND, VCC, SDA and SCL). LiquidCrystal_I2C, the Frank de Brabander library in the Library Manager, speaks to that expander and gives you the same print(), setCursor() and clear() calls as the plain LiquidCrystal library.
Built in on Mokxi: #include <LiquidCrystal_I2C.h> and it builds, with nothing to install. Free, and no account needed.
What LiquidCrystal I2C does
The constructor takes the backpack鈥檚 I2C address and the size of the display. Boards built on the PCF8574T answer at 0x27 and those built on the PCF8574AT at 0x3F; the three solder pads A0 to A2 move it within that range. When you are not sure, run an I2C scanner once and use what it prints.
The blue potentiometer on the backpack sets the contrast. A brand new module often shows nothing, or a row of solid blocks, until that pot is turned, which is the first thing to try before suspecting the code.
| Library Manager name | LiquidCrystal I2C |
|---|---|
| Author | Frank de Brabander |
| Include | #include <LiquidCrystal_I2C.h> |
| Boards | every board Mokxi compiles for |
| In the simulator | Simulated: it runs against the part the way it does on the bench. |
| Parts it drives | Character LCD with I2C backpack, Character LCD, 20x4, with I2C backpack |
Install it
It builds on every board Mokxi compiles for.
In Mokxi it is built in: #include <LiquidCrystal_I2C.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "LiquidCrystal I2C" by Frank de Brabander from the Arduino IDE鈥檚 Library Manager (Sketch, Include Library, Manage Libraries), or add LiquidCrystal I2C to lib_deps in PlatformIO. Mokxi follows the calls of release 1.1.2, so a sketch written here builds there too.
What to know in the simulator: F Malpartida鈥檚 NewLiquidCrystal forms build too (LiquidCrystal_I2C lcd(0x27, 2, 1, 0, 4, 5, 6, 7, 3, POSITIVE) and begin(16, 2)); the pin map named is the usual backpack鈥檚, which every Mokxi module is.
ESP32-C3 路 Arduino Uno 路 Arduino Nano 路 Arduino Mega 2560 路 Arduino Leonardo 路 SparkFun Pro Micro 路 Arduino Micro 路 ESP32-C6 路 ATtiny85 路 Raspberry Pi Pico 路 Raspberry Pi Pico W 路 Seeed XIAO SAMD21 路 STM32 路 STM32 Nucleo-F411RE 路 STM32 Blue Pill 路 micro:bit V2 路 Arduino Uno R4 路 ESP32 DevKit 路 ESP32-S3-DevKitC-1 路 ESP8266 NodeMCU 路 Arduino Pro Mini 3.3 V 路 Seeed XIAO ESP32-C3 路 ESP32-C3 SuperMini 路 Seeed XIAO ESP32-C6 路 ESP32-DevKitC V4 路 LOLIN32 Lite 路 Wemos D1 R32 路 Cheap Yellow Display 路 TTGO T-Display 路 Seeed XIAO ESP32-S3 路 Arduino Nano ESP32 路 Arduino Nano RP2040 Connect 路 Seeed XIAO RP2040 路 Waveshare RP2040-Zero 路 Arduino Uno R4 WiFi
The calls you will use
In the order a sketch meets them.
LiquidCrystal_I2C lcd(0x27, 16, 2)
Creates the display at I2C address 0x27 with 16 columns and 2 rows. A 20x4 module is LiquidCrystal_I2C lcd(0x27, 20, 4).
lcd.init()
Starts I2C and sends the controller its set-up. Some forks call it begin(); call it once in setup().
lcd.backlight()
Turns the backlight on through the backpack. Without it the text is there but very hard to see; noBacklight() turns it off again.
lcd.setCursor(0, 1)
Moves to column 0 of row 1, the second line. Columns and rows count from zero.
lcd.setCursor(0, 1);
lcd.print("Temp: ");
lcd.print(21.4, 1);lcd.clear()
Blanks the screen and returns the cursor to 0, 0. It takes about 2 ms, so calling it every loop makes the text flicker; overwrite with spaces instead.
lcd.createChar(0, heart)
Stores a custom 5 by 8 character in one of eight slots (0 to 7). Print it with lcd.write(0).
byte heart[8] = {0, 10, 31, 31, 14, 4, 0, 0};
lcd.createChar(0, heart);
lcd.setCursor(15, 0);
lcd.write(0);lcd.scrollDisplayLeft()
Shifts everything on the display one column left, for scrolling text longer than the screen. Call it in a loop with a short delay between steps.
Example: enjoyneering鈥檚 LiquidCrystal_I2C: the backpack named pin by pin
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include <Wire.h>
#include <LiquidCrystal_I2C.h>
#define COLUMS 16
#define ROWS 2
LiquidCrystal_I2C lcd(PCF8574_ADDR_A21_A11_A01, 4, 5, 6, 16, 11, 12, 13, 14, POSITIVE);
void setup() {
Serial.begin(115200);
while (lcd.begin(COLUMS, ROWS, LCD_5x8DOTS) != 1) {
Serial.println(F("PCF8574 is not connected or lcd pins declaration is wrong."));
delay(5000);
}
lcd.print(F("PCF8574 is OK..."));
Serial.println(F("PCF8574 is OK"));
delay(500);
lcd.clear();
lcd.print(F("Hello world"));
lcd.setCursor(0, 1);
lcd.print(F("uptime "));
}
void loop() {
lcd.setCursor(7, 1);
lcd.print(millis() / 1000);
delay(250);
}Wiring
- Arduino Uno R3 A4 to Character LCD with I2C backpack SDA
- Arduino Uno R3 A5 to Character LCD with I2C backpack SCL
- Arduino Uno R3 5V to Character LCD with I2C backpack VCC
- Arduino Uno R3 GND to Character LCD with I2C backpack GND
Common errors and how to fix them
The backlight is on but the screen shows a row of solid blocks
Either the contrast pot needs turning or init() never reached the display. Turn the pot slowly first; if the blocks stay, check the address with an I2C scanner and that SDA and SCL go to the board鈥檚 I2C pins.
Nothing at all: no text and no blocks
The address in the constructor is wrong (0x27 against 0x3F is the usual mix-up) or the module has no power. Run an I2C scanner and put the address it finds in the constructor.
Only the first letter of each print() appears
An old copy of the library written before Arduino 1.0 is installed. Remove it from the libraries folder and install LiquidCrystal I2C from the Library Manager, which returns the byte count print() expects.
'LiquidCrystal_I2C' does not name a type
The header was not found or a different library with the same file name won. Check the #include line spelling, then make sure only one LiquidCrystal_I2C library is installed.
Projects that use LiquidCrystal I2C
Built-in projects that include it. Each page has the full sketch and opens in the editor, already wired.
Keep going
Learn
More displays libraries
Try LiquidCrystal I2C without installing anything
Open the example, change the sketch, and keep your version in a free account.