You will need a board capable of running CircuitPython, such as the Adafruit Metro M4 Express. You can also use boards such as the Adafruit Feather M4 Express. Adafruit recommends using at least an M4 processor because they are much faster and works better for driving a display.

This guide will be using a Feather M4 Express. The steps should be about the same for the Metro. If you haven't already, be sure to check out the Feather M4 Express guide.

Angled shot of a Adafruit Feather M4 Express.
It's what you've been waiting for, the Feather M4 Express featuring ATSAMD51. This Feather is fast like a swift, smart like an owl, strong like a ox-bird (it's half ox,...
Out of Stock

Preparing the Breakout

Before using the TFT Breakout, you will need to solder the headers or some wires to it. Be sure to check out the Adafruit Guide To Excellent Soldering. After that the breakout should be ready to go.

Feather Wiring

  • Vin connects to the Feather's 3V pin
  • GND connects to the Feather's Gnd pin
  • CLK connects to SPI clock. On the Feather, that's SCK
  • MOSI connects to SPI MOSI. On the Feather, that's also MO
  • CS connects to our SPI Chip Select pin. This uses D5
  • RST connects to the Reset pin. This uses D9.
  • DC connects to our SPI Chip Select pin. This uses D6.

Metro M4 Wiring

  • Vin connects to the Metro's 5V or 3.3 pin.
  • GND connects to any one of the Metro's Gnd pins.
  • CLK connects to SPI clock. On the Metro, that's Pin 3 on the ICSP Header.
  • MOSI connects to SPI MOSI. On the Metro, that's Pin 4 on the ISCP Header.
  • CS connects to our SPI Chip Select pin. We'll be using D5
  • RST connects to our Reset pin. We'll be using D9.
  • DC connects to our SPI Chip Select pin. We'll be using D6.

CircuitPython Library Installation

First, make sure you are running the latest version of Adafruit CircuitPython for your board.

Next you'll need to install the Adafruit CircuitPython ST7789 library on your CircuitPython board.  

Click the Download Project Bundle button below to download the necessary libraries and the file in a zip file. Extract the contents of the zip file, open the folder that matches your CircuitPython version, and copy the entire lib folder and the file to your CIRCUITPY drive.

# 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 board
import terminalio
import displayio

# Starting in CircuitPython 9.x fourwire will be a seperate internal library
# rather than a component of the displayio library
    from fourwire import FourWire
except ImportError:
    from displayio import FourWire
from adafruit_display_text import label
from adafruit_st7789 import ST7789


# Release any resources currently in use for the displays

# built-in, silkscreen labelled SPI bus
spi = board.SPI()
tft_cs = board.D5
tft_dc = board.D6
tft_rst = board.D9

# If using a Raspberry Pi Pico or Pico-w
# Uncomment the below code to use GP (General Purpose) pins
# instead of D (Digital)

# import busio
# spi = busio.SPI(board.GP2, board.GP3, board.GP4)
# tft_cs = board.GP5
# tft_dc = board.GP6
# tft_rst = board.GP7

display_bus = FourWire(spi, command=tft_dc, chip_select=tft_cs, reset=tft_rst)

display = ST7789(display_bus, width=320, height=172, colstart=34, rotation=270)

# Make the display context
splash = displayio.Group()
display.root_group = splash

color_bitmap = displayio.Bitmap(display.width, display.height, 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)

# Draw a smaller inner rectangle
inner_bitmap = displayio.Bitmap(
    display.width - (BORDER_WIDTH * 2), display.height - (BORDER_WIDTH * 2), 1

inner_palette = displayio.Palette(1)
inner_palette[0] = 0xAA0088  # Purple
inner_sprite = displayio.TileGrid(
    inner_bitmap, pixel_shader=inner_palette, x=BORDER_WIDTH, y=BORDER_WIDTH

# Draw a label
text_area = label.Label(
    text="Hello World!",
    anchor_point=(0.5, 0.5),
    anchored_position=(display.width // 2, display.height // 2),

while True:

Run the Script

Once everything is wired up correctly and the files are all copied over, the script should automatically run. If not, try pressing the reset button and you should see the following on the display:

This guide was first published on Mar 29, 2022. It was last updated on Jul 17, 2024.

This page (CircuitPython Usage) was last updated on Jul 17, 2024.

Text editor powered by tinymce.