Skip to content

adafruit_st7789

Works with

Any board with SPI. Drives ST7789-based color TFT displays in 1.14", 1.3", 1.54", 1.9", and 2.0" sizes. Also used as the built-in display driver on the Feather ESP32-S3 TFT, Feather RP2040 TFT, and PyGamer.

What it does

Provides a displayio display driver for ST7789-based color TFT LCD panels over SPI. The driver handles display initialization, rotation, and display bus communication. Once set up, the display integrates fully with CircuitPython's displayio layer — you compose graphics from Group, Bitmap, TileGrid, shape, and text objects just as you would with any other displayio-compatible display.

Installing the library

Copy adafruit_st7789.mpy and the adafruit_bus_device/ folder from the bundle's lib/ folder to your board's lib/ folder.

Quick start

import board
import busio
import displayio
import terminalio
from adafruit_st7789 import ST7789
from adafruit_display_text import label

# Required before any displayio setup
displayio.release_displays()

spi = busio.SPI(clock=board.SCK, MOSI=board.MOSI)
display_bus = displayio.FourWire(
    spi, command=board.D9, chip_select=board.D10, reset=board.D11
)

# 240x135 for the 1.14" display; adjust width/height for other sizes
display = ST7789(display_bus, rotation=270, width=240, height=135, rowstart=40, colstart=53)

splash = displayio.Group()
display.root_group = splash

lbl = label.Label(terminalio.FONT, text="Hello", color=0xFFFFFF, x=80, y=67)
splash.append(lbl)

Key things you can do

What you want How to do it
Initialize display Pass FourWire bus + width, height, rotation
Set rotation rotation=0, 90, 180, or 270 at init
Show content Build a displayio.Group, set display.root_group
Adjust backlight display.brightness = 0.5 (0.0–1.0)
Draw text Use adafruit_display_text.label.Label
Draw shapes Use adafruit_display_shapes (Rect, Circle, etc.)
Load images Use displayio.OnDiskBitmap + TileGrid
Free the display displayio.release_displays() before re-init

Row and column offsets

Some ST7789 display sizes require rowstart and colstart offset values to map the panel correctly. These vary by display size; check the product guide for your specific board.

Reading the official docs

https://docs.circuitpython.org/projects/st7789/en/latest/

The constructor reference documents every initialization parameter including rowstart, colstart, bgr, and invert. When using a board where the display is already initialized by CircuitPython's built-in board.DISPLAY, you do not need this library at all — board.DISPLAY is ready to use.

Projects using this library