The Adafruit ESP32-S2 TFT Feather comes with a 1.14" 240x135pixel color TFT display built right in! There are a number of options for using the display. This page covers four basic ways to use the TFT display with CircuitPython: displaying the serial console/REPL, displaying simple text, displaying a bitmap, and displaying sensor data.

CircuitPython Serial Output and REPL

The most basic way to use the display happens automatically. You can view the serial console output and, when you've entered it, the REPL.

Update your code.py file to the following.

import time

while True:
    print("Hello, World!")
    time.sleep(4)

You'll see Hello, World! on the display, repeated every four seconds.

Now, if you're not already, connect to the serial console. Then, enter the REPL. You'll see the >>> prompt on the display (as well as on your computer). Try typing 1+2 into the REPL. 3!

That's all there is to using the TFT display to view the CircuitPython serial console and REPL.

Simple Text Display

The Adafruit CircuitPython Display Text library allows you to display text on the TFT display. There is a font built into CircuitPython that you can use.

Update your code.py to the following. 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, and copy the entire lib folder and the code.py file to your CIRCUITPY drive.

Your CIRCUITPY drive should resemble the following.

CIRCUITPY
# SPDX-FileCopyrightText: 2021 Tim C for Adafruit Industries
# SPDX-License-Identifier: MIT
"""
CircuitPython simple text display demo
"""
import board
import terminalio
from adafruit_display_text import bitmap_label

# Update this to change the text displayed.
text = "Hello, World!"
# Update this to change the size of the text displayed. Must be a whole number.
scale = 3

text_area = bitmap_label.Label(terminalio.FONT, text=text, scale=scale)
text_area.x = 10
text_area.y = 10
board.DISPLAY.root_group = text_area

while True:
    pass

Hello, World! is shown across the top of the display.

To change the text displayed, update the text = "Hello, World!" line. For example, to show Hello, Blinka, change it to text = "Hello, Blinka".

To change the size of the text displayed, update scale = 3. To make the text bigger, choose a large whole number. To make the text smaller, choose a smaller whole number. Minimum scale is 1.

That's all there is to showing a line of text on the TFT display using CircuitPython!

Simple Bitmap Display

CircuitPython has built in features, part of displayio, that allow you to easily display a bitmap on the TFT. This means you don't even need any external libraries!

Update your code.py to the following. 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, and copy the entire lib folderthe entire images folder, and the code.py file to your CIRCUITPY drive.

Your CIRCUITPY drive should resemble the following.

CIRCUITPY
# SPDX-FileCopyrightText: 2021 Tim C for Adafruit Industries
# SPDX-License-Identifier: MIT
"""
CircuitPython simple bitmap display demo
"""
import board
from displayio import OnDiskBitmap, TileGrid, Group

main_group = Group()
blinka_img = OnDiskBitmap("images/adafruit_blinka.bmp")

tile_grid = TileGrid(bitmap=blinka_img, pixel_shader=blinka_img.pixel_shader)
main_group.append(tile_grid)

board.DISPLAY.root_group = main_group

tile_grid.x = board.DISPLAY.width // 2 - blinka_img.width // 2

while True:
    pass

Blinka in the center of the display!

To update the bitmap file, copy your desired file to your CIRCUITPY drive. Then, change the following line to match the new filename.

blinka_img = OnDiskBitmap("images/adafruit_blinka.bmp")

For example, if you added robot.bmp to the images folder, you would change the code to read as follows.

blinka_img = OnDiskBitmap("images/robot.bmp")

That's all there is to displaying a bitmap image on the TFT display using CircuitPython!

Simple Sensor Data Display

There is an I2C LC709203 battery monitor built into the TFT Feather along with the display. The Adafruit CircuitPython LC709203F and Display Text libraries make it easy to display the sensor data on the TFT display.

You'll want to plug in a JST lipoly battery for best results.

Update your code.py to the following. 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, and copy the entire lib folder and the code.py file to your CIRCUITPY drive.

Your CIRCUITPY drive should resemble the following.

CIRCUITPY
# SPDX-FileCopyrightText: 2021 Tim C for Adafruit Industries
# SPDX-License-Identifier: MIT
"""
CircuitPython simple sensor data display demo using LC709203 battery monitor and TFT display
"""
import time
import board
import terminalio
from displayio import Group
from adafruit_display_text import bitmap_label
from adafruit_lc709203f import LC709203F

text_area = bitmap_label.Label(terminalio.FONT, scale=2)
text_area.anchor_point = (0.5, 0.5)
text_area.anchored_position = (board.DISPLAY.width // 2, board.DISPLAY.height // 2)

main_group = Group()

main_group.append(text_area)

print("LC709203F test")
print("Make sure LiPoly battery is plugged into the board!")

i2c = board.I2C()  # uses board.SCL and board.SDA
# i2c = board.STEMMA_I2C()  # For using the built-in STEMMA QT connector on a microcontroller
sensor = LC709203F(i2c)

print("IC version:", hex(sensor.ic_version))

board.DISPLAY.root_group = main_group

while True:
    text_area.text = "Battery:\n{:.1f} Volts \n{}%".format(sensor.cell_voltage, sensor.cell_percent)
    time.sleep(1)

The battery voltage and percent are shown on the display!

This code will run without a battery plugged in, and data will be shown on the display, but this data does not correlate to anything. Plug in a battery to get useful data!

That's all there is to displaying sensor data on the TFT using CircuitPython!

This guide was first published on Jan 12, 2022. It was last updated on Mar 28, 2024.

This page (TFT Basics) was last updated on Mar 28, 2024.

Text editor powered by tinymce.