LiquidCrystal_I2C Library: Complete Reference Guide

If you’ve ever worked with character LCDs on Arduino projects, you know the pain of dealing with multiple data pins. The LiquidCrystal_I2C library solves this problem elegantly by reducing your wiring from 12 pins down to just 4. After spending countless hours debugging LCD projects on various PCBs, I can tell you this library is a game-changer for anyone serious about embedded development.

What is the LiquidCrystal_I2C Library?

The LiquidCrystal_I2C library is an Arduino library that enables communication between your microcontroller and HD44780-based character LCD displays through the I2C protocol. Instead of connecting 8+ wires directly to your LCD’s parallel interface, you use a small I2C backpack module (typically based on the PCF8574 I/O expander) that handles all the heavy lifting.

This library maintains API compatibility with the standard LiquidCrystal library, meaning most of your existing LCD code will work with minimal modifications. Frank de Brabander originally authored the most widely-used version, though several forks exist with additional features.

Why Use the LiquidCrystal_I2C Library?

From a PCB design perspective, the advantages are significant. When you’re laying out a board, every GPIO pin matters. The I2C approach frees up precious pins for sensors, buttons, or other peripherals. I’ve used this setup on dozens of production boards, and the reduced trace routing alone makes the library worth adopting.

The I2C bus also allows daisy-chaining multiple devices. You can run several LCDs alongside temperature sensors, EEPROMs, and RTCs on the same two-wire bus without any conflicts.

LiquidCrystal_I2C Library Installation Guide

Installing via Arduino Library Manager

The easiest installation method uses the built-in Library Manager:

1. Open Arduino IDE
2. Navigate to Tools → Manage Libraries (or press Ctrl + Shift + I)
3. Search for “LiquidCrystal_I2C”
4. Find the library by Frank de Brabander
5. Click Install

Manual Installation from GitHub

For the latest features or specific versions, download directly from GitHub:

1. Visit the repository at github.com/fdebrabander/Arduino-LiquidCrystal-I2C-library
2. Download the ZIP file
3. Create a folder named “LiquidCrystal_I2C” in your Arduino libraries directory
4. Extract all files into this folder
5. Restart Arduino IDE

Important Note About Multiple Library Versions

Here’s something that trips up many developers: multiple libraries share the “LiquidCrystal_I2C” name but have different APIs. If your code throws compilation errors, check your libraries folder and remove any duplicate versions. Keep only the one you intend to use.

Hardware Setup and Wiring Connections

Standard I2C Wiring Configuration

The wiring couldn’t be simpler. Connect your I2C LCD backpack to the Arduino using these connections:

LCD I2C Pin	Arduino Uno/Nano	Arduino Mega	ESP8266	ESP32
VCC	5V	5V	3.3V/5V	3.3V
GND	GND	GND	GND	GND
SDA	A4	Pin 20	GPIO4	GPIO21
SCL	A5	Pin 21	GPIO5	GPIO22

Common I2C Addresses for LCD Modules

Different manufacturers use different default addresses. The most common ones are:

Address	Chip Type	Common Use
0x27	PCF8574T	Most Chinese modules
0x3F	PCF8574AT	Some alternative modules
0x20	PCF8574	Address jumpers all open
0x38	PCF8574A	Less common variants

If you’re unsure about your module’s address, run an I2C scanner sketch. This simple program probes all possible addresses and reports any devices found:

#include <Wire.h>

void setup() {

  Wire.begin();

  Serial.begin(9600);

  Serial.println(“I2C Scanner Starting…”);

}

void loop() {

  byte error, address;

  int deviceCount = 0;

  for(address = 1; address < 127; address++) {

    Wire.beginTransmission(address);

    error = Wire.endTransmission();

    if (error == 0) {

      Serial.print(“Device found at 0x”);

      Serial.println(address, HEX);

      deviceCount++;

    }

  }

  if (deviceCount == 0)

    Serial.println(“No I2C devices found”);

  delay(5000);

}

LiquidCrystal_I2C Library Functions Reference

Constructor and Initialization Functions

The table below lists all initialization functions available in the LiquidCrystal_I2C library:

Function	Parameters	Description
LiquidCrystal_I2C()	address, cols, rows	Creates LCD object with I2C address and dimensions
init()	none	Initializes LCD with default settings
begin()	none	Alias for init(), starts the LCD
clear()	none	Clears display and returns cursor to home
home()	none	Returns cursor to position (0,0)

