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()
Page last edited January 22, 2025
Text editor powered by tinymce.