Skip to content

adafruit_ili9341

Works with

Any board with SPI. Drives ILI9341-based 2.8" (240x320) and 3.2" (240x320) color TFT touchscreen displays. Commonly found on the 2.8" TFT Touch Shield and TFT FeatherWings.

What it does

Provides a displayio display driver for ILI9341-based color TFT displays over SPI. The ILI9341 drives the 2.8" and 3.2" panels that are a step up in size from 1.3"–2.0" ST7789 displays, offering a 320x240 resolution suitable for dashboards and more complex UIs. Touchscreen input (available on most ILI9341 breakouts) is handled by a separate library — either adafruit_stmpe610 for SPI touch controllers or adafruit_tsc2007 for I2C touch controllers.

Installing the library

Copy adafruit_ili9341.mpy and the adafruit_bus_device/ folder from the bundle's lib/ folder to your board's lib/ folder. For touchscreen input, also add adafruit_stmpe610.mpy (SPI) or adafruit_tsc2007.mpy (I2C) as appropriate for your hardware.

Quick start

import board
import busio
import displayio
import terminalio
from adafruit_ili9341 import ILI9341
from adafruit_display_text import label

# Required before any displayio setup
displayio.release_displays()

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

# 320x240 — the standard ILI9341 resolution
display = ILI9341(display_bus, width=320, height=240)

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

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

Key things you can do

What you want How to do it
Initialize display Pass FourWire bus + width=320, height=240
Set rotation Pass rotation=90 (or 0, 180, 270) at init
Show content Build displayio.Group, set display.root_group
Read touch (SPI) adafruit_stmpe610.Adafruit_STMPE610_SPI(spi, cs)
Read touch (I2C) adafruit_tsc2007.TSC2007(i2c)
Adjust backlight display.brightness = 0.5 (0.0–1.0)
Draw text Use adafruit_display_text.label.Label
Draw shapes Use adafruit_display_shapes classes

Reading the official docs

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

The constructor reference documents the full parameter set including rotation and auto_refresh. For touchscreen integration, check the product guide for your specific breakout to confirm which touch controller chip is installed — the STMPE610 and TSC2007 have different wiring and APIs.

Projects using this library