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.

The Circuit Playground Express, which has a SAMD chip, may not be able to run the full example due to memory constraints. This is why we recommend using the Circuit Playground Bluefruit.

Circuit Playground Bluefruit - Bluetooth Low Energy

PRODUCT ID: 4333
Circuit Playground Bluefruit is our third board in the Circuit Playground series, another step towards a perfect introduction to electronics and programming. We've...
OUT OF STOCK

Circuit Playground Express

PRODUCT ID: 3333
Circuit Playground Express is the next step towards a perfect introduction to electronics and programming. We've taken the original Circuit Playground Classic and...
$24.95
IN STOCK

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.

CircuitPython Code Example

"""
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(max_size=10)
display.show(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(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)

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.

Download: file
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.

Download: file
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.

Download: file
splash = displayio.Group(max_size=10)
display.show(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.

Download: file
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.

Download: file
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.

Download: file
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.

Download: file
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.

Download: file
while True:
    pass

Where to go from here

Be sure to check out this excellent guide to CircuitPython Display Support Using displayio

This guide was first published on Oct 03, 2019. It was last updated on Oct 03, 2019.
This page (CircuitPython Displayio Quickstart) was last updated on Oct 21, 2020.