实训项目名称

实训时间

ESP32开发板型号

开发环境

实训小组人数

ESP32 基于 GUI-Guider 的 LVGL 界面开发与移植

2026/3/13

ESP32-S3（实操适配型号）

ESP-IDF、GUI-Guider（LVGL9.2.1/LVGL8.3.10）

2

知识点类别

具体知识点

核心原理简述

实训应用场景

（机器人相关）

备注

（易错点/重点）

引脚配置

LCD 显示屏引脚配置

通过 GPIO 引脚实现 ESP32 与 LCD 的硬件连接，配置通信、数据、控制引脚的输入输出模式

机器人触控 / 显示面板的硬件驱动，实现机器人状态可视化显示

需严格匹配 LCD 型号的引脚定义，避免接错烧毁器件

外设驱动

LCD 屏驱动、LVGL 底层驱动适配

LVGL 作为图形库提供界面渲染能力，底层驱动实现 ESP32 对 LCD 的时序和数据传输控制

机器人的图形化界面显示，如传感器数据、运动模式可视化

驱动代码需与 LVGL 版本、ESP32 芯片型号匹配

通信协议

/

/

/

/

代码开发

GUI-Guider 工程创建与界面绘制、代码移植、CMakeLists.txt 配置、分区表配置

GUI-Guider 可视化生成 LVGL 界面代码，通过文件移植、编译配置将代码适配到 ESP32 的 ESP-IDF 工程中，分区表配置为 Flash 分配存储资源

机器人的人机交互界面开发，实现按钮、文本、进度条等组件的显示与操作

CMakeLists.txt 需正确添加 UI 文件路径；中文显示需导入字体文件

其他（自定义）

LVGL 中文显示适配、ESP32 Flash 分区配置

通过导入 TrueType 字体文件为 LVGL 添加中文字体支持，修改 partitions.csv 为界面资源、程序运行分配 Flash 空间

机器人中文界面的显示，保证界面文字、资源正常存储

字体文件需选择合适的格式（ttf/woff）；分区表需在 SDK 中完成配置生效

步骤序号

实操内容

（ESP32相关）

操作步骤细节

使用工具/代码片段

操作结果

（成功/失败及原因）

1

开发环境搭建

1. 安装 ESP-IDF 开发环境并配置环境变量；2. 安装 GUI-Guider 并选择 LVGL9.2.1/LVGL8.3.10 版本；3. 验证两个环境的基础编译运行功能ESP-IDF、GUI-Guider成功，环境可正常启动并完成基础工程编译2ESP32 开发板调试

ESP-IDF、GUI-Guider

成功，环境可正常启动并完成基础工程编译

2

ESP32开发板调试

1. 连接 ESP32 开发板与电脑，安装串口驱动；2. 在 ESP-IDF 中完成开发板串口、Flash 参数配置；3. 烧录基础例程验证开发板通信正常

串口工具、ESP-IDF 烧录工具

成功，开发板可正常烧录并回传串口信息

3

外设与ESP32连接

1. 打开 GUI-Guider，选择 Simulator 设备模板、EmptyUI 应用模板；2. 设置工程名、目录、色彩深度（16/24/32bit）、面板分辨率（如 320*240）；3. 拖拽按钮、文本、进度条等组件到绘制区，通过右侧属性区调整样式；4. 导入 simkai.ttf 字体文件实现中文显示；5. 编译运行模拟器验证界面效果

GUI-Guider、simkai.ttf 字体文件

成功，模拟器可正常显示设计的中文界面及各类组件

4

代码编写与烧录

1. 在 ESP32 的 ESP-IDF 工程 main 目录下新建 ui 文件夹；2. 从 GUI-Guider 工程中复制 custom、generated 文件夹到 ui 目录；3. 修改 main/CMakeLists.txt，添加 UI 文件路径和源文件检索规则；4. 将 partitions.csv 放入工程，在 SDK 配置编辑器中选择自定义分区表并指定该文件

/

成功，文件移植完成，配置文件修改无语法错误

5

机器人功能调试

1. 清理 ESP32 工程 main.c 中无关代码；2. 在 main.c 中添加 GUI-Guider 界面初始化、显示的五行核心代码；3. 保存工程并执行编译；4. 连接开发板完成代码烧录

ESP-IDF 编译工具、烧录工具

成功，编译无报错，代码正常烧录到 ESP32

6

功能优化与完善

1. 给 ESP32 和 LCD 显示屏供电，连接硬件；2. 复位开发板，查看 LCD 屏是否显示 GUI-Guider 设计的界面；3. 测试界面组件的显示效果、中文显示是否正常

