ESP32 MicroPython LCD I2C

This tutorial instructs you how to use ESP32 with a 16x2 LCD I2C, utilizing MicroPython. You will learn:

ESP32 MicroPython and 16x2 LCD I2C

Hardware Preparation

1×ESP-WROOM-32 Dev Module
1×USB Cable Type-C
1×LCD I2C
1×Jumper Wires
1×Breadboard
1×(Recommended) Screw Terminal Expansion Board for ESP32

Or you can buy the following sensor kits:

1×DIYables Sensor Kit (30 sensors/displays)
1×DIYables Sensor Kit (18 sensors/displays)
Disclosure: Some of the links provided in this section are Amazon affiliate links. We may receive a commission for any purchases made through these links at no additional cost to you.
Additionally, some of these links are for products from our own brand, DIYables.

Overview of LCD I2C 16x2

The 16x2 LCD I2C is a screen with 16 columns and 2 rows. It has an I2C interface and comes with a potentiometer to adjust the screen's contrast.

Pinout

The LCD I2C uses an I2C interface and includes 4 pins.

  • GND pin: connect to GND (0 volts).
  • VCC pin: connect to VCC for power (5 volts).
  • SDA pin: transfers I2C data signal.
  • SCL pin: transfers I2C clock signal.
LCD I2C Pinout

LCD Coordinate

The LCD I2C 16x2 includes 16 columns and 2 rows. The numbering of both columns and rows begins from 0.

ESP32 MicroPython LCD I2C Coordinate

Wiring Diagram

  • How to connect ESP32 and LCD i2c using breadboard (powered via USB cable)
The wiring diagram between ESP32 MicroPython LCD I2C

This image is created using Fritzing. Click to enlarge image

  • How to connect ESP32 and LCD i2c using breadboard (powered via Vin pin)
The wiring diagram between ESP32 MicroPython LCD display

This image is created using Fritzing. Click to enlarge image

How to connect ESP32 and LCD i2c
How to wire ESP32 and LCD i2c
LCD I2C ESP32
VCC Vin 5V
GND GND
SDA GPIO21 (SDA)
SCL GPIO22 (SCL)

ESP32 MicroPython Code

""" This ESP32 MicroPython code was developed by newbiely.com This ESP32 MicroPython code is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-lcd-i2c """ from machine import I2C, Pin from DIYables_MicroPython_LCD_I2C import LCD_I2C import utime # The I2C address of your LCD (Update if different) I2C_ADDR = 0x27 # Use the address found using the I2C scanner # Define the number of rows and columns on your LCD LCD_ROWS = 2 LCD_COLS = 16 # Initialize I2C i2c = I2C(1, scl=Pin(22), sda=Pin(21), freq=400000) # Initialize LCD lcd = LCD_I2C(i2c, I2C_ADDR, LCD_ROWS, LCD_COLS) # Setup function lcd.backlight_on() lcd.clear() # Main loop function while True: lcd.clear() lcd.set_cursor(3, 0) # Move the cursor to column 3, row 0 (first row) lcd.print("DIYables") lcd.set_cursor(0, 1) # Move the cursor to column 0, row 1 (second row) lcd.print("www.diyables.io") utime.sleep(2) lcd.clear() lcd.set_cursor(0, 0) # Move to the beginning of the first row lcd.print("Int: ") lcd.print(str(1234)) # Print integer lcd.set_cursor(0, 1) # Move to the beginning of the second row lcd.print("Float: ") lcd.print(str(56.78)) # Print float utime.sleep(2)

Detailed Instructions

Here’s instructions on how to set up and run your MicroPython code on the ESP32 using Thonny IDE:

  • Make sure Thonny IDE is installed on your computer.
  • Confirm that MicroPython firmware is loaded on your ESP32 board.
  • If this is your first time using an ESP32 with MicroPython, check out the ESP32 MicroPython Getting Started guide for step-by-step instructions.
  • Connect the LCD I2C display to the ESP32 according to the provided diagram.
  • Connect the ESP32 board to your computer with a USB cable.
  • Open Thonny IDE on your computer.
  • In Thonny IDE, go to Tools Options.
  • Under the Interpreter tab, choose MicroPython (ESP32) from the dropdown menu.
  • Make sure the correct port is selected. Thonny IDE usually detects it automatically, but you might need to select it manually (like COM12 on Windows or /dev/ttyACM0 on Linux).
  • Navigate to the Tools Manage packages on the Thonny IDE.
  • Search “DIYables-MicroPython-LCD-I2C”, then find the LCD I2C library created by DIYables.
  • Click on DIYables-MicroPython-LCD-I2C, then click Install button to install LCD I2C library.
ESP32 MicroPython LCD I2C library
  • Copy the provided MicroPython code and paste it into Thonny's editor.
  • Save the code to your ESP32 by:
    • Clicking the Save button or pressing Ctrl+S.
    • In the save dialog, choose MicroPython device.
    • Name the file main.py.
  • Click the green Run button (or press F5) to execute the script.
  • Check out the result on the LCD display.
ESP32 MicroPython LCD 16x2

Do More with LCD

Displaying Custom Character on LCD

To display special characters or symbols (like a heart or an angry bird) on an LCD, you'll need to use a character generator. This is because the lcd.print() function can only display standard ASCII characters.

The LCD 16x2 can display 32 characters, arranged in 16 positions per line over 2 lines. Each character is composed of 40 pixels, organized in 8 rows and 5 columns.

