You will need a board capable of running CircuitPython such as the Circuit Playground Express or Circuit Playground Bluefruit. The Circuit Playground Classic will only run Arduino sketches.
Circuit Playground Express with Displayio
If you have a Circuit Playground Express board, you will need a special build that includes displayio to use the TFT Gizmo. Be sure to download the latest one. You can find it here:
Required CircuitPython Libraries
To use this display with displayio, there are only two required libraries.
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 the library from Adafruit's CircuitPython library bundle. Our introduction guide has a great page on how to install the library bundle for both Express and non-Express boards.
Due to the number of libraries in the bundle, it is recommended that you manually install the necessary library from the bundle:
- adafruit_st7789
- adafruit_gizmo
Before continuing make sure your board's lib folder has the adafruit_st7789.mpy and adafruit_gizmo file and folder copied over.
Code Example Additional Libraries
For the Code Example, you will need an additional library. We decided to make use of a library so the code didn't get overly complicated. You'll also need to copy over the following library from the bundle:
- adafruit_display_text
Go ahead and install this in the same manner as the driver library by copying the adafruit_display_text folder over to the lib folder on your CircuitPython device.
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
"""
This test will initialize the display using displayio and draw a solid green
background, a smaller purple rectangle, and some yellow text.
"""
import displayio
import terminalio
from adafruit_display_text import label
from adafruit_gizmo import tft_gizmo
# Create the TFT Gizmo display
display = tft_gizmo.TFT_Gizmo()
# Make the display context
splash = displayio.Group()
display.root_group = splash
color_bitmap = displayio.Bitmap(240, 240, 1)
color_palette = displayio.Palette(1)
color_palette[0] = 0x00FF00 # Bright Green
bg_sprite = displayio.TileGrid(color_bitmap, pixel_shader=color_palette, x=0, y=0)
splash.append(bg_sprite)
# Draw a smaller inner rectangle
inner_bitmap = displayio.Bitmap(200, 200, 1)
inner_palette = displayio.Palette(1)
inner_palette[0] = 0xAA0088 # Purple
inner_sprite = displayio.TileGrid(inner_bitmap, pixel_shader=inner_palette, x=20, y=20)
splash.append(inner_sprite)
# Draw a label
text_group = displayio.Group(scale=2, x=50, y=120)
text = "Hello World!"
text_area = label.Label(terminalio.FONT, text=text, color=0xFFFF00)
text_group.append(text_area) # Subgroup for text scaling
splash.append(text_group)
while True:
pass
Let's take a look at the sections of code one by one. We start by importing displayio,terminalio for the font, a label, and the tft_gizmo helper.
import displayio import terminalio from adafruit_display_text import label from adafruit_gizmo import tft_gizmo
Next, we initialize the helper, which takes care of all the TFT Gizmo ST7789 Driver initialization for us. If we stopped at this point and ran the code, we would have a terminal that we could type at and have the screen update.
display = tft_gizmo.TFT_Gizmo()
Next we create a background splash image. We do this by creating a group that we can add elements to and adding that group to the display. In this example, we are limiting the maximum number of elements to 10, but this can be increased if you would like. The display will automatically handle updating the group.
splash = displayio.Group(max_size=10) display.root_group = splash
Next we create a Bitmap which is like a canvas that we can draw on. In this case we are creating the Bitmap to be the same size as the screen, but only have one color. The Bitmaps can currently handle up to 256 different colors. We create a Palette with one color and set that color to 0x00FF00 which happens to be green. Colors are Hexadecimal values in the format of RRGGBB. Even though the Bitmaps can only handle 256 colors at a time, you get to define what those 256 different colors are.
color_bitmap = displayio.Bitmap(240, 240, 1) color_palette = displayio.Palette(1) color_palette[0] = 0x00FF00 # Bright Green
With all those pieces in place, we create a TileGrid by passing the bitmap and palette and draw it at (0, 0) which represents the display's upper left.
bg_sprite = displayio.TileGrid(color_bitmap,
pixel_shader=color_palette,
x=0, y=0)
splash.append(bg_sprite)
Next we will create a smaller purple square. The easiest way to do this is the create a new bitmap that is a little smaller than the full screen with a single color and place it in a specific location. In this case, we will create a bitmap that is 20 pixels smaller on each side. The screen is 240x240, so we'll want to subtract 40 from each of those numbers.
We'll also want to place it at the position (20, 20) so that it ends up centered.
inner_bitmap = displayio.Bitmap(200, 200, 1)
inner_palette = displayio.Palette(1)
inner_palette[0] = 0xAA0088 # Purple
inner_sprite = displayio.TileGrid(inner_bitmap,
pixel_shader=inner_palette,
x=20, y=20)
splash.append(inner_sprite)
Since we are adding this after the first square, it's automatically drawn on top. Here's what it looks like now.
Next let's add a label that says "Hello World!" on top of that. We're going to use the built-in Terminal Font and scale it up by a factor of two. To scale the label only, we will make use of a subgroup, which we will then add to the main group.
Labels are centered vertically, so we'll place it at 120 for the Y coordinate, and around 50 pixels make it appear to be centered horizontally, but if you want to change the text, change this to whatever looks good to you. Let's go with some yellow text, so we'll pass it a value of 0xFFFF00.
text_group = displayio.Group(max_size=10, scale=2, x=50, y=120) text = "Hello World!" text_area = label.Label(terminalio.FONT, text=text, color=0xFFFF00) text_group.append(text_area) # Subgroup for text scaling splash.append(text_group)
Finally, we place an infinite loop at the end so that the graphics screen remains in place and isn't replaced by a terminal.
while True:
pass
Where to go from here
Be sure to check out this excellent guide to CircuitPython Display Support Using displayio
Page last edited January 21, 2025
Text editor powered by tinymce.
