Python & CircuitPython

It's easy to use a character LCD with CircuitPython or Python and the Adafruit CircuitPython CharLCD module.  This module allows you to easily write Python code that controls a character LCD (either single backlight or RGB backlight).

You can use these with any CircuitPython microcontroller board or with a computer that has GPIO and Python thanks to Adafruit_Blinka, our CircuitPython-for-Python compatibility library.

CircuitPython Microcontroller Wiring

First wire up a character LCD to your board exactly as shown on the previous pages for Arduino using the LCD's parallel data bus.  Here's an example of wiring a Metro M0 Express to a single color backlight character LCD:

  • Board 5V to LCD pin 2 and one side of the potentiometer.
  • Board GND to LCD pin 1, 5, 16, and the opposite side of the potentiometer.
  • Potentiometer output (middle pin) to LCD pin 3
  • Board D7 to LCD pin 4
  • Board D8 to LCD pin 6
  • Board D9 to LCD pin 11
  • Board D10 to LCD pin 12
  • Board D11 to LCD pin 13
  • Board D12 to LCD pin 14
  • Board D13 to LCD pin 15

Remember just like the Arduino wiring page mentions there are 4 unused pins on the LCD, pins 7-10.

If you're using a RGB backlight here's an example of wiring it to your board.  Remember, if you want to be able to do more than only red, green OR blue, each of the red, green, blue color channels needs to be wired to a PWM-capable output pin on your board (check out this script to find all the PWM capable pins on your board). If you'd like to use non-PWM pins, you can, however you'll only be able to turn on red, green OR blue at one time. The following diagram uses PWM capable pins:

  • Board 5V to LCD pin 2, 15, and one side of the potentiometer.
  • Board GND to LCD pin 1, 5, and the opposite side of the potentiometer.
  • Potentiometer output (middle pin) to LCD pin 3
  • Board D7 to LCD pin 4
  • Board D8 to LCD pin 6
  • Board D9 to LCD pin 11
  • Board D10 to LCD pin 12
  • Board D11 to LCD pin 13
  • Board D12 to LCD pin 14
  • Board D3 to LCD pin 16 (red backlight)
  • Board D5 to LCD pin 17 (green backlight)
  • Board D6 to LCD pin 18 (blue backlight)

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 a single color backlight character LCD:

  • Pi 5V to LCD pin 2, 15, and one side of the potentiometer.
  • Pi GND to LCD pin 1, 5, 16, and the opposite side of the potentiometer.
  • Potentiometer output (middle pin) to LCD pin 3
  • Pi GPIO26 to LCD pin 4
  • Pi GPIO19 to LCD pin 6
  • Pi GPIO25 to LCD pin 11
  • Pi GPIO24 to LCD pin 12
  • Pi GPIO22 to LCD pin 13
  • Pi GPIO27 to LCD pin 14

If you're using a RGB backlight character LCD, remember each of the red, green, blue color channels needs to be wired to a PWM-capable output pin on your computer (pins 10, 12, 18, 21 on the Raspberry Pi).

Here's an example of wiring an RGB backlight character LCD to a Raspberry Pi:

  • Pi 5V to LCD pin 2, 15, and one side of the potentiometer.
  • Pi GND to LCD pin 1, 5, 16, and the opposite side of the potentiometer.
  • Potentiometer output (middle pin) to LCD pin 3
  • Pi GPIO26 to LCD pin 4
  • Pi GPIO19 to LCD pin 6
  • Pi GPIO25 to LCD pin 11
  • Pi GPIO24 to LCD pin 12
  • Pi GPIO22 to LCD pin 13
  • Pi GPIO27 to LCD pin 14
  • PI GPIO21 to LCD pin 16 (red backlight)
  • Pi GPIO12 to LCD pin 17 (green backlight)
  • Pi GPIO18 to LCD pin 18 (blue backlight)

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 display text using Python code.

First you need to import the digitalio module and define all the pins connected to the LCD.  If you followed the Metro M0 wiring for a single color backlight display on this page you'd want to use:

Download: file
import board
import digitalio
lcd_rs = digitalio.DigitalInOut(board.D7)
lcd_en = digitalio.DigitalInOut(board.D8)
lcd_d7 = digitalio.DigitalInOut(board.D12)
lcd_d6 = digitalio.DigitalInOut(board.D11)
lcd_d5 = digitalio.DigitalInOut(board.D10)
lcd_d4 = digitalio.DigitalInOut(board.D9)

For use with Raspberry Pi, you need to change the pin assignments to match the Pi pins chosen. If you followed the Raspberry Pi wiring for a single color backlight display on this page, you'd want to use:

Download: file
import board
import digitalio
lcd_rs = digitalio.DigitalInOut(board.D26)
lcd_en = digitalio.DigitalInOut(board.D19)
lcd_d7 = digitalio.DigitalInOut(board.D27)
lcd_d6 = digitalio.DigitalInOut(board.D22)
lcd_d5 = digitalio.DigitalInOut(board.D24)
lcd_d4 = digitalio.DigitalInOut(board.D25)

