It's easy to use the RGB character LCD shield with CircuitPython and the Adafruit CircuitPython CharLCD library. This library allows you to easily write Python code that controls the RGB character LCD.
CircuitPython Microcontroller Wiring
Assemble the shield kit as shown in the previous pages. Then, attach it to a Metro M0 or Metro M4. It's that simple!
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.
If you choose, you may manually install the libraries from the bundle:
- adafruit_character_lcd
- adafruit_mcp230xx
- adafruit_bus_device
Before continuing make sure your board's lib folder or root filesystem has the adafruit_character_lcd, adafruit_mcp230xx, and adafruit_bus_device files and folders copied over.
Next connect to the board's serial REPL so you are at the CircuitPython >>> prompt.
CircuitPython 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:
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:
lcd.color = [100, 0, 0] 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 RGB character LCD shield kit with CircuitPython!
Full Code Example
Copy the following example to code.py on your board, and see a demo of some of the different things the character LCD library has to offer!
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
"""Simple test for I2C RGB character LCD shield kit"""
import time
import board
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 = 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_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()
