1. 创建第一个LVGL项目

任务目标

在ESP32上搭建LVGL图形库开发环境，完成基础初始化配置，使屏幕成功显示LVGL自带的演示界面，验证开发环境与硬件连接正常。

环境与依赖

• 硬件：ESP32开发板（如ESP32-DevKitC）、SPI接口TFT屏幕（如ILI9341，分辨率320×240）
• 软件：ESP-IDF v5.x（或Arduino-ESP32核心，本案例采用ESP-IDF）
• LVGL版本：v8.3.x（通过ESP-IDF组件管理器获取）
• 屏幕驱动：使用LVGL官方推荐的lvgl_esp32_drivers组件

项目结构

使用ESP-IDF组件管理器，在项目根目录的main/idf_component.yml中声明依赖：

dependencies:
  lvgl/lvgl: "^8.3.0"
  lvgl/lvgl_esp32_drivers: "^1.0.0"

关键完整代码

以下为main/main.c的完整实现，完成LVGL初始化、屏幕驱动绑定与演示界面加载：

#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_log.h"
#include "lvgl.h"
#include "lvgl_helpers.h"

static const char *TAG = "lvgl_demo";

void app_main(void) {
    ESP_LOGI(TAG, "Initializing LVGL...");

    /* 初始化LVGL核心 */
    lv_init();

    /* 初始化屏幕驱动（自动检测SPI引脚配置） */
    lvgl_driver_init();

    /* 获取屏幕缓冲区大小并分配 */
    size_t buf_size = LV_HOR_RES_MAX * 40;
    lv_color_t *buf = heap_caps_malloc(buf_size * sizeof(lv_color_t), MALLOC_CAP_DMA);
    assert(buf != NULL);

    /* 将显示驱动注册到LVGL */
    static lv_disp_draw_buf_t draw_buf;
    lv_disp_draw_buf_init(&draw_buf, buf, NULL, buf_size);

    static lv_disp_drv_t disp_drv;
    lv_disp_drv_init(&disp_drv);
    disp_drv.hor_res = LV_HOR_RES_MAX;
    disp_drv.ver_res = LV_VER_RES_MAX;
    disp_drv.flush_cb = disp_driver_flush;
    disp_drv.draw_buf = &draw_buf;
    lv_disp_drv_register(&disp_drv);

    /* 加载LVGL自带演示界面（widgets示例） */
    lv_demo_widgets();

    ESP_LOGI(TAG, "LVGL demo started. Screen should display UI.");

    /* LVGL心跳与任务处理 */
    while (1) {
        lv_timer_handler();
        vTaskDelay(pdMS_TO_TICKS(5));
    }
}

屏幕驱动配置

在main/Kconfig.projbuild中配置屏幕引脚与分辨率（示例为ILI9341，320×240，SPI）：

menu "LVGL Display Configuration"
    config LVGL_DISPLAY_SPI_MOSI
        int "SPI MOSI Pin"
        default 23
    config LVGL_DISPLAY_SPI_CLK
        int "SPI CLK Pin"
        default 18
    config LVGL_DISPLAY_SPI_CS
        int "SPI CS Pin"
        default 5
    config LVGL_DISPLAY_SPI_DC
        int "SPI DC Pin"
        default 26
    config LVGL_DISPLAY_SPI_RST
        int "SPI RST Pin"
        default 27
    config LVGL_DISPLAY_SPI_BL
        int "Backlight Pin"
        default 22
endmenu

编译与烧录

idf.py set-target esp32
idf.py menuconfig   # 在Component config → LVGL Configuration中确认分辨率与颜色深度
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor

验证方法

烧录成功后观察屏幕：

• 通过条件：屏幕显示LVGL widgets演示界面（包含滑块、按钮、仪表盘等交互控件），触摸或按键操作时界面有响应。
• 辅助验证：串口监视器输出LVGL demo started日志，无报错或重启循环。

常见问题

• 白屏：检查SPI引脚配置与屏幕型号是否匹配，确认背光引脚已正确使能。
• 编译报错找不到lvgl头文件：确认idf_component.yml依赖声明正确，并执行idf.py reconfigure重新解析组件。
• 显示花屏：降低SPI时钟频率（在menuconfig中调整），或增大DMA缓冲区。