Python & CircuitPython

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

First wire up a character LCD backpack to your board exactly as shown on the previous pages for Arduino using the backpack's I2C or SPI configuration.  

Here's an example of wiring a Feather M0 to the backpack with an I2C connection (the recommended wiring):

  • 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.)
  • Board GND to backpack GND.
  • Board SCL to backpack CLK.
  • Board SDA to backpack DAT.

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 M0 to the backpack with a hardware SPI connection:

  • 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.)
  • Board GND to backpack GND.
  • Board SCK to backpack CLK.
  • Board MOSI to backpack DAT.
  • Board D5 to backpack LAT.

Don't forget to solder closed the SPI jumper on the board if using the SPI wiring!

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:

  • Pi 5V to backpack 5V
  • Pi GND to backpack GND.
  • Pi SCL to backpack CLK.
  • Pi SDA to backpack DAT.

Here's the Raspberry Pi wired to the backpack using SPI:

  • Pi 5V to backpack 5V
  • 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 install the library bundle.

For non-express boards like the Trinket M0 or Gemma M0, you'll need to manually install the necessary libraries from the bundle:

  • adafruit_character_lcd
  • adafruit_mcp230xx
  • adafruit_74hc595
  • adafruit_bus_device

Before continuing make sure your board's lib folder or root filesystem has the adafruit_character_lcd, adafruit_mcp230xx, adafruit_74hc595 and adafruit_bus_device 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:

Download: file
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!):

Download: file
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:

Download: file
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.

"""Simple test for 16x2 character lcd connected to an MCP23008 I2C LCD backpack."""
import time
import board
import busio
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 = busio.I2C(board.SCL, board.SDA)

# 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.

"""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)
This guide was first published on Aug 27, 2012. It was last updated on Aug 27, 2012. This page (Python & CircuitPython) was last updated on Oct 23, 2019.