Display Control Functions

Function	Parameters	Description
display()	none	Turns display on
noDisplay()	none	Turns display off (content preserved)
backlight()	none	Turns backlight on
noBacklight()	none	Turns backlight off
setBacklight()	state	Sets backlight to HIGH or LOW

Cursor Control Functions

Function	Parameters	Description
setCursor()	col, row	Positions cursor at specified column and row
cursor()	none	Shows underscore cursor
noCursor()	none	Hides cursor
blink()	none	Enables blinking block cursor
noBlink()	none	Disables blinking cursor

Text Output Functions

Function	Parameters	Description
print()	data	Prints text or numbers to LCD
write()	byte	Writes single character to LCD
createChar()	location, charmap	Defines custom character (0-7)

Scrolling and Text Direction Functions

Function	Parameters	Description
scrollDisplayLeft()	none	Scrolls entire display left
scrollDisplayRight()	none	Scrolls entire display right
autoscroll()	none	Enables automatic scrolling
noAutoscroll()	none	Disables automatic scrolling
leftToRight()	none	Sets text direction left-to-right
rightToLeft()	none	Sets text direction right-to-left

Basic Code Examples for LiquidCrystal_I2C

Hello World Example

The simplest possible program to verify your setup:

#include <Wire.h>

#include <LiquidCrystal_I2C.h>

LiquidCrystal_I2C lcd(0x27, 16, 2);

void setup() {

  lcd.init();

  lcd.backlight();

  lcd.setCursor(0, 0);

  lcd.print(“Hello World!”);

  lcd.setCursor(0, 1);

  lcd.print(“LCD Working!”);

}

void loop() {

}

Displaying Sensor Data Example

A practical example showing temperature readings:

#include <Wire.h>

#include <LiquidCrystal_I2C.h>

LiquidCrystal_I2C lcd(0x27, 16, 2);

int sensorPin = A0;

void setup() {

  lcd.init();

  lcd.backlight();

  lcd.setCursor(0, 0);

  lcd.print(“Temperature:”);

}

void loop() {

  int reading = analogRead(sensorPin);

  float voltage = reading * 5.0 / 1024.0;

  float temperature = (voltage – 0.5) * 100;

  lcd.setCursor(0, 1);

  lcd.print(temperature);

  lcd.print(” C    “);

  delay(1000);

}

Creating Custom Characters with LiquidCrystal_I2C

One of the most powerful features of HD44780 displays is the ability to define up to 8 custom characters. Each character occupies a 5×8 pixel matrix that you define as a byte array.

Custom Character Byte Array Structure

byte heart[8] = {

  0b00000,

  0b01010,

  0b11111,

  0b11111,

  0b11111,

  0b01110,

  0b00100,

  0b00000

};

Complete Custom Characters Example

#include <Wire.h>

#include <LiquidCrystal_I2C.h>

LiquidCrystal_I2C lcd(0x27, 16, 2);

byte heart[8] = {

  0b00000, 0b01010, 0b11111, 0b11111,

  0b11111, 0b01110, 0b00100, 0b00000

};

byte smiley[8] = {

  0b00000, 0b00000, 0b01010, 0b00000,

  0b10001, 0b01110, 0b00000, 0b00000

};

void setup() {

  lcd.init();

  lcd.backlight();

  lcd.createChar(0, heart);

  lcd.createChar(1, smiley);

  lcd.setCursor(0, 0);

  lcd.print(“I “);

  lcd.write(byte(0));

  lcd.print(” Arduino”);

  lcd.setCursor(0, 1);

  lcd.write(byte(1));

  lcd.print(” Custom chars!”);

}

void loop() {

}

Troubleshooting Common LiquidCrystal_I2C Problems

LCD Display Shows Nothing

This is the most common issue, and in my experience, it usually comes down to three things:

Check the I2C address. Run the scanner sketch mentioned earlier. Most modules use 0x27, but yours might be different.

Adjust the contrast potentiometer. Look for a small blue pot on the I2C backpack. Turn it slowly while powered on until text appears. I’ve seen brand new modules ship with contrast set to zero.

Verify your wiring. Double-check SDA and SCL connections. They’re easy to swap accidentally.

Display Shows Garbled Characters

This usually indicates a library version mismatch or incorrect initialization. Delete all LiquidCrystal_I2C libraries from your system, install only the Frank de Brabander version, and restart your IDE.

