1. 为什么要在ESP32上折腾LVGL做WiFi配置界面做过ESP32项目的人都有一个共识设备联网是整个产品体验的第一道门槛。你辛辛苦苦把传感器驱动调通、把业务逻辑写完结果用户拿到手之后不知道怎么配网一切白搭。传统的做法是设备开一个热点用户手机连上去打开浏览器输入192.168.4.1在一个丑到不行的网页表单里填WiFi名称和密码。这个方案能用但体验实在谈不上好尤其是当你的设备带了一块TFT屏幕的时候还让用户掏手机去配网就显得很割裂。我这次做的事情就是直接在ESP32驱动的小屏幕上用LVGL搭一套完整的WiFi配置界面。设备开机后自动扫描周围热点列表展示在屏幕上用户点选目标热点弹出虚拟键盘输入密码点击连接状态实时反馈。整个过程不需要手机、不需要电脑屏幕本身就是交互入口。这个方案特别适合带屏的智能家居面板、工业HMI、便携式仪器这类场景。核心关键词就几个LVGL负责界面渲染和交互逻辑ESP32提供WiFi扫描与连接能力VSCode作为开发环境完成编码、编译、烧录、串口监视的闭环。整套东西跑在FreeRTOS之上LVGL的任务和WiFi事件处理分属不同优先级需要处理好任务间通信。这篇文章我会从整体架构讲到具体实现包括LVGL的移植配置、WiFi扫描的异步处理、虚拟键盘的布局技巧、中文字体裁剪、事件回调的线程安全以及我在调试过程中踩过的那些坑。不管你是刚接触LVGL的新手还是已经在STM32上用过LVGL想迁移到ESP32的老手应该都能找到有用的东西。2. 整体方案设计与技术选型思路2.1 为什么选LVGL而不是自己画UI有人可能会想不就是画个列表加个键盘吗自己用TFT_eSPI或者直接写绘图函数不就行了。我一开始也这么想过但实际动手之后发现自己画UI的工作量远超预期。一个可滚动的热点列表你需要处理触摸滑动、惯性滚动、边界回弹、列表项高亮一个虚拟键盘你需要处理按键布局、按下反馈、大小写切换、特殊字符。这些用LVGL都是现成的控件几行代码就能搭出来。LVGL的另一个优势是它的样式系统和Flex布局。你可以把界面元素按照比例排列适配不同尺寸的屏幕不需要为每个分辨率单独写坐标。我这次用的是一块320x240的SPI TFT屏后面换成480x320的屏界面代码几乎没改只是调整了几个尺寸参数。还有一点很关键LVGL的事件回调机制和定时器系统天然适合嵌入式场景。你可以用lv_timer定期刷新WiFi状态用事件回调处理按钮点击整个逻辑清晰且不容易阻塞主循环。2.2 ESP32的WiFi扫描为什么不能直接同步调用ESP32的WiFi扫描函数esp_wifi_scan_start默认是阻塞式的调用之后CPU会卡在那里等扫描完成通常需要1到3秒。如果你在LVGL的任务里直接调用这个函数界面会直接冻住触摸没反应动画停摆用户体验极差。我的做法是把WiFi扫描放到一个独立的任务里通过FreeRTOS的队列把扫描结果传回LVGL任务。具体来说创建一个低优先级的WiFi管理任务它负责调用扫描API、解析结果、发送到队列。LVGL任务在lv_timer回调里检查队列是否有新数据有的话就更新列表控件。这样界面始终保持流畅扫描过程中可以显示一个加载动画。这里有个细节需要注意esp_wifi_scan_start的第二个参数控制是否阻塞。如果你传true它会阻塞当前任务直到扫描完成传false则立即返回扫描完成后通过事件回调通知。我选择的是阻塞模式放在独立任务里因为这样代码逻辑更简单不需要处理复杂的事件状态机。2.3 VSCode ESP-IDF的开发环境搭建开发环境这块我强烈建议用VSCode ESP-IDF插件的组合而不是Arduino IDE。原因有三第一ESP-IDF提供了完整的WiFi API和FreeRTOS支持Arduino封装了一层有些底层功能用不了第二VSCode的代码补全和调试功能远超Arduino IDE第三ESP-IDF的组件管理机制方便集成LVGL这样的第三方库。安装步骤大致是这样的先从VSCode官网下载安装VSCode然后在扩展市场搜索ESP-IDF并安装。安装完成后插件会引导你下载ESP-IDF框架和工具链这个过程需要下载几百兆的文件建议在网络稳定的环境下进行。安装完成后按F1输入ESP-IDF: Show Examples可以验证环境是否正常。有一点要提醒ESP-IDF的版本选择很重要。我建议用v5.1或v5.2这两个版本对LVGL 9.x的支持比较完善。如果你用的是老版本v4.xLVGL 9的一些新特性可能编译不过。2.4 LVGL版本选择与移植方式LVGL目前主流的有两个大版本8.x和9.x。8.x更成熟稳定网上教程多9.x是新架构API有较大变化但性能和灵活性更好。我这次用的是LVGL 9.2主要考虑是它的新渲染引擎对SPI屏幕更友好而且官方对ESP32的支持文档更完善。移植方式上ESP-IDF有一个现成的组件注册表你可以直接在idf_component.yml里声明依赖编译时会自动下载LVGL。但我不建议这么做因为自动下载的版本可能和你的ESP-IDF版本不匹配而且不方便修改源码。我的做法是把LVGL源码下载到项目的components目录下手动配置lv_conf.h这样可控性最强。lv_conf.h里几个关键配置项需要根据你的硬件调整颜色深度设为LV_COLOR_DEPTH 16大多数SPI屏是RGB565显存大小根据屏幕分辨率计算如果内存紧张可以设为屏幕的1/10LVGL会分块渲染。字体方面默认的Montserrat字体只包含ASCII字符中文需要自己裁剪。3. 核心细节解析与实操要点3.1 屏幕驱动与LVGL的对接LVGL本身不直接操作硬件它需要一个显示驱动接口来把渲染好的图像数据推送到屏幕上。这个接口需要你实现两个核心函数flush_cb和read_cb如果支持触摸。flush_cb的作用是把LVGL渲染缓冲区里的像素数据写入屏幕。对于SPI屏幕通常用DMA传输来提高效率。我用的驱动芯片是ILI9341通过SPI接口连接ESP32。具体实现时在flush_cb里调用esp_lcd_panel_draw_bitmap这个函数内部会处理SPI传输和DMA。这里有个性能优化的关键点双缓冲。如果你只有一个缓冲区LVGL必须等DMA传输完成才能开始渲染下一帧这会导致帧率下降。配置两个缓冲区后LVGL可以在DMA传输的同时渲染下一帧帧率能提升30%以上。缓冲区大小建议设为屏幕分辨率的1/10比如320x240的屏幕每个缓冲区设为320x24像素。触摸部分我用的是XPT2046电阻触摸芯片通过SPI读取坐标。需要在read_cb里读取原始坐标然后做校准映射到屏幕坐标。校准参数可以通过实验确定或者用LVGL提供的校准界面。3.2 WiFi扫描的异步任务设计WiFi扫描任务的核心逻辑是这样的任务启动后等待一个信号量收到信号后调用esp_wifi_scan_start扫描完成后调用esp_wifi_scan_get_ap_records获取结果把结果打包成结构体发送到队列最后释放信号量等待下一次扫描。这里有个容易踩的坑扫描结果的数量限制。esp_wifi_scan_get_ap_records的第二个参数是你要获取的最大AP数量如果你传10但实际扫描到15个只会返回前10个。我建议先调用esp_wifi_scan_get_ap_num获取实际数量然后动态分配内存。但要注意动态分配的内存在使用完后必须释放否则会内存泄漏。另一个坑是扫描期间的WiFi状态。如果设备已经连接了一个AP扫描时会导致连接短暂中断。对于需要保持连接的场景建议在扫描前保存当前连接信息扫描后重新连接。或者使用esp_wifi_scan_start的被动扫描模式但被动扫描耗时更长。3.3 虚拟键盘的布局与中文输入LVGL自带的键盘控件lv_keyboard支持多种模式数字、大写字母、小写字母、特殊字符。对于WiFi密码输入通常只需要小写字母、数字和部分特殊符号。你可以通过lv_keyboard_set_mode切换模式或者自定义键盘映射。键盘布局上我建议把键盘放在屏幕下半部分上半部分显示当前输入的内容和光标。密码输入框要设置为密码模式显示为圆点而不是明文。LVGL的文本区域控件lv_textarea支持lv_textarea_set_password_mode开启后自动隐藏输入内容。中文输入是个麻烦事。LVGL本身不支持中文输入法如果你需要输入中文WiFi名称虽然少见但确实存在需要自己实现一个简单的拼音映射或者预设常用中文字库。我的做法是扫描结果里如果包含中文直接显示中文但输入框只支持英文和数字。毕竟WiFi密码用中文的概率极低。3.4 中文字体裁剪与显示LVGL默认字体不含中文直接显示中文会变成方块。解决办法是用LVGL官方的字体转换工具把需要的汉字裁剪成C数组。具体步骤是先确定界面中会用到的所有汉字比如“连接”“扫描”“密码”“取消”“确定”等把这些字整理成一个文本文件然后用lv_font_conv工具生成字体文件。命令大概是这样的lv_font_conv --font SourceHanSansSC-Regular.otf --size 16 --bpp 4 --format lvgl --symbols 连接扫描密码取消确定正在... --output my_font.c生成的C文件放到项目里在lv_conf.h里声明字体然后在代码里用lv_obj_set_style_text_font应用到需要的控件上。注意字体文件会占用Flash空间16px的字体每100个汉字大约占20KB根据你的Flash大小合理裁剪。4. 实操过程与核心环节实现4.1 项目目录结构与组件配置我的项目目录结构是这样的wifi_config_ui/ ├── CMakeLists.txt ├── sdkconfig ├── main/ │ ├── CMakeLists.txt │ ├── main.c │ ├── wifi_manager.c │ ├── wifi_manager.h │ ├── ui_main.c │ ├── ui_main.h │ └── fonts/ │ └── my_font.c └── components/ └── lvgl/ ├── CMakeLists.txt ├── lv_conf.h └── src/main/CMakeLists.txt里需要声明源文件和依赖组件idf_component_register( SRCS main.c wifi_manager.c ui_main.c fonts/my_font.c INCLUDE_DIRS . REQUIRES esp_wifi nvs_flash esp_lcd lvgl )components/lvgl/CMakeLists.txt里配置LVGL的编译选项关键是开启LV_CONF_PATH指向你的lv_conf.h。4.2 lv_conf.h关键配置项lv_conf.h是LVGL的核心配置文件以下是我修改过的关键项#define LV_COLOR_DEPTH 16 #define LV_MEM_SIZE (48U * 1024U) #define LV_DISP_DEF_REFR_PERIOD 30 #define LV_INDEV_DEF_READ_PERIOD 30 #define LV_USE_LOG 1 #define LV_LOG_LEVEL LV_LOG_LEVEL_WARN #define LV_FONT_MONTSERRAT_14 1 #define LV_FONT_MONTSERRAT_16 1 #define LV_FONT_CUSTOM_DECLARE LV_FONT_DECLARE(my_font) #define LV_USE_KEYBOARD 1 #define LV_USE_LIST 1 #define LV_USE_TEXTAREA 1 #define LV_USE_BAR 1 #define LV_USE_SPINNER 1LV_MEM_SIZE设为48KB这是LVGL内部使用的内存池如果界面控件多可以适当加大。LV_DISP_DEF_REFR_PERIOD设为30ms对应约33fps的刷新率对于配置界面足够了。4.3 WiFi管理任务的完整实现WiFi管理任务的核心代码如下static QueueHandle_t wifi_scan_queue; static SemaphoreHandle_t scan_start_sem; void wifi_manager_task(void *arg) { wifi_scan_queue xQueueCreate(1, sizeof(wifi_scan_result_t)); scan_start_sem xSemaphoreCreateBinary(); ESP_ERROR_CHECK(esp_netif_init()); ESP_ERROR_CHECK(esp_event_loop_create_default()); esp_netif_create_default_wifi_sta(); wifi_init_config_t cfg WIFI_INIT_CONFIG_DEFAULT(); ESP_ERROR_CHECK(esp_wifi_init(cfg)); ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA)); ESP_ERROR_CHECK(esp_wifi_start()); while (1) { if (xSemaphoreTake(scan_start_sem, portMAX_DELAY) pdTRUE) { wifi_scan_config_t scan_cfg { .ssid NULL, .bssid NULL, .channel 0, .show_hidden false, }; esp_wifi_scan_start(scan_cfg, true); uint16_t ap_count 0; esp_wifi_scan_get_ap_num(ap_count); if (ap_count MAX_AP_COUNT) ap_count MAX_AP_COUNT; wifi_ap_record_t *ap_list malloc(sizeof(wifi_ap_record_t) * ap_count); esp_wifi_scan_get_ap_records(ap_count, ap_list); wifi_scan_result_t result { .count ap_count, .ap_list ap_list, }; xQueueSend(wifi_scan_queue, result, portMAX_DELAY); } } }LVGL任务里通过xQueueReceive非阻塞地检查队列有数据就更新列表控件然后释放ap_list的内存。4.4 界面布局与事件回调主界面我用了一个lv_obj作为容器内部用Flex布局纵向排列顶部是标题栏中间是热点列表底部是扫描按钮。点击扫描按钮时释放scan_start_sem触发扫描同时显示一个Spinner动画。热点列表用lv_list控件每个列表项是一个按钮按钮的文本是SSID右侧显示信号强度图标。点击列表项时弹出一个模态窗口里面包含密码输入框和虚拟键盘。事件回调的关键是线程安全。LVGL不是线程安全的所有UI操作必须在同一个任务里执行。我的做法是在WiFi任务里只负责扫描和发送队列UI更新全部在LVGL任务里通过定时器轮询队列完成。这样避免了跨任务操作UI导致的崩溃。4.5 连接状态反馈与错误处理点击连接后界面需要实时反馈连接状态。我的做法是创建一个状态标签显示“正在连接...”、“连接成功”或“连接失败密码错误”。WiFi连接事件通过esp_event_handler注册回调在回调里更新一个全局状态变量LVGL定时器读取这个变量更新界面。错误处理方面常见的失败原因有密码错误、AP不在范围内、AP数量已达上限。对于密码错误ESP32的WiFi事件会返回WIFI_REASON_AUTH_FAIL可以据此提示用户重新输入。对于连接超时我设置了10秒的超时定时器超时后自动断开并提示。5. 常见问题与排查技巧实录5.1 屏幕花屏或颜色异常这是最常见的硬件问题。首先检查LV_COLOR_DEPTH是否和屏幕的像素格式匹配大多数SPI屏是RGB565对应16位色深。如果颜色反了比如红色显示成蓝色说明RGB顺序不对需要在flush_cb里交换字节顺序。如果屏幕出现花屏条纹通常是SPI时钟频率太高。ILI9341的SPI时钟建议不超过40MHzST7789可以到80MHz。在esp_lcd_panel_io_spi_config_t里调整pclk_hz参数从20MHz开始试稳定后再逐步提高。5.2 LVGL界面卡顿或触摸延迟卡顿的原因通常有三个刷新率设置过高、缓冲区太小、SPI传输阻塞。先把LV_DISP_DEF_REFR_PERIOD从30ms调到50ms试试如果改善明显说明是渲染压力大。缓冲区建议至少设为屏幕的1/10太小会导致频繁刷新。触摸延迟的话检查LV_INDEV_DEF_READ_PERIOD是否设得太大建议设为20-30ms。另外如果触摸读取函数里有延时或阻塞操作也会导致触摸不跟手。5.3 WiFi扫描不到热点或结果不全先确认esp_wifi_scan_start的返回值如果是ESP_ERR_WIFI_STATE说明WiFi还没初始化完成。扫描不到热点的话检查天线连接是否正常ESP32的PCB天线需要远离金属物体。结果不全的问题前面提过是esp_wifi_scan_get_ap_records的数量限制。另外如果周围AP数量超过你设置的最大值后面的AP会被丢弃。建议把MAX_AP_COUNT设为20以上但要注意内存占用。5.4 编译报错与版本兼容问题LVGL 9.x和ESP-IDF的版本兼容性是个大坑。如果你用的是ESP-IDF v4.xLVGL 9的某些API会编译不过比如lv_disp_drv_t在9.x里改成了lv_display_t。解决办法要么升级ESP-IDF到v5.x要么降级LVGL到8.x。另一个常见错误是lv_conf.h找不到检查CMakeLists.txt里是否正确设置了LV_CONF_PATH以及lv_conf.h是否在include路径下。5.5 内存不足与崩溃问题ESP32的RAM有限LVGL的控件和字体都会占用内存。如果出现malloc failed或系统重启先检查LV_MEM_SIZE是否设得太大导致堆内存不足。建议用esp_get_free_heap_size打印剩余内存根据实际情况调整。WiFi扫描结果的内存分配也要注意每次扫描后必须释放上一次的结果否则会内存泄漏。我是在LVGL任务里更新完列表后立即free掉ap_list。6. 几个提升体验的细节优化6.1 扫描时的加载动画扫描通常需要1-3秒这段时间如果界面没反应用户会以为死机了。我在扫描按钮旁边加了一个lv_spinner扫描开始时启动动画扫描完成后停止。Spinner的动画由LVGL的定时器驱动不会阻塞主循环。6.2 信号强度图标与排序热点列表按信号强度排序强的排前面。信号强度用rssi值判断大于-50dBm显示满格-50到-70显示三格-70到-85显示两格低于-85显示一格。图标可以用LVGL的Symbol字体或者自己画简单的矩形条。6.3 密码显示与隐藏切换密码输入框默认隐藏字符但用户可能想确认自己输对了。我在输入框旁边加了一个眼睛图标按钮点击切换明文和密文显示。实现方式是调用lv_textarea_set_password_mode切换。6.4 记住上次连接的热点用NVS非易失性存储保存上次成功连接的SSID和密码下次开机自动尝试连接。如果连接成功直接进入主界面失败则显示配置界面。NVS的读写很简单nvs_set_str和nvs_get_str两个函数就够了。6.5 屏幕休眠与唤醒配置界面如果长时间无操作可以关闭背光省电。用LVGL的lv_disp_get_inactive_time获取无操作时间超过30秒就调用esp_lcd_panel_disp_off关闭显示触摸中断唤醒。7. 我在实际调试中踩过的坑第一个坑是LVGL任务栈大小。默认的LVGL任务栈可能只有4KB界面复杂一点就会栈溢出。我建议至少设为8KB如果用了中文字体和大缓冲区设16KB更保险。栈溢出导致的崩溃很难排查现象是随机重启或HardFault。第二个坑是SPI总线冲突。屏幕和触摸芯片如果共用一条SPI总线需要处理好片选信号。我一开始没注意触摸读取时屏幕会闪一下后来发现是片选没拉高导致的。解决办法是在SPI传输前后正确控制CS引脚或者用不同的SPI主机。第三个坑是WiFi和LVGL的优先级。WiFi任务如果优先级太高会抢占LVGL任务的CPU时间导致界面卡顿。我的设置是LVGL任务优先级5WiFi任务优先级4这样界面流畅WiFi扫描稍慢一点但可以接受。第四个坑是字体裁剪遗漏字符。界面里用到的汉字必须全部包含在裁剪的字体文件里漏掉一个就会显示方块。我的做法是把所有界面文本整理到一个头文件里用宏定义裁剪字体时直接从这个头文件提取字符。第五个坑是NVS存储的命名空间。NVS的key有长度限制最多15个字符而且不能包含特殊字符。我一开始用SSID作为key结果SSID里有空格导致写入失败。后来改成用固定的key名比如wifi_ssid和wifi_pass。这套方案我已经在几个项目里实际用过稳定性没问题。如果你也在做类似的东西建议先把LVGL的PC模拟器跑通界面逻辑调好了再移植到ESP32上这样调试效率高很多。PC模拟器可以用VSCode直接编译运行不需要反复烧录改一行代码就能看到效果。
1. 为什么要在ESP32上折腾LVGL做WiFi配置界面做过ESP32项目的人都有一个共识设备联网是整个产品体验的第一道门槛。你辛辛苦苦把传感器驱动调通、把业务逻辑写完结果用户拿到手之后不知道怎么配网一切白搭。传统的做法是设备开一个热点用户手机连上去打开浏览器输入192.168.4.1在一个丑到不行的网页表单里填WiFi名称和密码。这个方案能用但体验实在谈不上好尤其是当你的设备带了一块TFT屏幕的时候还让用户掏手机去配网就显得很割裂。我这次做的事情就是直接在ESP32驱动的小屏幕上用LVGL搭一套完整的WiFi配置界面。设备开机后自动扫描周围热点列表展示在屏幕上用户点选目标热点弹出虚拟键盘输入密码点击连接状态实时反馈。整个过程不需要手机、不需要电脑屏幕本身就是交互入口。这个方案特别适合带屏的智能家居面板、工业HMI、便携式仪器这类场景。核心关键词就几个LVGL负责界面渲染和交互逻辑ESP32提供WiFi扫描与连接能力VSCode作为开发环境完成编码、编译、烧录、串口监视的闭环。整套东西跑在FreeRTOS之上LVGL的任务和WiFi事件处理分属不同优先级需要处理好任务间通信。这篇文章我会从整体架构讲到具体实现包括LVGL的移植配置、WiFi扫描的异步处理、虚拟键盘的布局技巧、中文字体裁剪、事件回调的线程安全以及我在调试过程中踩过的那些坑。不管你是刚接触LVGL的新手还是已经在STM32上用过LVGL想迁移到ESP32的老手应该都能找到有用的东西。2. 整体方案设计与技术选型思路2.1 为什么选LVGL而不是自己画UI有人可能会想不就是画个列表加个键盘吗自己用TFT_eSPI或者直接写绘图函数不就行了。我一开始也这么想过但实际动手之后发现自己画UI的工作量远超预期。一个可滚动的热点列表你需要处理触摸滑动、惯性滚动、边界回弹、列表项高亮一个虚拟键盘你需要处理按键布局、按下反馈、大小写切换、特殊字符。这些用LVGL都是现成的控件几行代码就能搭出来。LVGL的另一个优势是它的样式系统和Flex布局。你可以把界面元素按照比例排列适配不同尺寸的屏幕不需要为每个分辨率单独写坐标。我这次用的是一块320x240的SPI TFT屏后面换成480x320的屏界面代码几乎没改只是调整了几个尺寸参数。还有一点很关键LVGL的事件回调机制和定时器系统天然适合嵌入式场景。你可以用lv_timer定期刷新WiFi状态用事件回调处理按钮点击整个逻辑清晰且不容易阻塞主循环。2.2 ESP32的WiFi扫描为什么不能直接同步调用ESP32的WiFi扫描函数esp_wifi_scan_start默认是阻塞式的调用之后CPU会卡在那里等扫描完成通常需要1到3秒。如果你在LVGL的任务里直接调用这个函数界面会直接冻住触摸没反应动画停摆用户体验极差。我的做法是把WiFi扫描放到一个独立的任务里通过FreeRTOS的队列把扫描结果传回LVGL任务。具体来说创建一个低优先级的WiFi管理任务它负责调用扫描API、解析结果、发送到队列。LVGL任务在lv_timer回调里检查队列是否有新数据有的话就更新列表控件。这样界面始终保持流畅扫描过程中可以显示一个加载动画。这里有个细节需要注意esp_wifi_scan_start的第二个参数控制是否阻塞。如果你传true它会阻塞当前任务直到扫描完成传false则立即返回扫描完成后通过事件回调通知。我选择的是阻塞模式放在独立任务里因为这样代码逻辑更简单不需要处理复杂的事件状态机。2.3 VSCode ESP-IDF的开发环境搭建开发环境这块我强烈建议用VSCode ESP-IDF插件的组合而不是Arduino IDE。原因有三第一ESP-IDF提供了完整的WiFi API和FreeRTOS支持Arduino封装了一层有些底层功能用不了第二VSCode的代码补全和调试功能远超Arduino IDE第三ESP-IDF的组件管理机制方便集成LVGL这样的第三方库。安装步骤大致是这样的先从VSCode官网下载安装VSCode然后在扩展市场搜索ESP-IDF并安装。安装完成后插件会引导你下载ESP-IDF框架和工具链这个过程需要下载几百兆的文件建议在网络稳定的环境下进行。安装完成后按F1输入ESP-IDF: Show Examples可以验证环境是否正常。有一点要提醒ESP-IDF的版本选择很重要。我建议用v5.1或v5.2这两个版本对LVGL 9.x的支持比较完善。如果你用的是老版本v4.xLVGL 9的一些新特性可能编译不过。2.4 LVGL版本选择与移植方式LVGL目前主流的有两个大版本8.x和9.x。8.x更成熟稳定网上教程多9.x是新架构API有较大变化但性能和灵活性更好。我这次用的是LVGL 9.2主要考虑是它的新渲染引擎对SPI屏幕更友好而且官方对ESP32的支持文档更完善。移植方式上ESP-IDF有一个现成的组件注册表你可以直接在idf_component.yml里声明依赖编译时会自动下载LVGL。但我不建议这么做因为自动下载的版本可能和你的ESP-IDF版本不匹配而且不方便修改源码。我的做法是把LVGL源码下载到项目的components目录下手动配置lv_conf.h这样可控性最强。lv_conf.h里几个关键配置项需要根据你的硬件调整颜色深度设为LV_COLOR_DEPTH 16大多数SPI屏是RGB565显存大小根据屏幕分辨率计算如果内存紧张可以设为屏幕的1/10LVGL会分块渲染。字体方面默认的Montserrat字体只包含ASCII字符中文需要自己裁剪。3. 核心细节解析与实操要点3.1 屏幕驱动与LVGL的对接LVGL本身不直接操作硬件它需要一个显示驱动接口来把渲染好的图像数据推送到屏幕上。这个接口需要你实现两个核心函数flush_cb和read_cb如果支持触摸。flush_cb的作用是把LVGL渲染缓冲区里的像素数据写入屏幕。对于SPI屏幕通常用DMA传输来提高效率。我用的驱动芯片是ILI9341通过SPI接口连接ESP32。具体实现时在flush_cb里调用esp_lcd_panel_draw_bitmap这个函数内部会处理SPI传输和DMA。这里有个性能优化的关键点双缓冲。如果你只有一个缓冲区LVGL必须等DMA传输完成才能开始渲染下一帧这会导致帧率下降。配置两个缓冲区后LVGL可以在DMA传输的同时渲染下一帧帧率能提升30%以上。缓冲区大小建议设为屏幕分辨率的1/10比如320x240的屏幕每个缓冲区设为320x24像素。触摸部分我用的是XPT2046电阻触摸芯片通过SPI读取坐标。需要在read_cb里读取原始坐标然后做校准映射到屏幕坐标。校准参数可以通过实验确定或者用LVGL提供的校准界面。3.2 WiFi扫描的异步任务设计WiFi扫描任务的核心逻辑是这样的任务启动后等待一个信号量收到信号后调用esp_wifi_scan_start扫描完成后调用esp_wifi_scan_get_ap_records获取结果把结果打包成结构体发送到队列最后释放信号量等待下一次扫描。这里有个容易踩的坑扫描结果的数量限制。esp_wifi_scan_get_ap_records的第二个参数是你要获取的最大AP数量如果你传10但实际扫描到15个只会返回前10个。我建议先调用esp_wifi_scan_get_ap_num获取实际数量然后动态分配内存。但要注意动态分配的内存在使用完后必须释放否则会内存泄漏。另一个坑是扫描期间的WiFi状态。如果设备已经连接了一个AP扫描时会导致连接短暂中断。对于需要保持连接的场景建议在扫描前保存当前连接信息扫描后重新连接。或者使用esp_wifi_scan_start的被动扫描模式但被动扫描耗时更长。3.3 虚拟键盘的布局与中文输入LVGL自带的键盘控件lv_keyboard支持多种模式数字、大写字母、小写字母、特殊字符。对于WiFi密码输入通常只需要小写字母、数字和部分特殊符号。你可以通过lv_keyboard_set_mode切换模式或者自定义键盘映射。键盘布局上我建议把键盘放在屏幕下半部分上半部分显示当前输入的内容和光标。密码输入框要设置为密码模式显示为圆点而不是明文。LVGL的文本区域控件lv_textarea支持lv_textarea_set_password_mode开启后自动隐藏输入内容。中文输入是个麻烦事。LVGL本身不支持中文输入法如果你需要输入中文WiFi名称虽然少见但确实存在需要自己实现一个简单的拼音映射或者预设常用中文字库。我的做法是扫描结果里如果包含中文直接显示中文但输入框只支持英文和数字。毕竟WiFi密码用中文的概率极低。3.4 中文字体裁剪与显示LVGL默认字体不含中文直接显示中文会变成方块。解决办法是用LVGL官方的字体转换工具把需要的汉字裁剪成C数组。具体步骤是先确定界面中会用到的所有汉字比如“连接”“扫描”“密码”“取消”“确定”等把这些字整理成一个文本文件然后用lv_font_conv工具生成字体文件。命令大概是这样的lv_font_conv --font SourceHanSansSC-Regular.otf --size 16 --bpp 4 --format lvgl --symbols 连接扫描密码取消确定正在... --output my_font.c生成的C文件放到项目里在lv_conf.h里声明字体然后在代码里用lv_obj_set_style_text_font应用到需要的控件上。注意字体文件会占用Flash空间16px的字体每100个汉字大约占20KB根据你的Flash大小合理裁剪。4. 实操过程与核心环节实现4.1 项目目录结构与组件配置我的项目目录结构是这样的wifi_config_ui/ ├── CMakeLists.txt ├── sdkconfig ├── main/ │ ├── CMakeLists.txt │ ├── main.c │ ├── wifi_manager.c │ ├── wifi_manager.h │ ├── ui_main.c │ ├── ui_main.h │ └── fonts/ │ └── my_font.c └── components/ └── lvgl/ ├── CMakeLists.txt ├── lv_conf.h └── src/main/CMakeLists.txt里需要声明源文件和依赖组件idf_component_register( SRCS main.c wifi_manager.c ui_main.c fonts/my_font.c INCLUDE_DIRS . REQUIRES esp_wifi nvs_flash esp_lcd lvgl )components/lvgl/CMakeLists.txt里配置LVGL的编译选项关键是开启LV_CONF_PATH指向你的lv_conf.h。4.2 lv_conf.h关键配置项lv_conf.h是LVGL的核心配置文件以下是我修改过的关键项#define LV_COLOR_DEPTH 16 #define LV_MEM_SIZE (48U * 1024U) #define LV_DISP_DEF_REFR_PERIOD 30 #define LV_INDEV_DEF_READ_PERIOD 30 #define LV_USE_LOG 1 #define LV_LOG_LEVEL LV_LOG_LEVEL_WARN #define LV_FONT_MONTSERRAT_14 1 #define LV_FONT_MONTSERRAT_16 1 #define LV_FONT_CUSTOM_DECLARE LV_FONT_DECLARE(my_font) #define LV_USE_KEYBOARD 1 #define LV_USE_LIST 1 #define LV_USE_TEXTAREA 1 #define LV_USE_BAR 1 #define LV_USE_SPINNER 1LV_MEM_SIZE设为48KB这是LVGL内部使用的内存池如果界面控件多可以适当加大。LV_DISP_DEF_REFR_PERIOD设为30ms对应约33fps的刷新率对于配置界面足够了。4.3 WiFi管理任务的完整实现WiFi管理任务的核心代码如下static QueueHandle_t wifi_scan_queue; static SemaphoreHandle_t scan_start_sem; void wifi_manager_task(void *arg) { wifi_scan_queue xQueueCreate(1, sizeof(wifi_scan_result_t)); scan_start_sem xSemaphoreCreateBinary(); ESP_ERROR_CHECK(esp_netif_init()); ESP_ERROR_CHECK(esp_event_loop_create_default()); esp_netif_create_default_wifi_sta(); wifi_init_config_t cfg WIFI_INIT_CONFIG_DEFAULT(); ESP_ERROR_CHECK(esp_wifi_init(cfg)); ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA)); ESP_ERROR_CHECK(esp_wifi_start()); while (1) { if (xSemaphoreTake(scan_start_sem, portMAX_DELAY) pdTRUE) { wifi_scan_config_t scan_cfg { .ssid NULL, .bssid NULL, .channel 0, .show_hidden false, }; esp_wifi_scan_start(scan_cfg, true); uint16_t ap_count 0; esp_wifi_scan_get_ap_num(ap_count); if (ap_count MAX_AP_COUNT) ap_count MAX_AP_COUNT; wifi_ap_record_t *ap_list malloc(sizeof(wifi_ap_record_t) * ap_count); esp_wifi_scan_get_ap_records(ap_count, ap_list); wifi_scan_result_t result { .count ap_count, .ap_list ap_list, }; xQueueSend(wifi_scan_queue, result, portMAX_DELAY); } } }LVGL任务里通过xQueueReceive非阻塞地检查队列有数据就更新列表控件然后释放ap_list的内存。4.4 界面布局与事件回调主界面我用了一个lv_obj作为容器内部用Flex布局纵向排列顶部是标题栏中间是热点列表底部是扫描按钮。点击扫描按钮时释放scan_start_sem触发扫描同时显示一个Spinner动画。热点列表用lv_list控件每个列表项是一个按钮按钮的文本是SSID右侧显示信号强度图标。点击列表项时弹出一个模态窗口里面包含密码输入框和虚拟键盘。事件回调的关键是线程安全。LVGL不是线程安全的所有UI操作必须在同一个任务里执行。我的做法是在WiFi任务里只负责扫描和发送队列UI更新全部在LVGL任务里通过定时器轮询队列完成。这样避免了跨任务操作UI导致的崩溃。4.5 连接状态反馈与错误处理点击连接后界面需要实时反馈连接状态。我的做法是创建一个状态标签显示“正在连接...”、“连接成功”或“连接失败密码错误”。WiFi连接事件通过esp_event_handler注册回调在回调里更新一个全局状态变量LVGL定时器读取这个变量更新界面。错误处理方面常见的失败原因有密码错误、AP不在范围内、AP数量已达上限。对于密码错误ESP32的WiFi事件会返回WIFI_REASON_AUTH_FAIL可以据此提示用户重新输入。对于连接超时我设置了10秒的超时定时器超时后自动断开并提示。5. 常见问题与排查技巧实录5.1 屏幕花屏或颜色异常这是最常见的硬件问题。首先检查LV_COLOR_DEPTH是否和屏幕的像素格式匹配大多数SPI屏是RGB565对应16位色深。如果颜色反了比如红色显示成蓝色说明RGB顺序不对需要在flush_cb里交换字节顺序。如果屏幕出现花屏条纹通常是SPI时钟频率太高。ILI9341的SPI时钟建议不超过40MHzST7789可以到80MHz。在esp_lcd_panel_io_spi_config_t里调整pclk_hz参数从20MHz开始试稳定后再逐步提高。5.2 LVGL界面卡顿或触摸延迟卡顿的原因通常有三个刷新率设置过高、缓冲区太小、SPI传输阻塞。先把LV_DISP_DEF_REFR_PERIOD从30ms调到50ms试试如果改善明显说明是渲染压力大。缓冲区建议至少设为屏幕的1/10太小会导致频繁刷新。触摸延迟的话检查LV_INDEV_DEF_READ_PERIOD是否设得太大建议设为20-30ms。另外如果触摸读取函数里有延时或阻塞操作也会导致触摸不跟手。5.3 WiFi扫描不到热点或结果不全先确认esp_wifi_scan_start的返回值如果是ESP_ERR_WIFI_STATE说明WiFi还没初始化完成。扫描不到热点的话检查天线连接是否正常ESP32的PCB天线需要远离金属物体。结果不全的问题前面提过是esp_wifi_scan_get_ap_records的数量限制。另外如果周围AP数量超过你设置的最大值后面的AP会被丢弃。建议把MAX_AP_COUNT设为20以上但要注意内存占用。5.4 编译报错与版本兼容问题LVGL 9.x和ESP-IDF的版本兼容性是个大坑。如果你用的是ESP-IDF v4.xLVGL 9的某些API会编译不过比如lv_disp_drv_t在9.x里改成了lv_display_t。解决办法要么升级ESP-IDF到v5.x要么降级LVGL到8.x。另一个常见错误是lv_conf.h找不到检查CMakeLists.txt里是否正确设置了LV_CONF_PATH以及lv_conf.h是否在include路径下。5.5 内存不足与崩溃问题ESP32的RAM有限LVGL的控件和字体都会占用内存。如果出现malloc failed或系统重启先检查LV_MEM_SIZE是否设得太大导致堆内存不足。建议用esp_get_free_heap_size打印剩余内存根据实际情况调整。WiFi扫描结果的内存分配也要注意每次扫描后必须释放上一次的结果否则会内存泄漏。我是在LVGL任务里更新完列表后立即free掉ap_list。6. 几个提升体验的细节优化6.1 扫描时的加载动画扫描通常需要1-3秒这段时间如果界面没反应用户会以为死机了。我在扫描按钮旁边加了一个lv_spinner扫描开始时启动动画扫描完成后停止。Spinner的动画由LVGL的定时器驱动不会阻塞主循环。6.2 信号强度图标与排序热点列表按信号强度排序强的排前面。信号强度用rssi值判断大于-50dBm显示满格-50到-70显示三格-70到-85显示两格低于-85显示一格。图标可以用LVGL的Symbol字体或者自己画简单的矩形条。6.3 密码显示与隐藏切换密码输入框默认隐藏字符但用户可能想确认自己输对了。我在输入框旁边加了一个眼睛图标按钮点击切换明文和密文显示。实现方式是调用lv_textarea_set_password_mode切换。6.4 记住上次连接的热点用NVS非易失性存储保存上次成功连接的SSID和密码下次开机自动尝试连接。如果连接成功直接进入主界面失败则显示配置界面。NVS的读写很简单nvs_set_str和nvs_get_str两个函数就够了。6.5 屏幕休眠与唤醒配置界面如果长时间无操作可以关闭背光省电。用LVGL的lv_disp_get_inactive_time获取无操作时间超过30秒就调用esp_lcd_panel_disp_off关闭显示触摸中断唤醒。7. 我在实际调试中踩过的坑第一个坑是LVGL任务栈大小。默认的LVGL任务栈可能只有4KB界面复杂一点就会栈溢出。我建议至少设为8KB如果用了中文字体和大缓冲区设16KB更保险。栈溢出导致的崩溃很难排查现象是随机重启或HardFault。第二个坑是SPI总线冲突。屏幕和触摸芯片如果共用一条SPI总线需要处理好片选信号。我一开始没注意触摸读取时屏幕会闪一下后来发现是片选没拉高导致的。解决办法是在SPI传输前后正确控制CS引脚或者用不同的SPI主机。第三个坑是WiFi和LVGL的优先级。WiFi任务如果优先级太高会抢占LVGL任务的CPU时间导致界面卡顿。我的设置是LVGL任务优先级5WiFi任务优先级4这样界面流畅WiFi扫描稍慢一点但可以接受。第四个坑是字体裁剪遗漏字符。界面里用到的汉字必须全部包含在裁剪的字体文件里漏掉一个就会显示方块。我的做法是把所有界面文本整理到一个头文件里用宏定义裁剪字体时直接从这个头文件提取字符。第五个坑是NVS存储的命名空间。NVS的key有长度限制最多15个字符而且不能包含特殊字符。我一开始用SSID作为key结果SSID里有空格导致写入失败。后来改成用固定的key名比如wifi_ssid和wifi_pass。这套方案我已经在几个项目里实际用过稳定性没问题。如果你也在做类似的东西建议先把LVGL的PC模拟器跑通界面逻辑调好了再移植到ESP32上这样调试效率高很多。PC模拟器可以用VSCode直接编译运行不需要反复烧录改一行代码就能看到效果。
