How to Use I2C LCD with ESP32 on Arduino IDE (ESP8266 compatible)

This tutorial shows how to use the I2C LCD (Liquid Crystal Display) with the ESP32 using Arduino IDE. We’ll show you how to wire the display, install the library and try sample code to write text on the LCD: static text, and scroll long messages. You can also use this guide with the ESP8266.
16×2 I2C Liquid Crystal Display
For this tutorial we’ll be using a 16×2 I2C LCD display, but LCDs with other sizes should also work.
The advantage of using an I2C LCD is that the wiring is really simple. You just need to wire the SDA and SCL pins.
Additionally, it comes with a built-in potentiometer you can use to adjust the contrast between the background and the characters on the LCD. On a “regular” LCD you need to add a potentiometer to the circuit to adjust the contrast.
Parts Required
To follow this tutorial you need these parts:
ESP32 DOIT DEVKIT V1 Board
–
read ESP32 Development Boards Review and Comparison
Optional –
ESP8266 12-E
– read
Best ESP8266 Wi-Fi Development Boards
16×2 I2C Liquid Crystal Display (LCD)
Female to female jumper wires
You can use the preceding links or go directly to
MakerAdvisor.com/tools
to find all the parts for your projects at the best price!
Wiring the LCD to the ESP32
This display uses I2C communication, which makes wiring really simple.
Wire your LCD to the ESP32 by following the next schematic diagram. We’re using the ESP32 default I2C pins (
GPIO 21
and
GPIO 22
).
You can also use the following table as a reference.
I2C LCD
ESP32
GND
GND
VCC
VIN
SDA
GPIO 21
SCL
GPIO 22
Wiring the LCD to the ESP8266
You can also wire your LCD to the ESP8266 by following the next schematic diagram. We’re using the ESP8266 default I2C pins (
GPIO 4
and
GPIO 5
).
You can also use the following table as a reference.
I2C LCD
ESP8266
GND
GND
VCC
VIN
SDA
GPIO 4
(D2)
SCL
GPIO 5
(D1)
Preparing the Arduino IDE
Before proceeding with the project, you need to install the ESP32 or ESP8266 add-on in the Arduino IDE.
Arduino IDE with ESP32
Follow one of the next guides to prepare your Arduino IDE to work with the ESP32:
Windows
instructions – ESP32 Board in Arduino IDE
Mac and Linux
instructions – ESP32 Board in Arduino IDE
Arduino IDE with ESP8266
To install the ESP8266 add-on in your Arduino IDE, read the following tutorial:
How to Install the ESP8266 Board in Arduino IDE
Installing the LiquidCrystal_I2C Library
There are several libraries that work with the I2C LCD. We’re using
this library by Marco Schwartz
. Follow the next steps to install the library:
Click here to download the LiquidCrystal_I2C library
. You should have a .zip folder in your Downloads
Unzip the
.zip
folder and you should get
LiquidCrystal_I2C-master
folder
Rename your folder from
LiquidCrystal_I2C-master
to
LiquidCrystal_I2C
Move the
LiquidCrystal_I2C
folder to your Arduino IDE installation
libraries
folder
Finally, re-open your Arduino IDE
Getting the LCD Address
Before displaying text on the LCD, you need to find the LCD I2C address. With the LCD properly wired to the ESP32, upload the following I2C Scanner sketch.

#include <Wire.h>

void setup() {
Wire.begin();
Serial.begin(115200);
Serial.println("\nI2C Scanner");
}

void loop() {
byte error, address;
int nDevices;
Serial.println("Scanning...");
nDevices = 0;
for(address = 1; address < 127; address++ ) {
Wire.beginTransmission(address);
error = Wire.endTransmission();
if (error == 0) {
Serial.print("I2C device found at address 0x");
if (address<16) {
Serial.print("0");
}
Serial.println(address,HEX);
nDevices++;
}
else if (error==4) {
Serial.print("Unknow error at address 0x");
if (address<16) {
Serial.print("0");
}
Serial.println(address,HEX);
}
}
if (nDevices == 0) {
Serial.println("No I2C devices found\n");
}
else {
Serial.println("done\n");
}
delay(5000);
}
After uploading the code, open the Serial Monitor at a baud rate of 115200. Press the ESP32 EN button. The I2C address should be displayed in the Serial Monitor.
In this case the address is
0x27
. If you’re using a similar 16×2 display, you’ll probably get the same address.
Display Static Text on the LCD
Displaying static text on the LCD is very simple. All you have to do is select where you want the characters to be displayed on the screen, and then send the message to the display.
Here’s a very simple sketch example that displays “
Hello, World!
“.

#include <LiquidCrystal_I2C.h>

// set the LCD number of columns and rows
int lcdColumns = 16;
int lcdRows = 2;

// set LCD address, number of columns and rows
// if you don't know your display address, run an I2C scanner sketch
LiquidCrystal_I2C lcd(0x27, lcdColumns, lcdRows);

void setup(){
// initialize LCD
lcd.init();
// turn on LCD backlight
lcd.backlight();
}

void loop(){
// set cursor to first column, first row
lcd.setCursor(0, 0);
// print message
lcd.print("Hello, World!");
delay(1000);
// clears the display to print new message
lcd.clear();
// set cursor to first column, second row
lcd.setCursor(0,1);
lcd.print("Hello, World!");
delay(1000);
lcd.clear();
}
It displays the message in the first row, and then in the second row.
In this simple sketch we show you the most useful and important functions from the
LiquidCrystal_I2C
library. So, let’s take a quick look at how the code works.
How the code works
First, you need to include the
LiquidCrystal_I2C
library.
#include <LiquidCrystal_I2C.h>
The next two lines set the number of columns and rows of your LCD display. If you’re using a display with another size, you should modify those variables.
int lcdColumns = 16;
int lcdRows = 2;
Then, you need to set the display address, the number of columns and number of rows. You should use the display address you’ve found in the previous step.
LiquidCrystal_I2C lcd(0x27, lcdColumns, lcdRows);
In the
setup()
, first initialize the display with the
init()
method.
lcd.init();
Then, turn on the LCD backlight, so that you’re able to read the characters on the display.
lcd.backlight();
To display a message on the screen, first you need to set the cursor to where you want your message to be written. The following line sets the cursor to the first column, first row.
lcd.setCursor(0, 0);
Note
: 0 corresponds to the first column, 1 to the second column, and so on…
Then, you can finally print your message on the display using the
print()
method.
lcd.print("Hello, World!");
Wait one second, and then clean the display with the
clear()
method.
lcd.clear();
After that, set the cursor to a new position: first column, second row.
lcd.setCursor(0,1);
Then, the process is repeated.
So, here’s a summary of the functions to manipulate and write on the display:
lcd.init()
: initializes the display
lcd.backlight()
: turns the LCD backlight on
lcd.setCursor(int column, int row)
: sets the cursor to the specified column and row
lcd.print(String message)
: displays the message on the display
lcd.clear()
: clears the display
This example works well to display static text no longer than 16 characters.
Display Scrolling Text on the LCD
Scrolling text on the LCD is specially useful when you want to display messages longer than 16 characters. The library comes with built-in functions that allows you to scroll text. However, many people experience problems with those functions because:
The function scrolls text on both rows. So, you can’t have a fixed row and a scrolling row;
It doesn’t work properly if you try to display messages longer than 16 characters.
So, we’ve created a sample sketch with a function you can use in your projects to scroll longer messages.
The fo