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.
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.
- 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.
- 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 code.py 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 code.py 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 displayio
import terminalio
from adafruit_display_text import label
from fourwire import FourWire
from adafruit_st7789 import ST7789
BORDER_WIDTH = 28
TEXT_SCALE = 3
# Release any resources currently in use for the displays
displayio.release_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)
splash.append(bg_sprite)
# 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
)
splash.append(inner_sprite)
# Draw a label
text_area = label.Label(
terminalio.FONT,
text="Hello World!",
color=0xFFFF00,
scale=TEXT_SCALE,
anchor_point=(0.5, 0.5),
anchored_position=(display.width // 2, display.height // 2),
)
splash.append(text_area)
while True:
pass
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:
Page last edited January 21, 2025
Text editor powered by tinymce.
