GUI

Enable this feature in code by turning on the swap-bytes setting.

Enable GIF decoder library in menuconfig under Component config → LVGL configuration → 3rd Party Libraries.

Select use custom malloc in menuconfig.

This error means the LCD command parameter buffer is too small, so LCD_I80_IO_FORMAT_BUF_SIZE needs to be increased.

In esp-idf/components/esp_lcd/priv_include/esp_lcd_common.h, change the default value of LCD_I80_IO_FORMAT_BUF_SIZE from 32 to 64 or higher, depending on the actual LCD command length.

This error is usually caused by a version mismatch: the current lv_adapter is based on LVGL v8, while the project dependency needs to be updated.

Change the lvgl component dependency in the .yml file to LVGL v9.

LVGL is designed around a single-threaded core. Its object tree, style cache, and render buffers are not safe for concurrent access. Directly modifying LVGL objects from Wi-Fi callbacks, MQTT callbacks, or independent sensor tasks can cause data races, random crashes, display corruption, or inconsistent UI state.

Use the mutex provided by esp_lvgl_port to protect UI operations and make sure LVGL updates run in a safe context.

#include "esp_lvgl_port.h"
#include "lvgl.h"

void mqtt_data_callback(void *handler_args, esp_event_base_t base, int32_t event_id, void *event_data) {
    esp_mqtt_event_handle_t event = event_data;

    if (lvgl_port_lock(0)) {
        lv_label_set_text(ui_label_status, "Connected");
        lv_slider_set_value(ui_slider_temp, 25, LV_ANIM_ON);
        lvgl_port_unlock();
    } else {
        ESP_LOGW("UI", "Failed to lock LVGL, update skipped");
    }
}

The key rule is that every LVGL object operation must be performed inside the protected section, and lvgl_port_unlock() must always be called after the update is complete.

By default, LVGL image and font assets are compiled into the firmware .rodata section. When many assets are used, the application image can become too large or exceed the app partition size.

Store UI assets in a dedicated Flash data partition and load them dynamically through a file system:

1. Add a dedicated ui_assets data partition in partitions.csv.
2. Mount the partition with the ESP-IDF esp_littlefs component.
3. Enable LVGL LV_USE_FS_POSIX so the LVGL file system interface can use ESP-IDF VFS paths.
4. Use the official LVGL conversion tool to generate raw .bin asset files.
5. Flash the asset files to the data partition and load them by path at runtime.

This reduces the application image size and makes UI asset updates easier to manage separately.

Configure the rotation parameters during LVGL initialization. Depending on the BSP and display driver used by the project, sw_rotate in bsp_display_cfg_t can be used to control whether software rotation is enabled.

Reference code:

bsp_display_cfg_t cfg = {
    .lvgl_port_cfg = ESP_LVGL_PORT_INIT_CONFIG(),
    .buffer_size = BSP_LCD_DRAW_BUFF_SIZE,
    .double_buffer = BSP_LCD_DRAW_BUFF_DOUBLE,
    .flags = {
        .buff_dma = false,
        .buff_spiram = true,
#if 1
        .sw_rotate = false,
#else
        .sw_rotate = true,
#endif
    }
};

When software rotation is used, make sure the LVGL configuration, BSP display interface, and panel orientation settings are consistent. Otherwise, the display direction or refresh behavior may be abnormal.

To use Lottie animations in an LVGL project, add the required component dependency and enable the Lottie feature in menuconfig.

1. Add the esp_lv_lottie_player dependency in the .yml file under the project main directory:

esp_lv_lottie_player:
  version: "*"
  override_path: "../../../../../../components/display/tools/esp_lv_lottie_player"
  public: true

2. In menuconfig, go to Component config -> LVGL configuration -> 3rd Party Libraries and enable the Lottie library option.

After these settings are applied, the project will have Lottie decoding support.