Building a Custom LCD UI with LVGL on ESP32-P4

A custom LCD interface can make an embedded device much easier to use, but where should you start if you want to build your own graphical user interface instead of relying on a fixed demo?

One practical approach is to use ESP-IDF for firmware development and LVGL for the graphical interface. With a compatible ESP32-P4 LCD development kit, you can start with a working display and touch input, then gradually build the application logic around your own requirements.

In this tutorial, we'll look at the main development steps, a simple LVGL interface example, and a few common issues to consider when bringing up an LCD module.

Why Use LVGL for an Embedded LCD Interface?

LVGL is an open-source graphics library designed for embedded user interfaces. It provides reusable components such as buttons, labels, sliders, menus, and other widgets, so developers do not need to implement every graphical element from scratch.

For example, an embedded control panel might need to display sensor readings, show device status, and let users change settings through a touch interface.

LVGL can handle the graphical elements and their interactions. The application firmware is still responsible for collecting sensor data, managing device states, and communicating with external hardware.

This separation makes it easier to develop and maintain an embedded GUI as the application grows.

Hardware and Software Requirements

For a basic development setup, you'll need:

• An ESP32-P4 LCD development kit with a compatible display and, if required, a touch panel
• A computer with ESP-IDF installed
• LVGL and the appropriate display integration
• Compatible LCD and touch drivers
• A USB connection for programming and debugging

The exact configuration depends on the development board. LCD modules can use different display controllers, resolutions, interfaces, and touch controllers, so the initialization code from one board may not work on another.

Before writing the application, check the documentation and example project for your specific hardware.

Step 1: Set Up the ESP-IDF Environment

Install ESP-IDF using Espressif's official instructions:

ESP-IDF Getting Started Guide for ESP32-P4

For a new project, select the ESP32-P4 target:

idf.py set-target esp32p4

If your development kit already comes with an example project, start there. A working example can help you confirm that the display, touch controller, and project configuration are correct before you add your own interface.

Step 2: Integrate LVGL

LVGL provides the widgets and drawing functions used to create the interface.

You can find the official documentation and source code here:

• LVGL Documentation
• LVGL on GitHub

In an ESP-IDF project, LVGL can be integrated through the ESP Component Manager or through the dependencies already provided by your board's example project.

Espressif also provides an LVGL port component that helps connect LVGL with the display and input-device integration:

ESP LVGL Port on GitHub

Check the component documentation and version compatibility before adding dependencies. Avoid integrating a second copy of LVGL if the existing project already includes it.

Step 3: Initialize the LCD and Touch Input

Before building the interface, verify that the hardware works independently of your application code.

The initialization process generally includes:

• Configuring the display controller and resolution
• Setting up the required display interface and buffers
• Initializing the touch controller, if the module includes touch input
• Registering the display and input device with the LVGL integration
• Running a basic display and touch test

This is often the most hardware-specific part of the project. If the LCD stays blank, check the initialization sequence, power supply, driver configuration, and interface settings before troubleshooting the LVGL widgets.

Once the display works and touch input is detected, you can move on to the application interface.

Step 4: Create a Simple LVGL Interface

Let's start with a small interface containing a title, a status label, and a button.

The following example uses LVGL 9 APIs. It assumes that LVGL and the display have already been initialized by your application.

#include "lvgl.h"

static void button_event_cb(lv_event_t * e)
{
    lv_obj_t * status_label =
        (lv_obj_t *)lv_event_get_user_data(e);

    lv_label_set_text(
        status_label,
        "Button clicked!"
    );
}

