Using the 240x240 round TFT with CircuitPython involves wiring up the display to your board and loading the code and necessary libraries onto your board to see the graphics test on the display.
You can wire up the display with a breadboard or using an EYESPI breakout board.
Wiring
First, wire the TFT to your CircuitPython-compatible microcontroller. The diagram below shows wiring up to a Feather RP2040 with an EYESPI breakout:
- Feather 3.3V to breakout Vin (red wire)
- Feather GND to breakout Gnd (black wire)
- Feather SCK to breakout SCK (cyan wire)
- Feather MO to breakout MOSI (purple wire)
- Feather MI to breakout MISO (orange wire)
- Feather D9 to breakout RST (blue wire)
- Feather D6 to breakout DC (yellow wire)
- Feather D5 to breakout TCS (pink wire)
Attach the TFT screen to the EYESPI breakout with an EYESPI cable as described on the Plugging in an EYESPI Cable page.
The following is the TFT wired to a Feather RP2040 using a solderless breadboard:
- Feather 3.3V to TFT V+ (red wire)
- Feather GND to TFT G (black wire)
- Feather SCK to TFT SCK (cyan wire)
- Feather MO to TFT MOSI (purple wire)
- Feather MI to TFT MISO (orange wire)
- Feather D9 to TFT RST (blue wire)
- Feather D6 to TFT DC (yellow wire)
- Feather D5 to TFT TCS (pink wire)
CircuitPython Usage
To use with CircuitPython, you need to first install the necessary libraries, and their dependencies, into the lib folder on your CIRCUITPY drive. Then you need to update code.py with the example script.
Thankfully, we can do this in one go. In the example below, 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.
Connect the microcontroller to your computer via a known-good USB power+data cable. The board shows up as a thumb drive named CIRCUITPY. Copy the entire lib folder, blinka_round.bmp bitmap file and the code.py file to your CIRCUITPY drive.
Your CIRCUITPY/lib folder should contain the following folders and files:
- /adafruit_bitmap_font
- /adafruit_display_text
- /adafruit_imageload
- adafruit_gc9a01a.mpy
- adafruit_ticks.mpy
Once you have copied over the necessary folders and files, your CIRCUITPY drive should resemble the following:
# SPDX-FileCopyrightText: 2025 Liz Clark for Adafruit Industries
#
# SPDX-License-Identifier: MIT
import time
import board
import displayio
import terminalio
from adafruit_display_text.bitmap_label import Label
import adafruit_imageload
from fourwire import FourWire
from vectorio import Circle
from adafruit_gc9a01a import GC9A01A
spi = board.SPI()
tft_cs = board.D5
tft_dc = board.D6
tft_reset = board.D9
displayio.release_displays()
display_bus = FourWire(spi, command=tft_dc, chip_select=tft_cs, reset=tft_reset)
display = GC9A01A(display_bus, width=240, height=240)
# --- Default Shapes/Text Demo ---
main_group = displayio.Group()
display.root_group = main_group
bg_bitmap = displayio.Bitmap(240, 240, 2)
color_palette = displayio.Palette(2)
color_palette[0] = 0x00FF00 # Bright Green
color_palette[1] = 0xAA0088 # Purple
bg_sprite = displayio.TileGrid(bg_bitmap, pixel_shader=color_palette, x=0, y=0)
main_group.append(bg_sprite)
inner_circle = Circle(pixel_shader=color_palette, x=120, y=120, radius=100, color_index=1)
main_group.append(inner_circle)
text_group = displayio.Group(scale=2, x=50, y=120)
text = "Hello World!"
text_area = Label(terminalio.FONT, text=text, color=0xFFFF00)
text_group.append(text_area) # Subgroup for text scaling
main_group.append(text_group)
# --- ImageLoad Demo ---
blinka_group = displayio.Group()
bitmap, palette = adafruit_imageload.load("/blinka_round.bmp",
bitmap=displayio.Bitmap,
palette=displayio.Palette)
grid = displayio.TileGrid(bitmap, pixel_shader=palette)
blinka_group.append(grid)
while True:
# show shapes/text
display.root_group = main_group
time.sleep(2)
# show blinka bitmap
display.root_group = blinka_group
time.sleep(2)
After running the code, you should see a green circle appear on your display, followed by a smaller, inset purple circle, and finally, yellow text centered on the display saying, "Hello World!". This is followed by a bitmap of Blinka in her ouroboros circular pose. The two graphics will alternate being displayed every 2 seconds.
Page last edited February 11, 2025
Text editor powered by tinymce.
