Skip to main content
Character LCDs Python & CircuitPython

Character LCDs

Image for user adafruit2
by lady ada
published July 29, 2012, last edited January 22, 2025
posted in Arduino Compatibles/ Learn Arduino LCDs & Displays/ Character Displays LCDs & Displays/ Graphic LCDs
Save Download
140
Beginner
Skill guide

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:

learn_arduino_MetroM0_CharLCD_Mono_bb.jpg
  • 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:

learn_arduino_MetroM0_CharLCD_RGB_bb.jpg
  • 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:

learn_arduino_raspi_CharLCD_Mono_bb.jpg
  • 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:

learn_arduino_raspi_CharLCD_RGB_bb.jpg
  • Pi 5V to LCD pin 2, 15, and one side of the potentiometer.
  • Pi GND to LCD pin 1, 5, 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
Copy Code 
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
Copy Code 
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 pwmio modules and create the extra PWM lines.  For example with the Metro M0 wiring on this page:

Download File
Copy Code 
import board
import digitalio
import pwmio
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 = pwmio.PWMOut(board.D3)
green = pwmio.PWMOut(board.D5)
blue = pwmio.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
Copy Code 
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
Copy Code 
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
Copy Code 
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
Copy Code 
lcd.message = "Hello\nCircuitPython!"
learn_arduino_IMG_20171117_105115323.jpg

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
Copy Code 
lcd.cursor = True
learn_arduino_IMG_20171117_105138251.jpg

And to turn off:

Download File
Copy Code 
lcd.cursor = False
learn_arduino_IMG_20171117_105115323.jpg

You can clear the entire display using the clear function:

Download File
Copy Code 
lcd.clear()
learn_arduino_IMG_20171117_105337086.jpg

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
Copy Code 
lcd.cursor = True
lcd.blink = True
lcd.message = "Blink!"
learn_arduino_IMG_20171117_105412465.jpg

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
Copy Code 
lcd.move_left()
learn_arduino_IMG_20171117_105429486.jpg

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

Download File
Copy Code 
lcd.move_right()
learn_arduino_IMG_20171117_105445620.jpg

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
Copy Code 
lcd.color = [100, 0, 0]
learn_arduino_IMG_20171117_105925922.jpg

Or to green:

Download File
Copy Code 
lcd.color = [0, 100, 0]
learn_arduino_IMG_20171117_110030300.jpg

Or to blue:

Download File
Copy Code 
lcd.color = [0, 0, 100]
learn_arduino_IMG_20171117_110400542.jpg

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

Download File
Copy Code 
lcd.color = [100, 80, 50]
learn_arduino_IMG_20171117_110442215.jpg

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:

Download Project Bundle
Copy Code 
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

"""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)
View on GitHub

Raspberry Pi simpletest example:

Download Project Bundle
Copy Code 
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT

"""Simple test for monochromatic character LCD on Raspberry Pi"""
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

# Raspberry Pi Pin Config:
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)
lcd_backlight = digitalio.DigitalInOut(board.D4)

# 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!"
# Turn backlight off
lcd.backlight = False
time.sleep(2)
View on GitHub

Page last edited January 22, 2025

Text editor powered by tinymce.

 RGB Backlit LCDs The createChar Command 
Related Guides
RGB LCD Shield
By lady ada
65
Beginner
36mm LED Pixels
By Phillip Burgess
15
Beginner
Arduino Lesson 14. Servo Motors
By Simon Monk
101
Beginner
Smart Cocktail Shaker
By Tony DiCola
19
Beginner
Lady Ada's Bento Box
By lady ada
15
Beginner
Affordable HAL 9000 Replica
By Phillip Burgess
90
Beginner
How to program a Zumo Robot with Simulink
By Anuja Apte
4
Beginner
Adafruit 2.8" TFT Touch Shield v2 - Capacitive or...
By lady ada
64
Beginner
0.96" mini Color OLED
By lady ada
22
Beginner
Arduino Lesson 17. Email Sending Movement Detector
By Simon Monk
73
Intermediate
Arduin-o-Phone
By lady ada
91
Intermediate
Bluefruit LE Connect for iOS and Android
By Collin Cunningham
168
Intermediate
Adafruit Data Logger Shield
By Bill Earl
148
Beginner
Nokia 5110/3310 Monochrome LCD
By lady ada
27
Beginner
Program an AVR or Arduino Using Raspberry Pi GPIO
By Tony DiCola
58
Intermediate
Search

Search

Categories