# ESP32 display not working: white screen, touch

> Fix a white screen, wrong colours or dead touch on an ESP32 display such as the Cheap Yellow Display: TFT_eSPI User_Setup, ESPHome model, backlight pin.

Source: https://protoship.dev/guides/esp32-display-not-working

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:

1. Flash a known-working example from the CYD repository. If that draws, the hardware is fine and your config is the problem.
2. 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.
3. In the Arduino IDE, select the board "ESP32 Dev Module".
4. Make sure nothing else in your code uses GPIO21; it is the backlight pin.
5. 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](https://protoship.dev/boards/cheap-yellow-display)).
- 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](https://protoship.dev/finish#request) [Let your agent check your project](https://protoship.dev/guides/esp32-device-built-by-ai-agent#connect)

## Sources

Read on 4 November 2026.

- [CYD repo: TROUBLESHOOTING.md](https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display/blob/main/TROUBLESHOOTING.md)
- [CYD repo: SETUP.md](https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display/blob/main/SETUP.md)
- [CYD repo: cyd.md (CYD2USB, colour fix, CC resistors)](https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display/blob/main/cyd.md)
- [CYD repo: DisplayConfig/User_Setup.h (original board)](https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display/blob/main/DisplayConfig/User_Setup.h)
- [CYD repo: DisplayConfig/CYD2USB/User_Setup.h](https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display/blob/main/DisplayConfig/CYD2USB/User_Setup.h)
- [CYD repo: PINS.md](https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display/blob/main/PINS.md)
- [CYD repo: ESPHome examples README (USB-C version)](https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display/blob/main/Examples/ESPHome/README.md)
- [CYD repo: ESPHome touch demo yellowtft1.yaml](https://github.com/witnessmenow/ESP32-Cheap-Yellow-Display/blob/main/Examples/ESPHome/4-TouchDemo/yellowtft1.yaml)
- [ESPHome: MIPI SPI display models](https://esphome.io/components/display/mipi_spi/)
- [ESPHome: XPT2046 touchscreen](https://esphome.io/components/touchscreen/xpt2046/)