Overview

LVGL can be used and configured as standard ESP-IDF component.

If you are new to ESP-IDF, follow the instructions in the ESP-IDF Programming guide to install and set up ESP-IDF on your machine.

LVGL Demo Projects for ESP32

For a quick start with LVGL and ESP32, the following pre-configured demo projects are available for specific development boards:

Refer to the README.md files in these repositories for build and flash instructions.

These demo projects use Espressif's Board Support Packages (BSPs). Additional BSPs and examples are available in the esp-bsp repository.

Using LVGL in Your ESP-IDF Project

The simplest way to integrate LVGL into your ESP-IDF project is via the esp_lvgl_port component. This component, used in the demo projects mentioned above, provides helper functions for easy installation of LVGL and display drivers. Moreover, it can add support for touch, rotary encoders, button or USB HID inputs. It simplifies power savings, screen rotation and other platform specific nuances.

The esp_lvgl_port supports LVGL versions 8 and 9 and is compatible with ESP-IDF v4.4 and above. To add it to your project, use the following command:

idf.py add-dependency "espressif/esp_lvgl_port^2.3.0"

By default, esp_lvgl_port depends on the latest stable version of LVGL, so no additional steps are needed for new projects. If a specific LVGL version is required, specify this in your project to avoid automatic updates. LVGL can also be used without esp_lvgl_port, as described below.

Obtaining LVGL

LVGL is distributed through ESP Registry, where all LVGL releases are uploaded. In case you do not want to use esp_lvgl_port, you can add LVGL component into your project with following command:

idf.py add-dependency "lvgl/lvgl^9.*"

Adjust the ^9.* part to match your LVGL version requirement. More information on version specifications can be found in the IDF Component Manager documentation. During the next build, the LVGL component will be fetched from the component registry and added to the project.

Advanced usage: Use LVGL as local component

For LVGL development and testing, it may be useful to use LVGL as a local component instead of from the ESP Registry, which offers only released versions and does not allow local modifications. To do this, clone LVGL to your project with the following command:

git submodule add https://github.com/lvgl/lvgl.git components/lvgl

Note

All components from ${project_dir}/components are automatically added to build.

Configuration

To configure LVGL, launch the configuration menu with idf.py menuconfig in your project root directory. Navigate to Component config and then LVGL configuration.

Support for Display and Touch Drivers

For successful LVGL project you will need a display driver and optionally a touch driver. Espressif provides these drivers that are built on its esp_lcd component.

These components share a common public API, making it easy to migrate your projects across different display and touch drivers.

To add a display or touch driver to your project, use a command like:

idf.py add-dependency "espressif/esp_lcd_gc9a01^2.0.0"

Using the File System under ESP-IDF

ESP-IDF uses the standard C file operation functions (fopen, fread) in all its storage related APIs. This allows seamless interoperability with LVGL when enabling the LV_USE_FS_STDIO configuration. The process is described in details below, using SPIFFS as demonstration.

  • Decide what storage system you want to use

    ESP-IDF has many, ready-to-use examples like SPIFFS , SD Card and LittleFS .

  • Re-configure your own project

    The example project should be examined for details, but in general the changes involve:

    • Enabling LVGL's STDIO file system in the configuration

      You can use menuconfig:

      • Component config → LVGL configuration → 3rd Party Libraries: enable File system on top of stdio API

      • Then select Set an upper cased letter on which the drive will accessible and set it to 65 (ASCII A)

      • You can also set Default driver letter to 65 to skip the prefix in file paths.

    • Modifying the partition table

      The exact configuration depends on your flash size and existing partitions, but the new final result should look something like this:

      Partition Table

      nvs

      data

      nvs

      0x9000

      0x6000

      phy_init

      data

      phy

      0xf000

      0x1000

      factory

      app

      factory

      0x10000

      1400k

      storage

      data

      spiffs

      400k

      Note

      If you are not using a custom partition.csv yet, it can be added via menuconfig (Partition Table → Partition Table → Custom partition table CSV).

    • Apply changes to the build system

      Some ESP file systems provide automatic generation from a host folder using CMake. The proper line(s) must be copied to main/CMakeLists.txt

      Note

      LittleFS has extra dependencies that should be added to main/idf_component.yml

  • Prepare the image files

    LVGL's LVGLImage.py Python tool can be used to convert images to binary pixel map files. It supports various formats and compression.

    Meanwhile 3rd party libraries (like LodePNG and Tiny JPEG) allow using image files without conversion.

    After preparing the files, they should be moved to the target device:

    • If properly activated a SPIFFS file system based on the spiffs_image folder should be automatically generated and later flashed to the target

    • Similar mechanism for LittleFS uses the flash_data folder, but it's only available for Linux hosts

    • For the SD Card, a traditional file browser can be used

  • Invoke proper API calls in the application code

    The core functionality requires only a few lines. The following example draws the image as well.

    #include "esp_spiffs.h"

void lv_example_image_from_esp_fs(void) {

   esp_vfs_spiffs_conf_t conf = {
      .base_path = "/spiffs",
      .partition_label = NULL,
      .max_files = 5,
      .format_if_mount_failed = false
   };

   esp_err_t ret = esp_vfs_spiffs_register(&conf);

   if (ret != ESP_OK) {
      ESP_LOGE(TAG, "Failed to register SPIFF filesystem");
      return;
   }

   lv_obj_t * obj = lv_image_create(lv_screen_active());
   lv_image_set_src(widget, "A:/spiffs/logo.bin");
   lv_obj_center(widget);
}

  • Build and flash

    After calling idf.py build flash the picture should be displayed on the screen.

Note

Changes made by menuconfig are not being tracked in the repository if the sdkconfig file is added to .gitignore, which is the default for many ESP-IDF projects. To make your configuration permanent, add the following lines to sdkconfig.defaults:

CONFIG_PARTITION_TABLE_CUSTOM=y
CONFIG_LV_USE_FS_STDIO=y
CONFIG_LV_FS_STDIO_LETTER=65
CONFIG_LV_FS_DEFAULT_DRIVER_LETTER=65

Support for Pixel Processing Accelerator

Some ESP32 chip series, like the ESP32-P4 support the Pixel Processing Accelerator hardware (PPA), which is capable of speeding-up the filling and image blending operations, this peripheral works with the DMA-2D hardware which is responsible to move the input/output buffers into/from the PPA processing engine.

Supported devices

The Espressif targets that supports the PPA are:

  • ESP32-P4 series.

Using the PPA on your ESP-IDF project

LVGL supports, in experimental level, the filling and the image blending acceleration through the PPA, the user can enable it inside their sdkconfig.default by adding the following option to enable the PPA draw unit in conjunction to the software render:

CONFIG_LV_USE_PPA=y

Save the file and then rebuild the project, this will be sufficient to add the PPA code and it will start to run automatically, so no further steps are required from the user code perspective.

Limitations

Please notice that the PPA is at experimental level where some performance gains are expected on drawing tasks related to rectangle copy or filling, while for image blending, even though it is operational, there is no significant gains, the initial cause for that according to the PPA section from reference manual is due to the DMA-2D memory bandwidth.