It's easy to use the character LCD backpack with CircuitPython or Python and the Adafruit CircuitPython CharLCD module. Just like wiring up a LCD in parallel and controlling it from CircuitPython, you can use the I2C/SPI backpack to also control a LCD from CircuitPython or Python. The same Adafruit CircuitPython CharLCD module allows you to easily write Python code that controls a character LCD (remember only the single color backlight displays are supported by the backpack!).
CircuitPython Microcontroller Wiring
Here's an example of wiring a Feather RP2040 to the backpack with a STEMMA QT cable or via the terminal blocks:
- Board 3V to backpack VIN
- Board GND to backpack GND
- Board SCL to backpack CLK
- Board SDA to backpack DAT
If using the original version of the backpack:
- Board VUSB to backpack 5V (remember using the VUSB output on a Feather means it must be connected to a 5V USB power source like your computer or a battery pack! You can alternatively use the 3.3V output of the Feather but it might not be enough to power the LCD.)
Or you can wire the LCD backpack to your board using the SPI interface. Remember you must also solder closed the SPI Enable bridge on the backpack! Here's an example of wiring a Feather M4 to the backpack with a hardware SPI connection:
- Board 3V to backpack VIN
- Board GND to backpack GND.
- Board SCK to backpack CLK.
- Board MOSI to backpack DAT.
- Board D5 to backpack LAT.
If using the original version of the backpack:
- Board VUSB to backpack VIN (remember using the VUSB output on a Feather means it must be connected to a 5V USB power source like your computer or a battery pack! You can alternatively use the 3.3V output of the Feather but it might not be enough to power the LCD.)
Python Computer Wiring
Since there's dozens of Linux computers/boards you can use we will show wiring for Raspberry Pi. For other platforms, please visit the guide for CircuitPython on Linux to see whether your platform is supported.
Here's the Raspberry Pi wired to the backpack using I2C:
Here's the Raspberry Pi wired to the backpack using SPI:
- Pi 3V to backpack VIN
- Pi GND to backpack GND.
- Pi SCK to backpack CLK.
- Pi MOSI to backpack DAT.
- Pi GPIO5 to backpack LAT.
CircuitPython Installation of CharLCD Library
You'll need to install the Adafruit CircuitPython CharLCD library on your CircuitPython board.
First make sure you are running the latest version of Adafruit CircuitPython for your board.
Next you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle. Our CircuitPython starter guide has a great page on how to use the library bundle.
You'll need to install the necessary libraries from the bundle:
- adafruit_character_lcd
- adafruit_mcp230xx (used only for I2C)
- adafruit_74hc595 (used only for SPI)
- adafruit_bus_device (only needed on non-Express boards with adafruit_bus_device not built in)
Before continuing make sure your board's lib folder or root filesystem has the library files and folders copied over.
Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.
Python Installation of CharLCD Library
You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This may also require enabling I2C on your platform and verifying you are running Python 3. Since each platform is a little different, and Linux changes often, please visit the CircuitPython on Linux guide to get your computer ready!
Once that's done, from your command line run the following command:
sudo pip3 install adafruit-circuitpython-charlcd
If your default Python is version 3 you may need to run 'pip' instead. Just make sure you aren't trying to use CircuitPython on Python 2.x, it isn't supported!
Python & CircuitPython Usage
To demonstrate the usage of the character LCD we'll initialize it and write text using Python code.
I2C Initialization
For an I2C backpack run the following code to import necessary modules, initialize the I2C bus, and create an instance of the character LCD class:
import board import busio import adafruit_character_lcd.character_lcd_i2c as character_lcd i2c = busio.I2C(board.SCL, board.SDA) cols = 16 rows = 2 lcd = character_lcd.Character_LCD_I2C(i2c, cols, rows)
Also notice you need to specify the number of columns and rows for your character LCD. The cols and rows variables above are setting these values for a 16x2 character LCD. Make sure to set the right value for your LCD!
SPI Initialization
For a SPI backpack as wired above run the following code instead (again be sure to set the right cols and rows for your display!):
import board import busio import digitalio import adafruit_character_lcd.character_lcd_spi as character_lcd spi = busio.SPI(board.SCK, MOSI=board.MOSI) latch = digitalio.DigitalInOut(board.D5) cols = 16 rows = 2 lcd = character_lcd.Character_LCD_SPI(spi, latch, cols, rows)
The only big difference with a SPI connection is that you must also import the digitalio module and pass in a DigitalInOut pin for the latch line. Notice board pin D5 is used for this wiring--be sure to change the pin if your wiring is different.
Backpack Usage
Now you're ready to start writing text and characters on the display! The usage of the LCD class is exactly the same as shown in the parallel LCD wiring guide. Be sure to check out that guide for a complete discussion of LCD usage.
As a quick test though you can run the following code to use the message property to write text to the display:
lcd.message = "Hello\nCircuitPython!"
See the parallel LCD guide for more functions you can call to control the LCD!
That's all there is to using the I2C/SPI backpack with CircuitPython!
Full Example Code
As a complete example of I2C usage, see the charlcd_I2C_simpletest.py example in the character LCD library. Save this as code.py on your board and it will run a small demo of LCD functions.
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
"""Simple test for 16x2 character lcd connected to an MCP23008 I2C LCD backpack."""
import time
import board
import adafruit_character_lcd.character_lcd_i2c as character_lcd
# Modify this if you have a different sized Character LCD
lcd_columns = 16
lcd_rows = 2
# Initialise I2C bus.
i2c = board.I2C() # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C() # For using the built-in STEMMA QT connector on a microcontroller
# Initialise the lcd class
lcd = character_lcd.Character_LCD_I2C(i2c, lcd_columns, lcd_rows)
# Turn backlight on
lcd.backlight = True
# Print a two line message
lcd.message = "Hello\nCircuitPython"
# Wait 5s
time.sleep(5)
lcd.clear()
# Print two line message right to left
lcd.text_direction = lcd.RIGHT_TO_LEFT
lcd.message = "Hello\nCircuitPython"
# Wait 5s
time.sleep(5)
# Return text direction to left to right
lcd.text_direction = lcd.LEFT_TO_RIGHT
# Display cursor
lcd.clear()
lcd.cursor = True
lcd.message = "Cursor! "
# Wait 5s
time.sleep(5)
# Display blinking cursor
lcd.clear()
lcd.blink = True
lcd.message = "Blinky Cursor!"
# Wait 5s
time.sleep(5)
lcd.blink = False
lcd.clear()
# Create message to scroll
scroll_msg = "<-- Scroll"
lcd.message = scroll_msg
# Scroll message to the left
for i in range(len(scroll_msg)):
time.sleep(0.5)
lcd.move_left()
lcd.clear()
lcd.message = "Going to sleep\nCya later!"
time.sleep(5)
# Turn backlight off
lcd.backlight = False
time.sleep(2)
And a complete example of SPI usage is in the charlcd_SPI_simpletest.py example in the library. Save this as code.py on your board and it will run a small demo of LCD functions.
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
"""Simple test for 16x2 character LCD connected to 74HC595 SPI LCD backpack."""
import time
import board
import busio
import digitalio
import adafruit_character_lcd.character_lcd_spi as character_lcd
# Modify this if you have a different sized character LCD
lcd_columns = 16
lcd_rows = 2
# Backpack connection configuration:
clk = board.SCK # Pin connected to backpack CLK.
data = board.MOSI # Pin connected to backpack DAT/data.
latch = board.D5 # Pin connected to backpack LAT/latch.
# Initialise SPI bus.
spi = busio.SPI(clk, MOSI=data)
# Initialise the LCD class
latch = digitalio.DigitalInOut(latch)
lcd = character_lcd.Character_LCD_SPI(spi, latch, lcd_columns, lcd_rows)
# Turn backlight on
lcd.backlight = True
# Print a two line message
lcd.message = "Hello\nCircuitPython"
# Wait 5s
time.sleep(5)
lcd.clear()
# Print two line message right to left
lcd.text_direction = lcd.RIGHT_TO_LEFT
lcd.message = "Hello\nCircuitPython"
# Wait 5s
time.sleep(5)
# Return text direction to left to right
lcd.text_direction = lcd.LEFT_TO_RIGHT
# Display cursor
lcd.clear()
lcd.cursor = True
lcd.message = "Cursor! "
# Wait 5s
time.sleep(5)
# Display blinking cursor
lcd.clear()
lcd.blink = True
lcd.message = "Blinky Cursor!"
# Wait 5s
time.sleep(5)
lcd.blink = False
lcd.clear()
# Create message to scroll
scroll_msg = "<-- Scroll"
lcd.message = scroll_msg
# Scroll message to the left
for i in range(len(scroll_msg)):
time.sleep(0.5)
lcd.move_left()
lcd.clear()
lcd.message = "Going to sleep\nCya later!"
# Turn backlight off
lcd.backlight = False
time.sleep(2)
Text editor powered by tinymce.
