GUI相关

lvgl9在代码中使能该功能，.swap bytes =true。

在 menuconfig（Component config → LVGL configuration → 3rd Party Libraries）使能GIF decoder library

menuconfig配置中选择use custom malloc。

这个报错说明 LCD 命令参数缓冲区太小，需要增大 LCD_I80_IO_FORMAT_BUF_SIZE。

可在 esp-idf/components/esp_lcd/priv_include/esp_lcd_common.h 中，将默认的 LCD_I80_IO_FORMAT_BUF_SIZE 从 32 调整为 64 或更大，具体数值取决于实际 LCD 命令长度。

该报错通常是因为当前 lv_adapter 基于 LVGL v8，而工程依赖版本不匹配导致的。

解决方法是在 .yml 文件中将依赖的 lvgl 组件版本切换为 LVGL v9。

LVGL 核心采用单线程设计，内部对象树、样式缓存和渲染缓冲区不支持并发访问。如果在 Wi-Fi、MQTT 回调或独立传感器任务中直接操作 LVGL 对象，容易产生数据竞争，表现为随机崩溃、花屏或 UI 状态异常。

建议使用 esp_lvgl_port 组件提供的互斥锁保护 UI 操作，确保 LVGL 更新在安全上下文中执行。

#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");
    }
}

关键点是：所有 LVGL 对象操作都需要进入受保护区，并且完成后必须调用 lvgl_port_unlock() 释放锁。

LVGL 默认将图片、字体等资源编译到固件的 .rodata 段。资源较多时，固件体积会明显增大，甚至超过应用分区容量。

可以将 UI 资源独立放到 Flash 数据分区，并通过文件系统接口动态加载：

1. 在 partitions.csv 中新增独立的 ui_assets 数据分区。
2. 使用 ESP-IDF 的 esp_littlefs 组件挂载该分区。
3. 开启 LVGL 的 LV_USE_FS_POSIX，让 LVGL 文件系统接口对接 ESP-IDF VFS。
4. 使用 LVGL 官方转换工具将图片、字体等资源生成 .bin 原始格式文件。
5. 将资源文件烧录到对应分区，运行时通过文件路径加载。

这种方式可以显著降低应用固件本体大小，也便于后续单独更新 UI 资源。

可以在 LVGL 初始化阶段配置显示旋转参数。根据项目使用的 BSP 和显示驱动，可通过 bsp_display_cfg_t 中的 sw_rotate 配置决定是否启用软件旋转。

参考代码：

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
    }
};

如果使用软件旋转，需要同时确认 LVGL、BSP 显示接口和屏幕方向配置一致，否则可能出现方向不一致或刷新异常。

在 LVGL 项目中使用 Lottie 动画时，需要同时添加组件依赖并在 menuconfig 中启用 Lottie 功能。

1. 在工程 main 目录下的 .yml 文件中添加 esp_lv_lottie_player 依赖：

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

2. 在 menuconfig 中进入 Component config -> LVGL configuration -> 3rd Party Libraries，使能 Lottie library 选项。

完成上述配置后，工程才具备 Lottie 解码能力。

esp_lvgl_port 提供 lvgl_port_create_c_image，可在构建阶段自动生成适配当前 LVGL 版本的 C 数组图像。

在组件的 CMakeLists.txt 末尾为每张图片添加转换配置：

lvgl_port_create_c_image("images/logo.png" "images/" "ARGB8888" "NONE")
lvgl_port_create_c_image("images/image.png" "images/" "ARGB8888" "NONE")

然后将生成的图片加入组件构建：

lvgl_port_add_images(${COMPONENT_LIB} "images/")

重新配置并构建工程后，图片会按照指定的颜色格式和压缩方式转换，并链接到应用程序中。

ESP32-P4 支持 FreeType 字体。在 menuconfig 中进入以下配置路径，启用 FreeType library 即可：

(Top) → Component config → LVGL configuration → 3rd Party Libraries
Espressif IoT Development Framework Configuration

[ ] File system on top of stdio API
[*] File system on top of posix API
(83)    Set an upper cased letter on which the drive will accessible (e.g. 'A' i.e. 65)
()      Set the working directory
(0)     >0 to cache this number of bytes in lv_fs_read()
[ ] File system on top of Win32 API
[ ] File system on top of FatFS
[ ] File system on top of LittleFS
[*] PNG decoder library
[ ] BMP decoder library
[*] JPG + Split JPG decoder library
[ ] GIF decoder library
[ ] QR code library
[*] FreeType library
    FreeType cache config  --->
[ ] Tiny TTF library
[ ] Lottie library
[ ] FFmpeg library

LVGL 支持黑白电子纸显示屏。在 menuconfig 中进入以下配置路径，将色深设置为 1: 1 byte per pixel：

(Top) → Component config → LVGL configuration → Color Settings → Color depth
Espressif IoT Development Framework Configuration

( ) 32: XRGB8888
( ) 24: RGB888
( ) 16: RGB565
( ) 8: RGB232
(X) 1: 1 byte per pixel