ESP32 开发技术分享（day4）——ESP32-S3 基于 LVGL 的界面开发实操分享

咕噜咕噜968

522人浏览 · 2026-03-12 19:09:42

咕噜咕噜968 · 2026-03-12 19:09:42 发布

本次 ESP32-S3 开发实操聚焦LVGL 图形库的移植与基础组件开发，核心完成 LVGL 相关依赖的下载配置、基础演示程序运行及下拉列表组件的开发实现，全程基于 ESP-IDF 框架操作，贴合实际项目开发流程。以下为完整实操过程、关键注意事项及项目开发思考与总结，便于技术复盘和同类型开发参考。

一、LVGL 相关依赖下载与配置

LVGL 作为嵌入式常用的轻量级图形库，在 ESP32-S3 开发中需先通过 ESP-IDF 的包管理命令下载适配的依赖包，确保库文件与开发框架、硬件环境兼容，具体操作步骤如下：

打开 ESP32-S3 对应的终端开发环境，进入当前工程根目录；
依次输入以下三条命令，分别下载 LVGL 核心库、ESP32-S3 的 LVGL 移植包、FT5x06 触摸屏驱动包，命令执行时保证网络畅通，避免依赖下载中断：
```
idf.py add-dependency "lvgl/lvgl^9.4.0"
idf.py add-dependency "espressif/esp_lvgl_port^2.6.3"
idf.py add-dependency "espressif/esp_lcd_touch_ft5x06^1.0.6"
```
命令执行完成后，查看工程中的idf_component.yml文件，若文件中成功显示上述三个依赖的名称、版本号及相关配置信息，即说明依赖包插入配置成功；若未显示，需重新执行命令并检查网络连接。

在idf_component..yml显示如图就说明插入成功了

二、LVGL 基础演示程序编写与运行

依赖配置完成后，先编写基础演示代码运行 LVGL 官方基准测试程序，验证 LVGL 库是否成功移植、硬件与图形库是否适配，具体代码编写与执行步骤如下：

1. 完整代码编写

在工程main.c文件中编写如下代码，核心实现硬件初始化、LVGL 启动及基准测试演示：

#include <stdio.h>
#include <inttypes.h>
#include "sdkconfig.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_chip_info.h"
#include "esp_flash.h"
#include "esp_system.h"
#include "LCD/lcd.h"
#include "demos/lv_demos.h"

void app_main(void)
{
    // 初始化板载I2C总线与IO扩展芯片，为LCD、触摸屏提供硬件基础
    bsp_i2c_init();
    pca9557_init();
    // 注释原有LCD初始化，由LVGL移植包完成屏显初始化，避免重复配置
    // bsp_lcd_init();

    // 启动ESP32-S3的LVGL移植驱动，完成图形库与硬件的适配
    bsp_lvgl_start();
    // 运行LVGL官方基准测试程序，验证图形库是否正常工作
    lv_demo_bechmark();

    // 死循环维持程序运行，保证LVGL界面持续显示
    while (1){
        vTaskDelay(pdMS_TO_TICKS(100));
    }
}

2. SDK 配置与程序编译烧录

代码编写完成后，打开 ESP-IDF 的 SDK 配置界面（idf.py menuconfig），根据开发板硬件参数完成基础配置，重点确认 LCD 分辨率、触摸屏型号、I2C/SPI 通信引脚与板载硬件一致，避免配置不匹配导致屏显异常；
配置完成后，依次执行编译（idf.py build）、烧录（idf.py flash）命令，烧录时选择 UART 烧录方式，确保开发板与电脑连接正常；
烧录完成后重启开发板，若板载 2.0 寸 IPS LCD 屏幕正常显示 LVGL 基准测试的动态界面，即说明 LVGL 移植成功、基础演示程序运行正常。

三、LVGL 自定义组件开发 —— 下拉列表实现

基础演示程序验证通过后，基于百问网 LVGL 官方教程进行自定义组件开发，本次以下拉列表（dropdown） 为例，完成组件的代码编写、移植与运行，具体步骤如下：

1. 参考资料获取

