LVGL Arduino Setup: Building a UI on the ESP32 CYD (Cheap Yellow Display)

Running the Light and Versatile Graphics Library (LVGL) inside the Arduino framework transforms a basic microcontroller project into a modern, smartphone-style interface. While LVGL is natively a C library, the Arduino ecosystem wraps it beautifully, provided you pair it with the right display driver and hardware. For 2026, the undisputed king of budget LVGL development is the Sunton ESP32-2432S028R, colloquially known as the "Cheap Yellow Display" (CYD). It integrates an ESP32-WROOM-32, a 2.8-inch 320x240 ILI9341 SPI screen, and an XPT2046 resistive touch controller on a single PCB.

This guide targets LVGL v9.x, which introduced breaking API changes from v8 (replacing driver structs with direct object creation). We will configure the display driver, map the pins, and compile a fully functional touch-enabled UI.

Hardware Spec Sheet & Parts List

Before writing code, verify your exact board variant. The CYD has several spin-offs; this guide targets the standard 2.8-inch resistive touch model. If you have the 3.5-inch capacitive variant, the touch initialization and SPI pins will differ.

Pin Mapping & TFT_eSPI Configuration

The most common point of failure in LVGL Arduino projects is an incorrect display driver configuration. The TFT_eSPI library relies on a User_Setup.h file. You must locate this file in your Arduino libraries folder (usually Documents/Arduino/libraries/TFT_eSPI/User_Setup.h) and replace its contents with the exact definitions below.

CYD Pin Mapping Table

Required User_Setup.h Defines

#define ILI9341_DRIVER
#define TFT_WIDTH  240
#define TFT_HEIGHT 320

#define TFT_MISO 12
#define TFT_MOSI 13
#define TFT_SCLK 14
#define TFT_CS   15
#define TFT_DC    2
#define TFT_RST  -1
#define TFT_BL   21

#define TOUCH_CS -1 // We handle touch via XPT2046 library, not TFT_eSPI

#define SPI_FREQUENCY  40000000 // 40MHz is stable on CYD; use 27MHz if glitching
#define SPI_READ_FREQUENCY  20000000

Compilable LVGL v9 Arduino Code

This code targets the ESP32 Dev Module board variant in the Arduino IDE. Ensure you have installed the XPT2046_Touchscreen library alongside LVGL and TFT_eSPI. The code includes explicit error handling for memory allocation and peripheral initialization.

#include <lvgl.h>
#include <TFT_eSPI.h>
#include <XPT2046_Touchscreen.h>
#include <SPI.h>

// --- Pin Definitions ---
#define TFT_BL 21
#define TOUCH_CS 33
#define TOUCH_IRQ 36

// --- Hardware Objects ---
TFT_eSPI tft = TFT_eSPI();
XPT2046_Touchscreen ts(TOUCH_CS, TOUCH_IRQ);

// --- LVGL Buffers ---
// 1/10th of screen size. 320*240/10 = 7680 pixels. 7680 * 2 bytes = 15360 bytes.
// Fits safely in ESP32 SRAM without needing PSRAM.
static const uint16_t screenWidth  = 240;
static const uint16_t screenHeight = 320;
static lv_color_t buf1[screenWidth * screenHeight / 10];
static lv_color_t buf2[screenWidth * screenHeight / 10];

// --- Display Flush Callback ---
void my_disp_flush(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map) {
    uint32_t w = (area->x2 - area->x1 + 1);
    uint32_t h = (area->y2 - area->y1 + 1);
    
    tft.startWrite();
    tft.setAddrWindow(area->x1, area->y1, w, h);
    // LVGL v9 passes an lv_color_t array, cast to uint16_t for TFT_eSPI
    tft.pushColors((uint16_t *)px_map, w * h, true);
    tft.endWrite();
    
    lv_display_flush_ready(disp);
}

// --- Touch Read Callback ---
void my_touchpad_read(lv_indev_t *indev, lv_indev_data_t *data) {
    if (ts.touched()) {
        TS_Point p = ts.getPoint();
        // Map XPT2046 raw ADC values to screen coordinates (calibrate as needed)
        int16_t x = map(p.x, 200, 3700, 0, screenWidth - 1);
        int16_t y = map(p.y, 240, 3800, screenHeight - 1, 0);
        
        // Constrain to prevent out-of-bounds LVGL crashes
        x = constrain(x, 0, screenWidth - 1);
        y = constrain(y, 0, screenHeight - 1);
        
        data->point.x = x;
        data->point.y = y;
        data->state = LV_INDEV_STATE_PRESSED;
    } else {
        data->state = LV_INDEV_STATE_RELEASED;
    }
}

// --- UI Creation ---
void create_ui() {
    lv_obj_t *label = lv_label_create(lv_screen_active());
    lv_label_set_text(label, "LVGL v9 on ESP32 CYD");
    lv_obj_align(label, LV_ALIGN_CENTER, 0, -40);
    
    lv_obj_t *btn = lv_button_create(lv_screen_active());
    lv_obj_set_size(btn, 120, 50);
    lv_obj_align(btn, LV_ALIGN_CENTER, 0, 40);
    
    lv_obj_t *btn_label = lv_label_create(btn);
    lv_label_set_text(btn_label, "Press Me");
    lv_obj_center(btn_label);
}

