MicroPython LCD I2C Library

Author: Mr Tech
Supported Boards: Raspberry Pi Pico, ESP8266, ESP32, and other MicroPython-compatible boards

This is a simple, easy-to-use I2C LCD driver for MicroPython. It supports 16x2 and 20x4 LCDs, backlight control, cursor visibility, blinking, custom characters, and optional automatic I2C address detection.

---

Features

• Works with most I2C LCD modules (16x2, 20x4)
• Compatible with ESP8266, ESP32, Raspberry Pi Pico, etc.
• Optional automatic I2C address detection
• Turn backlight on or off
• Show/hide cursor and enable blinking
• Create and display custom characters

---

Installation

Copy the lcd.py file to your MicroPython board. Example using Thonny:

1. Connect your board.
2. Open Thonny → File → Save As → MicroPython device.
3. Save the file as lcd.py.

---

Usage Example

from machine import I2C, Pin
from lcd import LCD
import time

sda = Pin(0)
scl = Pin(1)
i2c = I2C(0, sda=sda, scl=scl, freq=400000)

# Optional: addr can be specified, or left None to auto-detect
lcd = LCD(i2c, rows=2, cols=16)
lcd.write("Hello There", 0, 0)
lcd.write("by Mr Tech", 0, 1)

Class: LCD

The LCD class provides all functions needed to control an I2C LCD display.

__init__(i2c, addr=None, rows=2, cols=16, backlight=True)

Initialize the LCD.

• i2c: An instance of machine.I2C

• addr: Optional I2C address. If None, auto-detects the first connected I2C device

• rows: Number of rows (default 2)

• cols: Number of columns (default 16)

• backlight: Enable backlight at startup (default True)

clear()

Clears the entire display and resets the cursor to home (0,0).

home()

Moves the cursor to the home position (0,0).

show_cursor(blink=False)

Shows the cursor on the display.

blink: Set to True to enable blinking

hide_cursor()

Hides the cursor.

backlight(on=True)

Turn the backlight on or off.

on: True for on, False for off

set_cursor(col=0, row=0)

Move the cursor to a specific position.

col: Column number (0-indexed)

row: Row number (0-indexed)

write(text, col=None, row=None)

Write text to the LCD, optionally at a specific column and row.

text: The string to display

col: Optional column number to start writing

row: Optional row number to start writing

custom_char(index, bitmap) Define a custom character.

index: Character slot (0–7)

bitmap: List of 8 integers representing the custom character

draw_custom(index)

Display a previously defined custom character.

index: Character slot (0–7)

Notes

• If multiple I2C devices are connected, the first detected device is used when addr=None.

• Common LCD I2C addresses are 0x27 or 0x3F.

• ESP8266 default pins for I2C: SDA → GPIO0 (D3), SCL → GPIO1 (D2)

• You can adjust freq in I2C() if the LCD is unstable.

Example Auto-Detect I2C Address

from machine import I2C, Pin

sda = Pin(0)
scl = Pin(1)
i2c = I2C(0, sda=sda, scl=scl, freq=400000)

devices = i2c.scan()
print("I2C devices found:", [hex(dev) for dev in devices])