进入百问网 LVGL 开发教程官网（https://lvgl.100ask.net/9.2/widgets/bar.html），该网站包含 LVGL 全版本的各类组件教程、示例代码及开发技巧，可根据开发需求选择心仪的组件，复制对应的示例代码，本次选择下拉列表组件进行开发。

2. 代码移植与修改

将从官网复制的下拉列表示例代码移植到工程main.c文件中，替换原有基准测试代码，完成后的完整代码如下，核心添加事件处理函数与组件创建函数，实现下拉列表的显示与交互：

#include <stdio.h>
#include <inttypes.h>
#include "sdkconfig.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "esp_chip_info.h"
#include "esp_flash.h"
#include "esp_system.h"
#include "LCD/lcd.h"
#include "demos/lv_demos.h"

// 下拉列表事件处理函数，响应组件的数值变化事件
static void event_handler(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_target(e);
    // 检测到下拉列表选项被选择时，获取并打印选中的选项内容
    if(code == LV_EVENT_VALUE_CHANGED) {
        char buf[32];
        lv_dropdown_get_selected_str(obj, buf, sizeof(buf));
        LV_LOG_USER("Option: %s", buf);
    }
}

// 下拉列表组件创建函数，定义组件样式、选项与显示位置
void lv_example_dropdown_1(void)
{
    // 创建下拉列表组件，绑定到当前活动屏幕
    lv_obj_t * dd = lv_dropdown_create(lv_screen_active());
    // 设置下拉列表的可选选项，以换行符分隔
    lv_dropdown_set_options(dd, "Apple\n"
                                "Banana\n"
                                "Orange\n"
                                "Cherry\n"
                                "Grape\n"
                                "Raspberry\n"
                                "Melon\n"
                                "Orange\n"
                                "Lemon\n"
                                "Nuts");
    // 设置组件显示位置：屏幕上中位置，水平偏移0，垂直偏移20
    lv_obj_align(dd, LV_ALIGN_TOP_MID, 0, 20);
    // 为下拉列表添加事件回调，监听所有事件并绑定处理函数
    lv_obj_add_event_cb(dd, event_handler, LV_EVENT_ALL, NULL);
}

void app_main(void)
{
    // 硬件底层初始化，与基础演示程序一致
    bsp_i2c_init();
    pca9557_init();
    // bsp_lcd_init();

    // 启动LVGL移植驱动
    bsp_lvgl_start();
    // 调用下拉列表创建函数，显示自定义组件
    lv_example_dropdown_1();

    // 死循环维持程序运行，保证组件持续显示与交互
    while (1){
        vTaskDelay(pdMS_TO_TICKS(100));
    }
}

3. 程序编译与功能验证

代码移植修改完成后，无需额外修改 SDK 配置，直接执行编译、烧录命令；
烧录完成后重启开发板，板载 LCD 屏幕将显示一个下拉列表组件，点击组件可展开选项列表，选择任意选项后，终端会打印对应的选项名称，即说明下拉列表组件开发成功，实现了界面显示与交互反馈的核心功能。

四、实操关键注意事项

本次 LVGL 开发实操中，多个环节的细节配置直接影响开发结果，结合实操过程整理核心注意事项，规避同类型开发问题：

依赖下载环节：需严格按顺序执行依赖下载命令，且保证网络畅通，若下载中断，需删除工程中临时生成的依赖文件后重新执行；idf_component.yml文件是依赖配置的核心，需确认配置信息完整再进行后续开发。
硬件初始化环节：必须先完成bsp_i2c_init()和pca9557_init()，板载 LCD 与触摸屏均依赖 I2C 总线和 IO 扩展芯片；原有 LCD 初始化函数bsp_lcd_init()需注释，由 LVGL 移植包esp_lvgl_port完成屏显初始化，避免重复配置导致硬件冲突。
SDK 配置环节：LCD 分辨率、通信引脚、触摸屏型号需与 ESP32-S3 开发板硬件参数严格匹配，尤其是屏显相关配置，若与硬件不符，会出现屏幕白屏、花屏、组件显示不全等问题。
代码移植环节：从百问网复制的示例代码需结合 ESP-IDF 框架做适配，确保头文件引用完整（如lv_demos.h、lvgl.h）；组件显示位置需根据板载 LCD 实际分辨率调整，避免组件超出屏幕显示范围。
程序运行环节：必须保留死循环与vTaskDelay延时函数，ESP32-S3 基于 FreeRTOS 系统，无循环会导致程序运行结束，LVGL 界面无法持续显示；延时参数建议设置为 100ms，兼顾界面响应性与系统资源占用。

