Python Usage

It's easy to use the I2C 16x2 RGB LCD Pi plate with Python and the Adafruit CircuitPython CharLCD library. This library allows you to easily write Python code that controls the RGB character LCD.

Assemble the plate as shown in the previous pages and attach to your Pi.

You'll need to set up your Raspberry PI to work with I2C before this will work! Check out the CircuitPython on Raspberry Pi guide for details: https://learn.adafruit.com/circuitpython-on-raspberrypi-linux

Python Installation of CharLCD Library

You'll need to install the Adafruit_Blinka library that provides the CircuitPython support in Python. This will also require enabling I2C on your Raspberry Pi and verifying you are running Python 3.

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 Code

To demonstrate the usage of the character LCD we'll initialize it and display text using CircuitPython code.

First, you'll need to import necessary modules, initialize the I2C bus, and create an instance of the character LCD class. Paste the following code into your REPL:

Download: file
import board
import busio
import adafruit_character_lcd.character_lcd_rgb_i2c as character_lcd
lcd_columns = 16
lcd_rows = 2
i2c = busio.I2C(board.SCL, board.SDA)
lcd = character_lcd.Character_LCD_RGB_I2C(i2c, lcd_columns, lcd_rows)

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 color property to set the backlight to red and the message property to write text to the display:

Download: file
lcd.color = [100, 0, 0]
lcd.message = "Hello\nCircuitPython"

See the parallel LCD guide for more functions you can call to control the LCD!

If you don't see anything, adjust the potentiometer on the plate until the message shows up. The potentiometer is located below the LCD on the side opposite the buttons.

That's all there is to using the RGB character LCD Pi Plate with Python and the Adafruit CircuitPython CharLCD library!

Full Example Code

Save the following file to your Pi and run it to see a demo of some of the different things the character LCD library has to offer!

"""Simple test for I2C RGB character LCD shield kit"""
import time
import board
import busio
import adafruit_character_lcd.character_lcd_rgb_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_RGB_I2C(i2c, lcd_columns, lcd_rows)

lcd.clear()
# Set LCD color to red
lcd.color = [100, 0, 0]
time.sleep(1)
# Print two line message
lcd.message = "Hello\nCircuitPython"
# Wait 5s
time.sleep(5)
# Set LCD color to blue
lcd.color = [0, 100, 0]
time.sleep(1)
# Set LCD color to green
lcd.color = [0, 0, 100]
time.sleep(1)
# Set LCD color to purple
lcd.color = [50, 0, 50]
time.sleep(1)
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 to the left
for i in range(len(scroll_msg)):
    time.sleep(0.5)
    lcd.move_left()
lcd.clear()
time.sleep(1)
lcd.message = "Going to sleep\nCya later!"
time.sleep(5)
# Turn off LCD backlights and clear text
lcd.color = [0, 0, 0]
lcd.clear()
This guide was first published on Nov 21, 2012. It was last updated on Nov 21, 2012. This page (Python Usage) was last updated on Aug 17, 2019.