How to use the
ST7789 240x240 display
with ESP32
Overview
The ST7789 is a 240x240 TFT display driven over SPI. It is the square equivalent of the GC9A01 and uses the same pin layout. Many modules use the same breakout board form factor.
This page covers the User_Setup_Select.h config to drive it with TFT_eSPI. Once configured, use the How to set up TFT_eSPI with ESP32 - test sketch to confirm it is working.
Wiring
| Display Pin | ESP32 Pin | Notes |
|---|---|---|
| VCC | 3.3V or 5V | Check your module - most accept both |
| GND | GND | |
| SCL / SCLK | GPIO 18 | SPI clock |
| SDA / MOSI | GPIO 23 | SPI data |
| DC | GPIO 2 | Data / command select |
| CS | GPIO 15 | Chip select |
| RST | GPIO 4 | Reset |
| MISO | GPIO 19 | Optional |
If your module has a BL (backlight) pin, tie it to 3.3V.
Config
1. Open User_Setup_Select.h
Open ~/Arduino/libraries/TFT_eSPI/User_Setup_Select.h. Comment out the default line and uncomment Setup24:
//#include <User_Setup.h> // comment this out
#include <User_Setups/Setup24_ST7789.h> // uncomment this2. Edit the pins in Setup24
Open ~/Arduino/libraries/TFT_eSPI/User_Setups/Setup24_ST7789.h. The default uses NodeMCU-style pins - replace the active pin defines with these:
| Comment out | Uncomment / add |
|---|---|
#define TFT_CS -1 | #define TFT_CS 15 |
#define TFT_DC PIN_D1 | #define TFT_DC 2 |
#define TFT_RST PIN_D4 | #define TFT_RST 4 |
Also uncomment the ESP32 MOSI/SCLK/MISO lines already present in the file:
#define TFT_MISO 19
#define TFT_MOSI 23
#define TFT_SCLK 18Notes
Display is blank but no errors
The ST7789 can be sensitive to the RST pin. Confirm GPIO 4 is wired to RST and not floating.
Image offset or wrong size
Some ST7789 modules are 240x280 or 170x320. If the image is cropped or offset, update TFT_WIDTH and TFT_HEIGHT in Setup24 to match your actual display resolution.