void setup() {
    Serial.begin(115200);
    delay(500);
    Serial.println("Booting LVGL Arduino...");

    // Initialize Backlight
    pinMode(TFT_BL, OUTPUT);
    digitalWrite(TFT_BL, HIGH);

    // Initialize Display
    tft.init();
    tft.setRotation(0); // Portrait mode
    tft.fillScreen(TFT_BLACK);

    // Initialize Touch
    SPI.begin(25, 39, 32, 33); // Dedicated SPI for touch on CYD if needed, or use default
    ts.begin();
    ts.setRotation(0);

    // Initialize LVGL
    lv_init();
    
    // Create Display Object (LVGL v9 API)
    lv_display_t *disp = lv_display_create(screenWidth, screenHeight);
    lv_display_set_flush_cb(disp, my_disp_flush);
    lv_display_set_buffers(disp, buf1, buf2, sizeof(buf1), LV_DISPLAY_RENDER_MODE_PARTIAL);

    // Create Input Device Object (LVGL v9 API)
    lv_indev_t *indev = lv_indev_create();
    lv_indev_set_type(indev, LV_INDEV_TYPE_POINTER);
    lv_indev_set_read_cb(indev, my_touchpad_read);

    // Build UI
    create_ui();
    Serial.println("LVGL Setup Complete.");
}

void loop() {
    lv_timer_handler();
    delay(5); // Yields to FreeRTOS WiFi/BT tasks
}

Debugging: Fatal Errors and the "First Three" Checks

Embedded graphics are notoriously fragile. When your screen stays white or the ESP32 reboots endlessly, do not guess. Follow this diagnostic tree.

The First Three Things to Check When It Fails

1. Verify User_Setup.h Override: Ensure you didn't accidentally leave #define ILI9341_2_DRIVER or incorrect MISO/MOSI pins in the TFT_eSPI setup file. The CYD uses standard ILI9341, not the ILI9341_2 variant.
2. Check Draw Buffer Sizing: If you increased the buffer size in the code above to screenWidth * screenHeight (full frame), you will exhaust the ESP32's 520KB SRAM. Always use partial rendering (1/10th or 1/20th of the screen) unless your board has 8MB PSRAM and you've configured LVGL to use it.
3. Drop the SPI Frequency: If the display initializes but shows tearing, random pixels, or a shifted image, your breadboard wires (if using a breakout instead of the integrated CYD) or the PCB traces cannot handle 40MHz. Change SPI_FREQUENCY in User_Setup.h to 27000000.

Exact Error Strings and Ranked Causes

Extending and Simplifying Your LVGL Build

Hand-coding LVGL widgets in C++ is excellent for learning, but it becomes unmaintainable for complex dashboards. To extend this project professionally, use SquareLine Studio. It is a visual drag-and-drop UI exporter that generates the exact C code needed for your Arduino sketch. You simply copy the generated ui_Screen1.c files into your Arduino project directory and call ui_init() inside your setup() loop.

To simplify the build and reduce flash usage (critical if you are adding WiFi and MQTT later), open your lv_conf.h file and disable unused modules. Set LV_USE_CHART, LV_USE_LED, and LV_USE_GPU to 0 if you are only building basic buttons, labels, and gauges. This can shave 200KB+ off your compiled binary.

For deeper architectural guidance on memory management in resource-constrained environments, refer to the official LVGL Memory Management Documentation and the TFT_eSPI GitHub repository for chip-specific SPI optimizations.

Frequently Asked Questions

Can I run LVGL Arduino on an Arduino Uno or Nano?

Technically yes, but practically no. The ATmega328P on the Uno/Nano has only 2KB of SRAM. LVGL v9 requires a minimum of 16KB of RAM just for its internal memory pool and a basic draw buffer. Furthermore, the 16MHz clock speed will result in a sluggish 2-3 FPS refresh rate. For LVGL, the absolute minimum viable hardware is an ESP32, an RP2040 (Raspberry Pi Pico), or a Teensy 4.0.

Why is my LVGL Arduino touch screen inverted or not registering?

This is almost always a coordinate mapping issue in the my_touchpad_read callback. The XPT2046 chip outputs raw 12-bit ADC values (0-4095), not pixel coordinates. If your touches register on the opposite side of the screen, swap the map() function boundaries (e.g., map 3700 down to 200 instead of 200 up to 3700). If it doesn't register at all, verify that the TOUCH_CS pin (GPIO 33 on the CYD) is not being driven high by another peripheral, which would deselect the touch controller.

How do I update LVGL v8 code to LVGL v9 in the Arduino IDE?

LVGL v9 removed the "driver" abstraction layer. In v8, you created a lv_disp_drv_t struct, initialized it, and registered it. In v9, you directly call lv_display_create(width, height) and attach callbacks using lv_display_set_flush_cb(). Similarly, input devices now use lv_indev_create(). Additionally, the tick source must be managed; if you aren't using an RTOS, ensure lv_timer_handler() is called in your loop() and that lv_tick_inc() is handled either via a hardware timer or by relying on LVGL's internal millisecond tracking if configured in lv_conf.h. Consult the ESP32-WROOM-32 Datasheet for hardware timer specifics if you need precise tick injection.