ESP32 CYD in VS Code: Project Files & Build Diagnostics
This guide focuses on organizing a CYD project in VS Code and diagnosing the build. For choosing the physical board and bringing up the screen, start with the CYD PlatformIO setup guide and CYD PlatformIO & LVGL workflow. Keep the complete project together rather than copying one source file into a new environment.
Keep the project structure intact
| File or folder | Purpose |
|---|---|
| platformio.ini | Build environments, platform/framework and dependencies |
| src/ | Application source files |
| include/ | Project headers |
| lib/ | Project-local libraries where provided |
| Board/display setup files | Driver and pin definitions selected by the build |
| .pio/ | Generated build and dependency artifacts |
Open the folder containing platformio.ini in VS Code. Opening only main.cpp can leave the editor without the project context. Let the project configuration define dependencies; avoid mixing a global Arduino library copy with a different project-local version.
Inspect the selected environment
Check the environment name, board, framework, build flags and library declarations. Use the environment matching the exact screen and touch hardware. A generic esp32dev target does not by itself configure a CYD’s LCD or touch pins.
pio project config
pio run -e YOUR_ENVIRONMENT -vReplace YOUR_ENVIRONMENT with a real environment from this project. The first command displays project configuration; the verbose build exposes toolchain and include paths. Keep the full first compiler error rather than only the final “failed” line.
Diagnose common build problems
| Problem | Useful check |
|---|---|
| Header not found | Dependency declaration, include path and whether the complete project was copied |
| LVGL type/function not found | Example and installed LVGL major version |
| Build succeeds but LCD is white | Actual board, selected driver, pin definitions, reset and backlight |
| Editor underline but build succeeds | Editor indexing/environment selection; distinguish it from a compiler failure |
| Old behavior after config changes | Confirm the active environment and perform a clean rebuild if needed |
TFT_eSPI’s Read_User_Setup diagnostic reports compiled configuration, not a detected hardware model. Definitions must reach the library compilation; putting them only into an unrelated source file does not configure the library.
Make the result reproducible
Record the project commit, environment, platform/framework version and dependency revisions used for a successful build. Keep credentials out of shared repositories. If updating a dependency, change one component at a time and retain a known-working revision. See LCD driver identification before changing display flags at random.
References
Article illustrations