ESP32 MicroPython LCD 16x2 Pixel

The character generator makes a character (40 pixels). You just need to follow these steps:

Click on each pixel to select/deselect


Copy below custom character code
Replace the heart in the below code
""" This ESP32 MicroPython code was developed by newbiely.com This ESP32 MicroPython code is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-lcd-i2c """ from machine import I2C, Pin from DIYables_MicroPython_LCD_I2C import LCD_I2C import utime # The I2C address of your LCD (Update if different) I2C_ADDR = 0x27 # Define the number of rows and columns on your LCD LCD_ROWS = 2 LCD_COLS = 16 # Initialize I2C i2c = I2C(1, scl=Pin(22), sda=Pin(21), freq=400000) # Initialize LCD lcd = LCD_I2C(i2c, I2C_ADDR, LCD_ROWS, LCD_COLS) # Define custom character 0 (heart shape) heart = [ 0b00000, 0b01010, 0b11111, 0b11111, 0b01110, 0b00100, 0b00000, 0b00000 ] # Create the custom character at location 0 lcd.custom_char(0, heart) # Display the custom character lcd.print("Custom Char: ") lcd.print_custom_char(0) # Display the custom character stored at location 0

Result shown on the screen:

LCD custom character

Displaying Multiple custom characters on LCD

We can create up to 8 special characters (from 0 to 7). Here is how to make and show three of these characters.

""" This ESP32 MicroPython code was developed by newbiely.com This ESP32 MicroPython code is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-lcd-i2c """ from machine import I2C, Pin from DIYables_MicroPython_LCD_I2C import LCD_I2C import utime # The I2C address of your LCD (Update if different) I2C_ADDR = 0x27 # Define the number of rows and columns on your LCD LCD_ROWS = 2 LCD_COLS = 16 # Initialize I2C i2c = I2C(1, scl=Pin(22), sda=Pin(21), freq=400000) # Initialize LCD lcd = LCD_I2C(i2c, I2C_ADDR, LCD_ROWS, LCD_COLS) # Define custom character 0 (heart shape) heart = [ 0b00000, 0b01010, 0b11111, 0b11111, 0b01110, 0b00100, 0b00000, 0b00000 ] # Define custom character 1 (arrow pointing upwards) arrow_up = [ 0b00100, 0b01110, 0b11111, 0b00100, 0b00100, 0b00100, 0b00100, 0b00100 ] # Define custom character 2 (arrow pointing downwards) arrow_down = [ 0b00100, 0b00100, 0b00100, 0b00100, 0b00100, 0b11111, 0b01110, 0b00100 ] # Create the custom character at location 0 lcd.custom_char(0, heart) lcd.custom_char(1, arrow_up) lcd.custom_char(2, arrow_down) # Display the custom character lcd.set_cursor(0, 0) # Move the cursor to column 0, row 0 (first row) lcd.print_custom_char(0) # Display the custom character stored at location 0 lcd.set_cursor(5, 0) # Move the cursor to column 5, row 0 (first row) lcd.print_custom_char(1) # Display the custom character stored at location 0 lcd.set_cursor(10, 0) # Move the cursor to column 10, row 0 (first row) lcd.print_custom_char(2) # Display the custom character stored at location 0

Result shown on LCD screen:

LCD multiple custom characters

Summary: How to Use Custom Characters on an LCD

  • Create binary code: Use the provided tool to generate the binary code for your custom character.
  • Write down the code: Copy the binary code from the tool.
heart = [ 0b00000, 0b01010, 0b11111, 0b11111, 0b01110, 0b00100, 0b00000, 0b00000 ]
  • Create a custom character and position it at a number from 0 to 7
lcd.custom_char(0, heart)
  • Show a custom symbol on the LCD display.
lcd.print_custom_char(0) # Display the custom character stored at location 0

Troubleshooting on LCD I2C

If you're having trouble displaying text on your LCD I2C screen, try the following:

  • Adjust the brightness: Rotate the potentiometer on the back of the LCD to increase or decrease the brightness.
  • Check the I2C address: The I2C address for the LCD may vary between manufacturers. Common addresses are 0x27 and 0x3F. Experiment with these addresses to see if either works. If not, you can run the below I2C scanner code on ESP32 board to scan for the correct I2C address.
""" This ESP32 MicroPython code was developed by newbiely.com This ESP32 MicroPython code is made available for public use without any restriction For comprehensive instructions and wiring diagrams, please visit: https://newbiely.com/tutorials/esp32-micropython/esp32-micropython-lcd-i2c """ from machine import I2C, Pin import utime i2c = I2C(1, scl=Pin(22), sda=Pin(21)) print('Scanning I2C bus...') devices = i2c.scan() if len(devices) == 0: print("No I2C devices found") else: print('I2C devices found:',len(devices)) for device in devices: print("Decimal address: ",device," | Hex address: ",hex(device)) utime.sleep(2)

The result shown in the Shell at the bottom of Thonny:

Shell x
>>> %Run -c $EDITOR_CONTENT
MPY: soft reboot Scanning I2C bus... I2C devices found: 1 Decimal address: 39 | Hex address: 0x27
MicroPython (ESP32) • CP2102 USB To UART Bridge Controller @ COM12 ≡

※ OUR MESSAGES

  • As freelancers, We are AVAILABLE for HIRE. See how to outsource your project to us
  • Please feel free to share the link of this tutorial. However, Please do not use our content on any other websites. We invested a lot of effort and time to create the content, please respect our work!