Is ST7789 240x240 Color IPS Display Compatible with Home Assistant (ESPHome)?
Variants covered by this page
240x240 IPS panel ST7789 240x240 Color IPS Display
1.28" round panel ST7789 1.28 Round Display Module
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
The ESP32-S3 paired with the ST7789 1.54 inch 240x240 IPS TFT display provides high-fps color dashboards in Home Assistant using native ESPHome display components.
Typical SPI Wiring Reference
Standard SPI signal names. This is a bus reference, not a pinout for this specific board — check the silkscreen and datasheet for its actual pin order.
Reference circuit only. A shifter is needed when the host and peripheral run at different logic levels — check both datasheets to confirm whether this applies to your pairing.
Technical Specification Matrix
| Feature / Attribute | Specification / Status |
|---|---|
| Hardware Protocol | SPI / 3.3V GPIO |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | TFT Display Screen Backlight Dimmer Framebuffer Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Plug-and-Play |
| Factory Reset Instruction | Hold BOOT button while cycling EN button to enter USB serial flash mode. |
Wire, Flash, Adopt, Check
Wire it up
Follow the bus reference above. The host pins in the configuration are defaults — any free GPIO of the right kind will do, as long as the YAML names the pin you actually used.
Flash the configuration
Create a new device in the ESPHome dashboard (the Home Assistant add-on) and paste the configuration below into it, or save it as emb_esp32s3_st7789_esphome.yaml and run esphome run emb_esp32s3_st7789_esphome.yaml. The first flash goes over USB. If it is not detected, hold BOOT button while cycling EN button to enter USB serial flash mode to put it in download mode. Every update after that is over the air.
Adopt it in Home Assistant
Settings → Devices & Services. A node on the same network shows up as a discovered ESPHome device within a minute of joining Wi-Fi; choose Configure and enter the API encryption key from your secrets.yaml. If discovery does not find it, add the ESPHome integration by hand with the node's IP address.
Check it works
The entities on this page appear under the device in Home Assistant and update at the configured interval. The ESPHome log (Logs in the dashboard, or esphome logs) reports the setup of each component and any bus scan results at boot.
ESPHome Configuration
Starting configuration for ST7789 240x240 Color IPS Display on ESP32-S3. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for ST7789 240x240 Color IPS Display
# Host: ESP32-S3. Pin numbers below are host-side defaults — any free
# GPIO will do, and you should change them to match your own wiring.
esphome:
name: emb_esp32s3_st7789_esphome
friendly_name: "ST7789 240x240 Color IPS Display"
esp32:
board: esp32-s3-devkitc-1
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
spi:
clk_pin: GPIO12
mosi_pin: GPIO11
miso_pin: GPIO13
# The 240x240 ST7789 panels differ in where their 240 rows sit inside the
# controller's 320-row memory. If the image is offset with a band of noise,
# set offset_height: 80 (or rotate and try 0 again).
display:
- platform: ili9xxx
model: ST7789V
cs_pin: GPIO10
dc_pin: GPIO9
reset_pin: GPIO8
invert_colors: true
dimensions:
width: 240
height: 240
offset_width: 0
offset_height: 0
update_interval: 1s
lambda: |-
it.print(0, 0, id(roboto), "Hello");
font:
- file: "gfonts://Roboto"
id: roboto
size: 14
Before you flash:
the !secret values come from your
secrets.yaml, and the GPIO numbers are host-side
defaults rather than properties of this part — change them to match how you actually wired it.
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for ST7789 240x240 Color IPS Display? Submit a pull request or report corrections to our index.