ESP32 开发板、LCD 显示屏

成功，LCD 屏正常显示设计的人机交互界面，中文、组件渲染无异常

问题序号

问题描述（ESP32相关）

排查过程

解决方案

问题总结（避免方法）

1

编译 ESP32 工程时提示 UI 相关头文件找不到

检查 CMakeLists.txt 中 INCLUDE_DIRS 是否添加了 ui/generated、ui/custom 等路径；检查文件移植路径是否正确

1. 核对并补全 CMakeLists.txt 中的 UI 文件路径；2. 确认 custom、generated 文件夹准确放在 main/ui 目录下

修改 CMakeLists.txt 后需保存，文件移植时严格按目录结构放置，避免路径层级错误

2

LCD 屏无显示，代码烧录正常

1. 检查 ESP32 与 LCD 的硬件引脚连接；2. 验证 LVGL 底层驱动代码是否适配；3. 检查界面初始化代码是否在 main.c 中正确添加

1. 重新核对引脚定义并焊接 / 接线；2. 替换与 ESP32、LCD 匹配的 LVGL 底层驱动；3. 检查并补全界面初始化核心代码

硬件连接做好标记，驱动代码提前做好版本匹配验证，代码添加后逐行核对

3

GUI-Guider 移植后中文显示为乱码 / 方块

检查是否成功导入 simkai.ttf 字体文件；检查界面组件是否选择了导入的中文字体；检查字体文件是否被正确编译到工程中

1. 重新通过 GUI-Guider 的「工具 - 导入字体」添加 simkai.ttf；2. 选中界面文本组件，在属性区选择导入的中文字体；3. 确认 CMakeLists.txt 添加了 guider_customer_fonts 路径

导入字体后在 GUI-Guider 中验证模拟器中文显示，移植后确认字体文件被纳入编译

4

烧录时提示 Flash 分区错误 / 空间不足

检查 partitions.csv 的分区大小配置；检查 SDK 中是否正确选择了自定义分区表；检查 Flash 实际容量与配置的 Flash size 是否匹配

1. 调整 partitions.csv 中各分区的 Size 参数，为 app 和 vfs/fat 分区预留足够空间；2. 在 SDK 配置编辑器中「Partition Table」选择 Custom 并指定 partitions.csv；3. 配置 Flash size 为实际硬件的容量（如 16MB）

根据工程大小合理分配分区空间，修改分区表后必须在 SDK 中生效配置

5

GUI-Guider 模拟器界面正常，ESP32 移植后组件显示错位

检查 GUI-Guider 的面板分辨率与 LCD 实际分辨率是否一致；检查 LVGL 的显示缩放配置是否正确

1. 重新在 GUI-Guider 中设置与 LCD 匹配的面板分辨率，重新生成代码并移植；2. 调整 LVGL 的显示缩放参数为 Auto Ratio/Custom Ratio 适配 LCD

GUI-Guider 工程创建时提前确认 LCD 硬件分辨率，避免分辨率不匹配导致的显示错位

项目完成情况

ESP32开发重点收获

存在的不足

后续改进计划

成功完成 GUI-Guider 到 ESP32 的代码移植，实现了基于 LVGL 的图形化界面在 LCD 屏的正常显示，界面包含各类基础组件且中文显示正常，完成了机器人人机交互界面的基础开发

1. 掌握了 GUI-Guider 的工程创建、界面绘制和中文字体适配方法；2. 学会了 ESP-IDF 工程的 CMakeLists.txt 配置和 Flash 分区表配置；3. 理解了 LVGL 图形库在 ESP32 上的移植原理和底层驱动适配逻辑；4. 积累了 ESP32 外设（LCD）驱动和代码调试的实操经验

1. 对 LVGL 底层驱动的原理理解不够深入，无法独立修改驱动适配不同型号 LCD；2. 界面交互功能开发不足，仅实现了显示，未完成按钮点击等事件响应；3. 代码优化意识不足，移植后的代码存在冗余，未做精简

1. 深入学习 LVGL 底层驱动源码，尝试适配不同分辨率、接口的 LCD 显示屏；2. 学习 GUI-Guider 的事件配置和 ESP32 的中断处理，实现界面组件的交互功能（如按钮控制机器人运动）；3. 对移植后的代码进行精简和优化，减少 Flash 和 RAM 占用；4. 尝试在界面中添加机器人传感器数据的实时显示，实现数据可视化与交互结合