CircuitPython Displayio Quickstart

You will need a Metro capable of running CircuitPython such as the Metro M0 Express or the Metro M4 Express. We recommend the Metro M4 Express because it's much faster and works better for driving a display. The steps should be about the same for the Metro M0 Express. If you haven't already, be sure to check out our Adafruit Metro M4 Express featuring ATSAMD51 guide.

Adafruit Metro M4 feat. Microchip ATSAMD51

PRODUCT ID: 3382
Are you ready? Really ready? Cause here comes the fastest, most powerful Metro ever. The Adafruit Metro M4 featuring the Microchip ATSAMD51. This...
$27.50
IN STOCK

You could use a Grand Central which also has an M4 Processor. For this board, be sure to check out our Introducing the Adafruit Grand Central M4 Express guide.

Adafruit Grand Central M4 Express featuring the SAMD51

PRODUCT ID: 4064
Are you ready? Really ready? Cause here comes the Adafruit Grand Central featuring the Microchip ATSAMD51. This dev board is so big, it's not...
$37.50
IN STOCK

If you need WiFi capabilities for your project, you could also use the Metro M4 Airlift Lite. For this board, be sure to check out our Adafruit Metro M4 Express AirLift guide.

Adafruit Metro M4 Express AirLift (WiFi) - Lite

PRODUCT ID: 4000
Give your next project a lift with AirLift - our witty name for the ESP32 co-processor that graces this Metro M4. You already know about the Adafruit Metro...
$34.95
IN STOCK

Preparing the Shield

Before using the TFT Shield, you will need to solder the headers on. Be sure to check out the Adafruit Guide To Excellent Soldering. After that the shield should be ready to go.

Required CircuitPython Libraries

To use this display with displayio, there are a few required libraries. You will need the display driver and since this is no ordinary display and has some additional controls, you will also need the seesaw and busdevice 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 these libraries 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.

Remember for non-express boards, you'll need to manually install the necessary libraries from the bundle:

  • adafruit_st7735r
  • adafruit_seesaw
  • adafruit_bus_device

Before continuing make sure your board's lib folder or root filesystem has the adafruit_st7735radafruit_seesaw and adafruit_bus_device files and folders copied over.

CircuitPython Code Example

"""
This example will test out the display on the 1.8" TFT Shield
"""
import time
import board
import displayio
from adafruit_seesaw.tftshield18 import TFTShield18
from adafruit_st7735r import ST7735R

# Release any resources currently in use for the displays
displayio.release_displays()

ss = TFTShield18()

spi = board.SPI()
tft_cs = board.D10
tft_dc = board.D8

display_bus = displayio.FourWire(spi, command=tft_dc, chip_select=tft_cs)

ss.tft_reset()
display = ST7735R(display_bus, width=160, height=128, rotation=90, bgr=True)

ss.set_backlight(True)

while True:
    buttons = ss.buttons

    if buttons.right:
        print("Button RIGHT!")

    if buttons.down:
        print("Button DOWN!")

    if buttons.left:
        print("Button LEFT!")

    if buttons.up:
        print("Button UP!")

    if buttons.select:
        print("Button SELECT!")

    if buttons.a:
        print("Button A!")

    if buttons.b:
        print("Button B!")

    if buttons.c:
        print("Button C!")

    time.sleep(.001)

Let's take a look at the sections of code one by one. We start by importing time, so we can pause, the board so that we can initialize SPI, displayio, the tftshield18 seesaw library, and the adafruit_ili9341 driver.

Download: file
import time
import board
import displayio
from adafruit_seesaw.tftshield18 import TFTShield18
from adafruit_st7735r import ST7735R

Next we release any previously used displays. This is important because if the Metro is reset, the display pins are not automatically released and this makes them available for use again.

Download: file
displayio.release_displays()

We set up seesaw using the TFTShield18, which was written specifically for this shield to make things very easy.

Download: file
ss = TFTShield18()

Next, we set the SPI object to the board's SPI with the easy shortcut function board.SPI(). By using this function, it finds the SPI module and initializes using the default SPI parameters. Next we set the Chip Select and Data/Command pins that will be used.

Download: file
spi = board.SPI()
tft_cs = board.D10
tft_dc = board.D8

In the next line, we set the display bus to FourWire which makes use of the SPI bus.

Download: file
display_bus = displayio.FourWire(spi, command=tft_dc, chip_select=tft_cs)

Finally, we reset the display, initialize the driver with a width of 160 and a height of 128, and turn on the backlight. 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
ss.tft_reset()
display = ST7735R(display_bus, width=160, height=128, rotation=90, bgr=True)

ss.set_backlight(True)

Finally, we place an infinite loop at the end and constantly read the buttons. If a button is detected as being pressed, a message specifies which one. Multiple buttons can be pressed at the same time. We also provide an optional small delay to allow you to adjust how quickly you want the buttons to read in case you want to debounce the output.

Download: file
while True:
    buttons = ss.buttons

    if buttons.right:
        print("Button RIGHT!")

    if buttons.down:
        print("Button DOWN!")

    if buttons.left:
        print("Button LEFT!")

    if buttons.up:
        print("Button UP!")

    if buttons.select:
        print("Button SELECT!")

    if buttons.a:
        print("Button A!")

    if buttons.b:
        print("Button B!")

    if buttons.c:
        print("Button C!")

    time.sleep(.001)

Now go ahead and run the code. Once it's running, try pushing a few buttons and see what happens.

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 Aug 29, 2012. It was last updated on 2019-09-17 20:45:44 -0400. This page (CircuitPython Displayio Quickstart) was last updated on Sep 17, 2019.