void create_home_screen(void)
{
    lv_obj_t * screen = lv_screen_active();

    lv_obj_t * title = lv_label_create(screen);
    lv_label_set_text(title, "My Embedded Device");
    lv_obj_align(
        title,
        LV_ALIGN_TOP_MID,
        0,
        24
    );

    lv_obj_t * status = lv_label_create(screen);
    lv_label_set_text(status, "System Ready");
    lv_obj_align(
        status,
        LV_ALIGN_CENTER,
        0,
        -30
    );

    lv_obj_t * button = lv_button_create(screen);
    lv_obj_set_size(button, 180, 56);
    lv_obj_align(
        button,
        LV_ALIGN_CENTER,
        0,
        30
    );

    lv_obj_t * button_label = lv_label_create(button);
    lv_label_set_text(button_label, "Test Button");
    lv_obj_center(button_label);

    lv_obj_add_event_cb(
        button,
        button_event_cb,
        LV_EVENT_CLICKED,
        status
    );
}

This example demonstrates a basic interaction: clicking the button updates the status label.

It is not a complete firmware project. You still need to call create_home_screen() from the appropriate point in your initialized application, and the board's LVGL integration must handle display refresh and input processing.

If you are using LVGL 8, check the API documentation because some functions differ between major versions.

Step 5: Build, Flash, and Test

After integrating the interface with your application's initialization code, build the firmware:

idf.py build

Then flash it to the board and start the serial monitor:

idf.py -p PORT flash monitor

Replace PORT with the serial port assigned to your development kit.

Check the following:

• Does the LCD display the expected interface?
• Does the touch panel register input?
• Does the button update the status label?
• Are there initialization errors in the serial output?

Test the interface on the actual hardware. A successful compilation alone does not confirm that the display and touch integration are working correctly.

Step 6: Connect the Interface to Real Application Logic

Once the basic GUI works, you can begin implementing the functions required by your application.

For a smart home control panel, possible extensions include:

• Displaying temperature and humidity readings
• Showing the current state of lights or other devices
• Adding pages for different rooms or settings
• Connecting buttons to GPIO or an appropriate communication interface
• Updating the display when new sensor data arrives

Remember that changing a label is not the same as controlling a physical device. Real device control requires the appropriate hardware connections, application logic, and communication implementation.

It is also worth separating the GUI from the business logic. For example, a button callback can request a lighting-state change, while a separate application component handles the actual hardware operation. This makes the code easier to test and maintain.

Common Problems During Development

The LCD remains blank.

Check the display driver, power supply, resolution, interface configuration, and initialization order. Start with a known working board example if available.

Touch input does not work.

Verify the touch controller configuration and confirm that the input device is registered correctly with LVGL.

The code compiles but the interface does not appear correctly.

Check the LVGL version, display buffer configuration, color format, and the way the board integrates display refresh.

The project cannot find an LVGL component.

Review the ESP-IDF dependency configuration and make sure you are not mixing incompatible versions or duplicating an existing component.

The interface becomes slow as it grows.

Review image sizes, font usage, rendering buffers, and how frequently widgets are updated. Keep unnecessary redraws and large graphical assets under control.

Choosing an LCD Development Kit

A development kit that combines the ESP32-P4, LCD, and touch hardware can simplify the initial setup. Instead of assembling every component independently, developers can focus on the graphical interface and application firmware.

When evaluating a kit, check the display resolution, touch support, available drivers, example code, and compatibility with your chosen ESP-IDF and LVGL versions.

APTUS provides ESP32-P4 LCD development hardware intended as a starting point for custom application development. The actual setup and software compatibility should be confirmed against the specifications and documentation of the selected kit.

For a more detailed walkthrough of the development workflow, see the ESP32-P4 LCD and LVGL application development guide.

Final Thoughts

Building a custom LCD interface with ESP32-P4 and LVGL is easier to approach when the work is divided into stages: establish the development environment, verify the hardware, integrate LVGL, build a small interface, and then connect it to the real application logic.

Starting with a simple working example also makes debugging more manageable. Once the display and touch input are stable, you can extend the interface to suit your own embedded HMI, IoT, or smart home project.

The most important lesson is to treat the GUI, hardware drivers, and application logic as connected but separate parts of the system. That structure gives you a more practical foundation for developing and maintaining a custom embedded interface.