To use a Raspberry Pi with a character LCD with an RGB backlight, check out the example found here.

For an RGB backlight on the Metro M0 Express, you need to import both the digitalio and pulseio modules and create the extra PWM lines.  For example with the Metro M0 wiring on this page:

Download: file
import board
import digitalio
import pulseio
lcd_rs = digitalio.DigitalInOut(board.D7)
lcd_en = digitalio.DigitalInOut(board.D8)
lcd_d7 = digitalio.DigitalInOut(board.D12)
lcd_d6 = digitalio.DigitalInOut(board.D11)
lcd_d5 = digitalio.DigitalInOut(board.D10)
lcd_d4 = digitalio.DigitalInOut(board.D9)
red = pulseio.PWMOut(board.D3)
green = pulseio.PWMOut(board.D5)
blue = pulseio.PWMOut(board.D6)

Now define the size of your character LCD in number of columns and rows, for example for a 16 character wide by 2 row tall display:

Download: file
lcd_columns = 16
lcd_rows = 2

Next import the character LCD module and create an instance of the Character_LCD or Character_LCD_RGB class depending on what type of display you have wired up.  For example for the single color backlight display:

Download: file
import adafruit_character_lcd.character_lcd as characterlcd
lcd = characterlcd.Character_LCD_Mono(lcd_rs, lcd_en, lcd_d4, lcd_d5, lcd_d6, lcd_d7, lcd_columns, lcd_rows)

Or for a RGB backlight display:

Download: file
import adafruit_character_lcd.character_lcd as characterlcd
lcd = characterlcd.Character_LCD_RGB(lcd_rs, lcd_en, lcd_d4, lcd_d5, lcd_d6, lcd_d7, lcd_columns, lcd_rows, red, green, blue)

Now you can print a message using the message property, for example to print on two lines (notice the \n line break added to the string in the middle):

Download: file
lcd.message = "Hello\nCircuitPython!"

You can turn the cursor on and off using the cursor property.  Set to True to turn it on and False to turn it off, for example to turn on:

Download: file
lcd.cursor = True

And to turn off:

Download: file
lcd.cursor = False

You can clear the entire display using the clear function:

Download: file
lcd.clear()

You can also blink the cursor by turning it on and then calling the blink property and setting it to a boolean value.  Set to True will start blinking the cursor, and False will disable blinking.  For example to print a message and blink the cursor:

Download: file
lcd.cursor = True
lcd.blink = True
lcd.message = "Blink!"

Finally the move_left message will move the printed message one character left, like if you wanted to scroll it off the screen. Try it:

Download: file
lcd.move_left()

Or call move_right to scroll a character back to the right:

Download: file
lcd.move_right()

If you're using the RGB backlight display there's one extra function you can use to change the backlight color.  Use the color function and provide a three-member list of red, green, blue color values, i.e. [R, G, B], that range from 0 to 100.  For example to set the color to red:

Download: file
lcd.color = [100, 0, 0]

Or to green:

Download: file
lcd.color = [0, 100, 0]

Or to blue:

Download: file
lcd.color = [0, 0, 100]

Or any color in between, like a pleasing warm white with full red, nearly full green, and half blue: 

Download: file
lcd.color = [100, 80, 50]

That's all there is to using a character LCD with CircuitPython!  Be sure to see the examples in the character LCD library too for more fun like creating and printing custom characters.

Full Example Code

Metro M0/M4 simpletest example:

"""Simple test for monochromatic character LCD"""
import time
import board
import digitalio
import adafruit_character_lcd.character_lcd as characterlcd

# Modify this if you have a different sized character LCD
lcd_columns = 16
lcd_rows = 2

# Metro M0/M4 Pin Config:
lcd_rs = digitalio.DigitalInOut(board.D7)
lcd_en = digitalio.DigitalInOut(board.D8)
lcd_d7 = digitalio.DigitalInOut(board.D12)
lcd_d6 = digitalio.DigitalInOut(board.D11)
lcd_d5 = digitalio.DigitalInOut(board.D10)
lcd_d4 = digitalio.DigitalInOut(board.D9)
lcd_backlight = digitalio.DigitalInOut(board.D13)

# Initialise the LCD class
lcd = characterlcd.Character_LCD_Mono(lcd_rs, lcd_en, lcd_d4, lcd_d5, lcd_d6,
                                      lcd_d7, lcd_columns, lcd_rows, lcd_backlight)

# 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(3)
# Turn backlight off
lcd.backlight = False
time.sleep(2)

Raspberry Pi simpletest example:

Temporarily unable to load content:
This guide was first published on Jul 29, 2012. It was last updated on Jul 29, 2012. This page (Python & CircuitPython) was last updated on Oct 13, 2019.