ESP32 display not working: white screen, wrong colours, dead touch

Most ESP32 display faults come from a config that does not match the board, not from broken hardware. A white screen usually means the driver or pins in TFT_eSPI's User_Setup.h do not match the board, or the backlight pin is in use; inverted or wrong colours on a Cheap Yellow Display usually mean you have the dual-USB variant with a different display controller; dead touch on the CYD comes from the XPT2046 touch controller sitting on its own SPI pins, separate from the display.

First find out which board you have

The Cheap Yellow Display (CYD) model number is printed in gold on the back, next to the speaker connector. ESP32-2432S028 is printed on more than one board, though: the original has one micro-USB port, the later board has micro-USB and USB-C and a different display controller, which also changes between batches. ESPHome's MIPI SPI driver lists all three:

ESPHome model	Controller	Board
`ESP32-2432S028`	ILI9341	Original, micro-USB only
`ESP32-2432S028-7789`	ST7789V	Dual-USB batches
`ESP32-2432S028-9342`	ILI9342	Dual-USB batches

If you cannot read the chip, try both dual-USB models.

White screen

The backlight is on but nothing is drawn. Work through these in order:

Flash a known-working example from the CYD repository. If that draws, the hardware is fine and your config is the problem.
With TFT_eSPI, the settings live in User_Setup.h inside the library folder, not in your sketch. Copy the repository's User_Setup.h for your board variant there.
In the Arduino IDE, select the board "ESP32 Dev Module".
Make sure nothing else in your code uses GPIO21; it is the backlight pin.
Try another USB cable and power supply. Flicker has the same cause.

The original board's User_Setup.h sets these values:

Setting	Value
Driver	`ILI9341_2_DRIVER`
Size	240×320
SPI port	`USE_HSPI_PORT`, 55 MHz
Pins	DC 2, MISO 12, MOSI 13, SCK 14, CS 15
Backlight	`TFT_BL 21`, on when HIGH

Wrong or inverted colours

This is the dual-USB CYD (CYD2USB). The repository's fix for TFT_eSPI is its CYD2USB User_Setup.h (ST7789_DRIVER, TFT_BGR, TFT_INVERSION_OFF), or the original setup plus tft.invertDisplay(1); and a gamma fix (ILI9341_GAMMASET). In ESPHome the repository's README gives this display block for the USB-C board:

display:
  - platform: ili9xxx
    id: esp_display
    model: ili9342
    spi_id: tft
    cs_pin: GPIO15
    dc_pin: GPIO2
    #invert_display: true (changed to below with ESPhome 2023.12.0)
    invert_colors: true

Older configs use invert_display; ESPHome renamed it to invert_colors in 2023.12.0. Rename the key when you copy an older example.

Touch not working

On the CYD, the XPT2046 touch controller has its own SPI pins: CLK 25, MOSI 32, MISO 39, CS 33 and IRQ 36. Code that expects touch on the display's SPI bus reads nothing.

In ESPHome, define a second SPI bus for touch and point the xpt2046 platform at it (full config on the Cheap Yellow Display page).
With TFT_eSPI, if you need display, touch and SD card together, the repository suggests reading touch with the XPT2046_Bitbang_Slim library.
If touch works but lands in the wrong place, calibrate. XPT2046 calibration differs from device to device; the repository's example uses x_min: 3860, x_max: 280, y_min: 340, y_max: 3860 as a start, with x reversed.

Upload and boot errors that look like display faults

Upload fails: Lower the upload speed to 115200 and install the CH340 driver. On Linux, remove brltty and add your user to the dialout group.
"Wrong boot mode detected (0x13)": The repository traces this to the capacitor on EN and recommends replacing it (C4, or C5 on the USB-C version) with 1–10 µF.

Let your agent check it

check_project reads your repo or ESPHome file, names the board and lists the display and touch pins it uses against the board's own pin map. Connect the Protoship MCP server once:

claude mcp add --transport http protoship https://mcp.protoship.dev
codex mcp add protoship --url https://mcp.protoship.dev

An agent without MCP calls GET https://protoship.dev/api/check?url=… with the link to your repo or config file.

Questions

Why is my ESP32 TFT display only white?

The backlight is on but the driver does not talk to the display. Usually TFT_eSPI's User_Setup.h in the library folder does not match the board, or another part of the code uses the backlight pin. Flash a known-working example first.

Why are the colours inverted on my Cheap Yellow Display?

You likely have the dual-USB board, which uses a different display controller. Use the CYD2USB User_Setup.h, or tft.invertDisplay(1) with the gamma fix; in ESPHome set model ili9342 and invert_colors: true.

How do I tell which Cheap Yellow Display I have?

Count the USB ports: one micro-USB is the original with an ILI9341; micro-USB plus USB-C is the later board with an ST7789 or ILI9342 depending on the batch. The model number is printed in gold on the back.

Why does touch register in the wrong place?

XPT2046 calibration is per device. Adjust x_min, x_max, y_min and y_max until touches match the drawing; on the CYD example the x axis is reversed.

Finish my build Let your agent check your project

Sources

Read on 4 November 2026.