LCD_I2C: Blackhack’s library for the I2C character LCD
LCD_I2C, by Blackhack, is a newer library for the same hardware as LiquidCrystal_I2C: an HD44780 16x2 or 20x4 LCD with a PCF8574 backpack on SDA and SCL. It shows up in tutorials written since about 2020 because its Library Manager name is short and easy to find, and its calls read a little more plainly.
Built in on Mokxi: #include <LCD_I2C.h> and it builds, with nothing to install. Free, and no account needed.
What LCD_I2C does
The differences are naming, and they matter when you mix code from two tutorials. LCD_I2C starts with begin() rather than init(), and every call that turns something off ends in Off: backlightOff(), displayOff(), cursorOff(), blinkOff() and autoscrollOff(). The LiquidCrystal names noBacklight() and noCursor() are not there.
begin() also starts the Wire bus for you. If your sketch has already called Wire.begin() with its own pins, for example on an ESP32 with SDA and SCL moved, pass false so the library leaves the bus alone.
| Library Manager name | LCD_I2C |
|---|---|
| Author | Blackhack |
| Include | #include <LCD_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 |
Install it
It builds on every board Mokxi compiles for.
In Mokxi it is built in: #include <LCD_I2C.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "LCD_I2C" by Blackhack from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add LCD_I2C to lib_deps in PlatformIO. Mokxi follows the calls of release 2.4.0, so a sketch written here builds there too.
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.
LCD_I2C lcd(0x27, 16, 2)
The display at address 0x27, 16 columns by 2 rows. Change the address to 0x3F for a backpack built on the PCF8574A.
lcd.begin()
Starts I2C and sets the display up. lcd.begin(false) skips Wire.begin() when the sketch started the bus itself.
lcd.backlight()
Turns the backlight on; lcd.backlightOff() turns it off.
lcd.setCursor(4, 0)
Moves to column 4 of the first row before the next print().
lcd.setCursor(4, 0);
lcd.print("Ready");lcd.clear()
Clears the display and homes the cursor. For a number that changes often, print over it with spaces instead to avoid flicker.
lcd.blinkOff()
Stops the blinking cursor block that blink() turns on. cursorOff() does the same for the underline cursor.
Example: An I2C LCD with LCD_I2C
On the Arduino Uno R3. It runs in the browser exactly as printed.
#include <LCD_I2C.h>
LCD_I2C lcd(0x27, 16, 2);
void setup() {
Serial.begin(9600);
lcd.begin();
lcd.backlight();
lcd.print(" Hello");
lcd.setCursor(5, 1);
lcd.print("World!");
Serial.println("printed");
}
void loop() {}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
'class LCD_I2C' has no member named 'init'
init() belongs to LiquidCrystal_I2C. With this library the call is lcd.begin(); change that one line and the rest of a LiquidCrystal_I2C sketch usually compiles.
'class LCD_I2C' has no member named 'noBacklight'
LCD_I2C spells the off calls with a suffix: use backlightOff(), cursorOff(), blinkOff() and displayOff() in place of noBacklight(), noCursor(), noBlink() and noDisplay().
The display stays blank on an ESP32 with custom I2C pins
begin() called Wire.begin() on the default pins after your own call. Start the bus with Wire.begin(sda, scl) first and then call lcd.begin(false) so it is not restarted.
Keep going
Learn
More displays libraries
Try LCD_I2C without installing anything
Open the example, change the sketch, and keep your version in a free account.