You will need a board capable of running CircuitPython such as the Metro M0 Express or the Metro M4 Express. You can also use boards such as the Feather M0 Express or the Feather M4 Express. We recommend either the Metro M4 or the Feather M4 Express 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 Feather M0 Express or either of the Metros. If you haven't already, be sure to check out our 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. 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.

Metro M0/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

spi = board.SPI()
tft_cs = board.D5
tft_dc = board.D6

display_bus = FourWire(spi, command=tft_dc, chip_select=tft_cs, reset=board.D9)

display = ST7789(display_bus, width=280, height=240, rowstart=20, rotation=90)

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

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

# Draw a smaller inner rectangle
inner_bitmap = displayio.Bitmap(240, 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)

# Draw a label
text_group = displayio.Group(scale=3, x=37, y=120)
text = "Hello World!"
text_area = label.Label(terminalio.FONT, text=text, color=0xFFFF00)
text_group.append(text_area)  # Subgroup for text scaling

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 Sep 08, 2021. It was last updated on Jul 23, 2024.

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

Text editor powered by tinymce.