Skip to content
ESP32s.com
0$0.00

ESP32 CYD with PlatformIO: TFT_eSPI, Touch & LVGL Setup

Build an ESP32 CYD project in VS Code with PlatformIO by confirming the board, bringing up the LCD, checking touch input, and then adding LVGL. Keep a working configuration for each stage so that library changes do not obscure a wiring or driver problem.

Choose the correct workflow

This article describes the workflow for the classic 2.8-inch ESP32-2432S028R. RGB panels, ESP32-S3 displays and other CYD boards require their own configurations. Use the 2.8-inch board tutorial and the CYD PlatformIO and LVGL guide for model-specific setup.

1. Create a small PlatformIO project

  1. Install VS Code and the PlatformIO IDE extension.
  2. Create an Arduino-framework project using the board profile appropriate to the fitted processor.
  3. Upload a serial-only test before installing display libraries.
  4. Select the actual serial port and matching monitor baud rate.

A basic project separates platformio.ini, application code in src/main.cpp, and project-owned configuration files. Keep the project under version control so you can return to a working baseline.

2. Configure TFT_eSPI for the LCD

The LCD driver and LCD pin definitions must match the exact board. Do not copy the touch controller's SPI pins into the TFT configuration. The old generic setup in this article has been replaced by links to the model-specific guide to avoid mixing these interfaces.

Keep display settings in the project where possible, rather than relying on untracked edits inside a downloaded dependency folder. PlatformIO build flags can supply definitions or include a project configuration file; use the method supported by the selected TFT_eSPI version.

3. Test touch separately

For a board fitted with XPT2046, use an appropriate touch driver and initialize the correct SPI bus and control pins. Print raw coordinates before mapping them to pixels. A working LCD does not establish that touch has been configured correctly.

Rotation and calibration belong together. Test the center and corners, then apply the mapping appropriate to that panel. Do not present another board's calibration constants as universal defaults.

4. Add LVGL with a matching example

LVGL major versions can use different initialization and driver APIs. Choose one version and use its matching display, input and buffer examples. Record the PlatformIO platform, framework and library versions with the project.

Do not enable BOARD_HAS_PSRAM just because a sample uses it. Confirm the board's actual memory hardware and configuration. Increase buffer sizes only after the display and touch baseline works reliably.

5. Build, upload and verify

  • Build fails: inspect the first compiler error and check for mismatched library APIs or missing definitions.
  • Upload cannot connect: check the port, USB cable and boot mode before changing graphics code.
  • White or blank screen: compare the LCD driver, pins and backlight configuration with the board guide.
  • Touch fails: test the touch controller separately and check rotation and calibration.
  • UI becomes unstable: return to the baseline, then reintroduce networking, storage and widgets one at a time.

What to save with a reproducible project

Record the board marking, selected environment, dependency versions, display settings, touch calibration and the steps needed to upload. State whether the result was compiled only or also tested on physical hardware. The checks described here are a workflow; they are not a claim that every library combination has been bench-tested.

Next steps

Use the CYD pinout reference for interface identification and touchscreen troubleshooting for input problems. Compare boards with the CYD buying guide.

Related tutorials and hardware

Reference images

Sources and version references

Build settings or editor problems?

This page covers bringing up the board. Use VS Code project files and build diagnostics for workspace structure, include paths and environment selection. Check touch-coordinate sampling only after a matching display example works.