五、项目开发思考与总结

本次实操完成了 LVGL 在 ESP32-S3 上的完整移植与基础组件开发，从依赖配置到自定义组件实现，全程贴合嵌入式图形界面的实际项目开发流程，结合实操过程与后续项目开发需求，形成以下思考与总结：

1. 技术收获

掌握了 ESP-IDF 框架下第三方库的依赖管理方法，通过idf.py add-dependency命令可快速下载适配的开源库，无需手动拷贝库文件，大幅提升开发效率，该方法也适用于其他 ESP32-S3 开发的第三方库移植。
理解了 LVGL 图形库与 ESP32-S3 硬件的适配逻辑，通过esp_lvgl_port移植包可快速实现图形库与板载 LCD、触摸屏的对接，无需深入编写底层屏显驱动，降低了嵌入式图形界面的开发门槛。
学会了 LVGL 基础组件的开发流程，掌握了从官方教程获取示例代码、移植修改、功能验证的完整步骤，理解了 LVGL 组件 “创建 - 配置 - 事件绑定 - 显示” 的核心开发逻辑，可快速迁移到按钮、滑块、圆弧等其他 LVGL 组件的开发中。
进一步熟悉了 ESP32-S3 开发板的硬件特性，明确了 I2C 总线、IO 扩展芯片、LCD / 触摸屏的硬件关联，积累了硬件初始化与软件配置的适配经验，规避了硬件冲突、配置不匹配等常见问题。

2. 项目开发思考

库版本适配性：本次选择 LVGL 9.4.0 与esp_lvgl_port2.6.3 版本组合，版本间兼容性良好，在实际项目开发中，需优先选择 ESP 官方推荐的库版本组合，避免因版本差异导致的编译报错、功能异常等问题，若需升级版本，需提前做兼容性测试。
组件复用与封装：LVGL 组件开发中，可将常用组件（如下拉列表、按钮、显示框）进行函数封装，形成自定义组件库，在后续项目开发中直接调用，减少重复代码编写，提升项目开发效率；同时可根据项目需求修改组件样式，适配实际产品的界面设计。
硬件与软件的协同优化：ESP32-S3 开发板的 FLASH（16MB）与 PSRAM（8MB）资源充足，可支持复杂 LVGL 界面开发，但在实际项目中，需根据界面复杂度优化代码，减少不必要的组件渲染与事件监听，降低系统资源占用，保证界面运行的流畅性。
交互功能的拓展：本次下拉列表仅实现了 “选项选择 - 终端打印” 的基础交互，在实际项目中，可基于该逻辑拓展交互功能，如选择不同选项后控制板载 LED 亮灭、电机运转、传感器数据采集等，实现图形界面与硬件外设的联动，丰富产品的功能体验。

3. 后续开发规划

基于本次实操基础，继续学习 LVGL 高级组件开发（如图表、列表、弹窗），掌握组件的样式定制、布局管理技巧，实现更复杂的图形界面开发，满足实际项目的界面设计需求。
探索 LVGL 与 ESP32-S3 其他硬件外设的联动开发，结合板载姿态传感器、摄像头、音频模块，实现 “界面操作 - 硬件响应 - 数据反馈” 的全流程功能，开发更具实用性的嵌入式项目。
总结 LVGL 开发的常用代码与问题解决方案，形成专属开发模板，包括依赖配置、硬件初始化、组件封装、事件处理等模块，为后续同类型项目开发提供参考，提升开发效率。
深入学习 LVGL 底层源码与esp_lvgl_port移植包的实现逻辑，理解图形库与硬件的底层对接原理，能够自主解决 LVGL 开发中的硬件适配、性能优化等问题，提升嵌入式图形界面的开发能力。

最后效果展示：