Backlight Works But No Text

The display is communicating, so address and wiring are correct. Try these fixes:

1. Adjust contrast potentiometer
2. Call lcd.init() before lcd.backlight()
3. Add a small delay after initialization

Compilation Errors with begin() Function

Different library versions handle initialization differently. If you get errors about begin() not accepting parameters, try using lcd.init() instead, or declare dimensions in the constructor:

// Method 1: Dimensions in constructor

LiquidCrystal_I2C lcd(0x27, 16, 2);

lcd.init();

// Method 2: Some libraries need this

LiquidCrystal_I2C lcd(0x27, 16, 2);

lcd.begin(16, 2);

Working with 20×4 LCD Displays

Larger displays work identically to 16×2 modules. Simply update the dimensions:

LiquidCrystal_I2C lcd(0x27, 20, 4);

void setup() {

  lcd.init();

  lcd.backlight();

  lcd.setCursor(0, 0);

  lcd.print(“Line 0”);

  lcd.setCursor(0, 1);

  lcd.print(“Line 1”);

  lcd.setCursor(0, 2);

  lcd.print(“Line 2”);

  lcd.setCursor(0, 3);

  lcd.print(“Line 3”);

}

Note that row numbering starts at 0, not 1. This catches many beginners off guard.

Resources and Downloads for LiquidCrystal_I2C Library

Official Library Downloads

Resource	URL
Frank de Brabander’s Library	github.com/fdebrabander/Arduino-LiquidCrystal-I2C-library
John Rickman’s Fork	github.com/johnrickman/LiquidCrystal_I2C
Arduino Library Registry	arduinolibraries.info/libraries/liquid-crystal-i2-c
ESP8266 Compatible Version	github.com/lucasmaziero/LiquidCrystal_I2C

Useful Tools

Tool	Purpose
LCD Custom Character Generator	omerk.github.io/lcdchargen
Wokwi Simulator	wokwi.com (online Arduino simulator with I2C LCD support)
I2C Scanner Sketch	Built into Wire library examples

Recommended I2C LCD Hardware

Most 16×2 and 20×4 character LCDs with I2C backpacks work with this library. Look for modules with the PCF8574 or PCF8574A chip. Quality varies significantly between manufacturers, so purchasing from reputable suppliers saves debugging time.

Frequently Asked Questions

What I2C address does my LCD use?

Most I2C LCD modules default to address 0x27 (PCF8574T) or 0x3F (PCF8574AT). Run an I2C scanner sketch to find your specific address. The address depends on the chip variant and any jumper settings on the backpack module.

Can I use multiple LCDs on the same I2C bus?

Yes, but each LCD needs a unique address. Most backpack modules have solder jumpers (A0, A1, A2) that let you configure different addresses. With three address pins, you can theoretically run up to 8 LCDs on one bus.

Why does my LCD show only the backlight with no text?

This typically indicates correct communication but wrong contrast settings. Locate the small potentiometer on the I2C backpack and slowly rotate it while the Arduino runs your sketch. You should see text appear as you adjust it.

Is the LiquidCrystal_I2C library compatible with ESP32 and ESP8266?

Yes, the library works with ESP8266 and ESP32 boards. The main difference is the I2C pin assignments. ESP8266 uses GPIO4 (SDA) and GPIO5 (SCL) by default, while ESP32 uses GPIO21 (SDA) and GPIO22 (SCL). Some forks include specific ESP support with configurable pins.

How many custom characters can I create?

The HD44780 controller allows exactly 8 custom characters, stored in CGRAM locations 0 through 7. Each character uses a 5×8 pixel bitmap defined as a byte array. You can redefine characters during runtime to effectively display more unique symbols.

Conclusion

The LiquidCrystal_I2C library transforms what used to be a wiring nightmare into a straightforward four-wire connection. Whether you’re building a one-off prototype or designing a production PCB, the simplified interface and reduced pin count make this library essential for any character LCD project.

The key to success lies in verifying your I2C address, installing the correct library version, and remembering to adjust that contrast potentiometer. Once you nail those basics, you’ll find the LiquidCrystal_I2C library incredibly reliable across hundreds of projects.

Start with the Hello World example, verify everything works, then build from there. The function reference above covers everything you need for most applications, and custom characters open up creative possibilities for status indicators, progress bars, and unique interface elements.