You will need a Metro capable of running CircuitPython such as the Metro M0 Express or the Metro M4 Express. We recommend the Metro M4 Express because it's much faster and works better for driving a display. The steps should be about the same for the Metro M0 Express. If you haven't already, be sure to check out our Adafruit Metro M4 Express featuring ATSAMD51 guide.
You could use a Grand Central which also has an M4 Processor. For this board, be sure to check out our Introducing the Adafruit Grand Central M4 Express guide.
If you need WiFi capabilities for your project, you could also use the Metro M4 Airlift Lite. For this board, be sure to check out our Adafruit Metro M4 Express AirLift guide.
Preparing the Shield
Before using the TFT Shield, you will need to solder the headers on. Be sure to check out the Adafruit Guide To Excellent Soldering. After that the shield should be ready to go.
Required CircuitPython Libraries
To use this display with displayio, there are a few required libraries. You will need the display driver and since this is no ordinary display and has some additional controls, you will also need the seesaw and busdevice libraries.
First, make sure you are running the latest version of Adafruit CircuitPython for your board.
Next, you'll need to install the necessary libraries to use the hardware--carefully follow the steps to find and install these libraries from Adafruit's CircuitPython library bundle. Our introduction guide has a great page on how to install the library bundle for both express and non-express boards.
Remember for non-express boards, you'll need to manually install the necessary libraries from the bundle:
- adafruit_st7735r
- adafruit_seesaw
- adafruit_bus_device
Before continuing make sure your board's lib folder or root filesystem has the adafruit_st7735r, adafruit_seesaw and adafruit_bus_device files and folders copied over.
# SPDX-FileCopyrightText: 2021 ladyada for Adafruit Industries
# SPDX-License-Identifier: MIT
"""
This example will test out the display on the 1.8" TFT Shield
"""
import time
import board
import displayio
from adafruit_seesaw.tftshield18 import TFTShield18
from adafruit_st7735r import ST7735R
# Release any resources currently in use for the displays
displayio.release_displays()
ss = TFTShield18()
spi = board.SPI()
tft_cs = board.D10
tft_dc = board.D8
display_bus = displayio.FourWire(spi, command=tft_dc, chip_select=tft_cs)
ss.tft_reset()
display = ST7735R(display_bus, width=160, height=128, rotation=90, bgr=True)
ss.set_backlight(True)
while True:
buttons = ss.buttons
if buttons.right:
print("Button RIGHT!")
if buttons.down:
print("Button DOWN!")
if buttons.left:
print("Button LEFT!")
if buttons.up:
print("Button UP!")
if buttons.select:
print("Button SELECT!")
if buttons.a:
print("Button A!")
if buttons.b:
print("Button B!")
if buttons.c:
print("Button C!")
time.sleep(0.001)
Let's take a look at the sections of code one by one. We start by importing time, so we can pause, the board so that we can initialize SPI, displayio, the tftshield18 seesaw library, and the adafruit_ili9341 driver.
import time import board import displayio from adafruit_seesaw.tftshield18 import TFTShield18 from adafruit_st7735r import ST7735R
Next we release any previously used displays. This is important because if the Metro is reset, the display pins are not automatically released and this makes them available for use again.
displayio.release_displays()
We set up seesaw using the TFTShield18, which was written specifically for this shield to make things very easy.
ss = TFTShield18()
Next, we set the SPI object to the board's SPI with the easy shortcut function board.SPI(). By using this function, it finds the SPI module and initializes using the default SPI parameters. Next we set the Chip Select and Data/Command pins that will be used.
spi = board.SPI() tft_cs = board.D10 tft_dc = board.D8
In the next line, we set the display bus to FourWire which makes use of the SPI bus.
display_bus = displayio.FourWire(spi, command=tft_dc, chip_select=tft_cs)
Finally, we reset the display, initialize the driver with a width of 160 and a height of 128, and turn on the backlight. If we stopped at this point and ran the code, we would have a terminal that we could type at and have the screen update.
ss.tft_reset() display = ST7735R(display_bus, width=160, height=128, rotation=90, bgr=True) ss.set_backlight(True)
Finally, we place an infinite loop at the end and constantly read the buttons. If a button is detected as being pressed, a message specifies which one. Multiple buttons can be pressed at the same time. We also provide an optional small delay to allow you to adjust how quickly you want the buttons to read in case you want to debounce the output.
while True:
buttons = ss.buttons
if buttons.right:
print("Button RIGHT!")
if buttons.down:
print("Button DOWN!")
if buttons.left:
print("Button LEFT!")
if buttons.up:
print("Button UP!")
if buttons.select:
print("Button SELECT!")
if buttons.a:
print("Button A!")
if buttons.b:
print("Button B!")
if buttons.c:
print("Button C!")
time.sleep(.001)
Now go ahead and run the code. Once it's running, try pushing a few buttons and see what happens.
Where to go from here
Be sure to check out this excellent guide to CircuitPython Display Support Using displayio
