1. 为什么要在ESP32上折腾一套WiFi配置界面做过ESP32联网项目的朋友大概都有过这种体验设备焊好、固件烧进去结果换了个使用环境WiFi的SSID和密码全变了只能重新连电脑、改代码、再烧录一遍。如果设备已经装进外壳、挂在墙上这个流程简直让人抓狂。给ESP32配一块小屏幕做一个能扫描周边热点、手动输入密码的配置界面本质上就是把重新烧录这件事变成在屏幕上点几下这是产品化思维和玩具思维的分水岭。我这次要聊的就是用LVGL在ESP32上搭一套完整的WiFi配置界面开发环境选VSCode核心功能包括热点扫描、列表展示、密码输入、连接状态反馈。整套方案跑在一块带SPI接口的TFT屏上配合ESP-IDF的原生WiFi API不依赖任何云平台。适合已经会点亮屏幕、但还没把UI和网络逻辑串起来的开发者也适合想把LVGL真正用到实际项目里的朋友。很多人第一次做这个功能会掉进一个思维陷阱以为UI和WiFi是两件独立的事先画界面再调网络。实际做下来你会发现真正的难点在于两个异步系统之间的状态同步——WiFi扫描是异步的连接是异步的而LVGL的界面刷新必须在它自己的任务上下文里跑。这个矛盾处理不好轻则界面卡死重则直接看门狗复位。下面我按实际开发顺序把每个环节的坑和取舍讲清楚。2. 开发环境与工程骨架的搭建取舍2.1 VSCode ESP-IDF插件的组合为什么比纯命令行省心在VSCode里做ESP32开发主流路线是装乐鑫官方的ESP-IDF插件。相比纯命令行它最大的价值不是能编译而是把串口监视器、menuconfig、烧录、调试这几件事集成到了一个界面里。做WiFi配置界面这种需要频繁看日志的功能串口监视器的体验直接决定开发效率。安装流程大致是VSCode扩展市场搜ESP-IDF装完后按提示选择Express安装方式让它自动下载工具链和IDF本体。这里有个细节安装路径绝对不要带中文和空格我见过太多人卡在编译报错上最后发现是路径里有中文。装完后用CtrlShiftP调出命令面板运行ESP-IDF: Show Examples Projects能正常列出示例工程就说明环境通了。提示如果公司网络对下载有限制可以提前把IDF工具链离线包准备好用Advanced安装方式指定本地路径比反复重试Express安装稳得多。2.2 工程目录结构把UI和网络逻辑彻底分开新建工程后我建议一开始就把目录分好不然后面代码一多必然乱。我的习惯是这样wifi_config_ui/ ├── main/ │ ├── main.c // 入口初始化各模块 │ ├── ui/ │ │ ├── ui_main.c // LVGL界面构建 │ │ └── ui_main.h │ ├── net/ │ │ ├── wifi_mgr.c // WiFi扫描与连接逻辑 │ │ └── wifi_mgr.h │ └── CMakeLists.txt ├── components/ │ └── lvgl/ // LVGL组件 └── CMakeLists.txt这样分的好处是ui层只负责显示什么net层只负责网络状态是什么两层之间通过一个共享的状态结构体或者事件组通信。等你后面要换屏幕、换WiFi芯片改动范围能控制在一个目录里。2.3 LVGL版本选择8.x还是9.x这是个绕不开的问题。LVGL 9.x在渲染架构上做了大改API和8.x有不少差异比如lv_obj_set_style_*系列、显示驱动注册方式都变了。网上大量教程还是8.x的写法直接照抄到9.x上会编译不过。我的建议是新项目直接上9.x因为它的显示驱动接口更清晰对ESP32这种资源受限平台的内存管理也更友好。但如果你手头有大量8.x的现成代码那就先统一在8.x上别中途升级。判断版本很简单看lvgl.h里的LVGL_VERSION_MAJOR宏。下面代码里我用的是9.x的写法8.x用户注意对照调整。3. LVGL在ESP32上的移植与显示驱动对接3.1 把LVGL作为组件挂进工程LVGL官方推荐用组件方式集成。最省事的做法是把LVGL源码放到components/lvgl目录下然后在main/CMakeLists.txt里加一行REQUIRES lvgl。LVGL自带一个CMakeLists.txt能自动识别源文件不用手动一个个列。关键配置在lv_conf.h里。这个文件默认是lv_conf_template.h需要复制一份改名并把开头的#if 0改成#if 1才会生效。几个必须改的参数配置项建议值说明LV_COLOR_DEPTH16大多数SPI屏是RGB565LV_MEM_SIZE48KB以上界面复杂时适当加大LV_USE_LOG1调试期打开方便定位问题LV_TICK_CUSTOM1用ESP32的tick别用LVGL自带定时器LV_TICK_CUSTOM这项特别重要。LVGL需要一个毫秒级的时间源来驱动动画和超时如果让它自己开定时器会和FreeRTOS的任务调度打架。正确做法是把它指向ESP-IDF的esp_timer_get_time()配置成#define LV_TICK_CUSTOM 1 #define LV_TICK_CUSTOM_INCLUDE esp_timer.h #define LV_TICK_CUSTOM_SYS_TIME_EXPR (esp_timer_get_time() / 1000)3.2 显示驱动flush回调是核心LVGL不直接操作屏幕它通过一个flush_cb回调把渲染好的像素数据交给你由你负责推给屏幕。ESP32上通常用SPI接口的TFT配合esp_lcd驱动。核心逻辑是LVGL画好一块区域回调里把这块区域的数据通过SPI发出去发完调用lv_display_flush_ready()告诉LVGL可以继续。这里有个性能关键点SPI发送要用DMA。如果不用DMA刷屏时会占满CPU界面动画会明显卡顿。用esp_lcd_panel_draw_bitmap配合DMA通道能把CPU解放出来。我实测在40MHz SPI时钟下320x240的屏幕刷一屏大概十几毫秒动画基本流畅。static void lvgl_flush_cb(lv_display_t *disp, const lv_area_t *area, uint8_t *px_map) { esp_lcd_panel_handle_t panel lv_display_get_user_data(disp); esp_lcd_panel_draw_bitmap(panel, area-x1, area-y1, area-x2 1, area-y2 1, px_map); }注意area-x2 1和area-y2 1LVGL的坐标是闭区间而esp_lcd的接口是开区间这个1漏了会导致画面错位是个非常隐蔽的坑。3.3 输入设备触摸屏的注册如果屏幕带触摸比如FT6236、GT911这类电容触摸芯片需要注册一个输入设备。LVGL 9.x里用lv_indev_create()然后设置read_cb。回调里读取触摸坐标通过lv_indev_set_point返回。触摸读取建议放在一个独立任务里轮询或者用中断触发别在回调里做阻塞式I2C读取否则会拖慢整个UI。4. WiFi扫描与连接ESP-IDF原生API的异步处理4.1 扫描不是调用一下就出结果很多新手以为esp_wifi_scan_start()是同步的调用完就能拿到列表。实际上它是异步的你得注册一个事件处理函数等WIFI_EVENT_SCAN_DONE事件来了再去调esp_wifi_scan_get_ap_records()取结果。这个异步特性直接决定了UI的交互设计——扫描按钮点下去之后界面必须进入扫描中状态不能傻等。扫描的完整流程是这样的// 1. 配置扫描参数 wifi_scan_config_t scan_cfg { .ssid NULL, // NULL表示扫描所有 .bssid NULL, .channel 0, // 0表示全信道 .show_hidden false, }; esp_wifi_scan_start(scan_cfg, false); // false 非阻塞 // 2. 在事件回调里处理结果 case WIFI_EVENT_SCAN_DONE: { uint16_t ap_count 0; esp_wifi_scan_get_ap_num(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); // 把ap_list交给UI层展示 free(ap_list); break; }esp_wifi_scan_get_ap_records取完记录后内部缓存会被清空所以必须及时把数据拷走。我一般会定义一个全局的结果数组扫描完成后填充然后发一个FreeRTOS事件通知UI任务去刷新列表。4.2 扫描结果怎么排序才符合用户直觉原始扫描结果是无序的直接展示体验很差。用户最关心的是我家的WiFi在哪所以按信号强度RSSI降序排是最合理的。RSSI是负值越接近0信号越强排序时注意方向。另外同一个SSID可能有多个AP比如Mesh组网展示时可以考虑去重只保留信号最强的那条。这个处理放在net层做UI层拿到的就是干净的数据。RSSI范围信号质量界面建议-30 ~ -50极佳满格图标-50 ~ -70良好三格-70 ~ -85一般两格-85以下弱一格或警告4.3 连接过程的状态机设计连接比扫描更复杂因为它涉及多个状态认证中、获取IP中、成功、失败。ESP-IDF会依次抛出WIFI_EVENT_STA_CONNECTED、IP_EVENT_STA_GOT_IP等事件。UI层需要根据这些事件更新界面。我的做法是在wifi_mgr.c里维护一个状态枚举typedef enum { WIFI_STATE_IDLE, WIFI_STATE_SCANNING, WIFI_STATE_CONNECTING, WIFI_STATE_CONNECTED, WIFI_STATE_FAILED, } wifi_state_t;每次状态变化通过一个回调或者事件组通知UI。UI层只认这个状态不直接碰WiFi API。这样解耦之后界面逻辑会非常清晰。注意连接失败后不要立刻疯狂重试ESP-IDF内部有重连机制但如果你在应用层再叠加一层循环重连很容易触发看门狗。建议失败后给用户一个明确的重试按钮把控制权交回用户。5. 界面构建从热点列表到密码键盘的完整实现5.1 用Tab控件组织扫描和手动输入两个页面界面结构上我用LVGL的Tab控件lv_tabview分成两页一页是扫描到的热点列表一页是手动输入SSID和密码。为什么用Tab而不是两个独立屏幕因为Tab切换成本低用户不用来回跳转而且状态保持简单。lv_obj_t *tabview lv_tabview_create(lv_screen_active()); lv_obj_t *tab_scan lv_tabview_add_tab(tabview, 扫描); lv_obj_t *tab_manual lv_tabview_add_tab(tabview, 手动);Tab控件的标签文字如果显示乱码八成是字体没包含中文。LVGL默认字体只带ASCII中文需要自己用LVGL的字体转换工具生成或者用lv_font_simsun_16_cjk这类内置的CJK字体需要在lv_conf.h里开启LV_FONT_SIMSUN_16_CJK。5.2 热点列表用lv_list还是lv_table展示热点列表lv_list和lv_table都能用。我的选择是lv_list因为每个热点项需要放图标信号强度、SSID文字、可能还有加密标识lv_list的按钮项更容易塞进多个子对象。lv_table更适合规整的表格数据。每个列表项我这样构建lv_obj_t *btn lv_list_add_button(list, LV_SYMBOL_WIFI, ap-ssid); lv_obj_set_user_data(btn, (void *)ap_index); // 记住是第几个AP lv_obj_add_event_cb(btn, ap_click_cb, LV_EVENT_CLICKED, NULL);lv_obj_set_user_data这一步很关键点击回调里需要知道用户点的是哪个热点把索引存进去回调里取出来就能拿到对应的SSID和加密方式。5.3 密码输入自绘键盘还是系统键盘LVGL自带软键盘lv_keyboard直接关联到一个lv_textarea上就能用。但默认键盘是英文布局密码输入够用。如果要做中文SSID输入就得自己扩展键盘布局工作量不小。我的建议是密码输入用自带键盘SSID输入如果只支持英文就用自带键盘要支持中文再考虑自绘。键盘弹出时会占据屏幕下半部分记得把输入框往上挪别被挡住。lv_obj_t *kb lv_keyboard_create(lv_screen_active()); lv_obj_t *ta lv_textarea_create(tab_manual); lv_keyboard_set_textarea(kb, ta); lv_obj_add_flag(kb, LV_OBJ_FLAG_HIDDEN); // 默认隐藏点击输入框再显示密码框要设置lv_textarea_set_password_mode(ta, true)这样输入的内容显示成圆点符合用户习惯。5.4 连接状态反馈别让用户猜点击某个热点后界面要立刻给出反馈。我的做法是弹一个模态框lv_msgbox显示正在连接 xxx同时把扫描列表禁用防止用户重复点击。连接成功就关闭模态框并显示IP失败就改成错误提示加一个重试按钮。这里有个体验细节连接过程可能持续几秒模态框里最好放一个转圈动画lv_spinner让用户知道程序没死。LVGL的spinner用起来很简单创建后自动转。6. 踩坑实录那些让我熬夜的异步与内存问题6.1 LVGL任务和WiFi事件的线程冲突这是最容易出问题的地方。LVGL不是线程安全的所有对UI对象的操作必须在同一个任务里做。而WiFi事件回调运行在ESP-IDF的事件任务上下文里如果你在回调里直接调lv_label_set_text轻则画面错乱重则直接崩溃。正确做法是WiFi回调里只更新状态变量然后通过xEventGroupSetBits或者队列通知UI任务由UI任务去刷新界面。我一般会开一个专门的LVGL任务里面跑lv_timer_handler()同时处理来自网络层的消息。void lvgl_task(void *arg) { while (1) { lv_timer_handler(); // 检查网络层消息队列 ui_msg_t msg; if (xQueueReceive(ui_queue, msg, 0) pdTRUE) { handle_ui_msg(msg); } vTaskDelay(pdMS_TO_TICKS(5)); } }lv_timer_handler的调用间隔建议5ms左右太频繁浪费CPU太慢动画卡顿。6.2 扫描结果内存泄漏的隐蔽陷阱前面提到esp_wifi_scan_get_ap_records取完数据后内部缓存会清空。但如果你在扫描完成后没有及时取数据或者取了没释放自己malloc的数组内存就会一点点漏掉。ESP32的堆本来就不大跑几次扫描就可能OOM。我的习惯是扫描结果数组用静态分配大小按最大AP数一般20个够用固定避免频繁malloc/free。如果一定要动态分配务必在拷贝完数据后立刻free。提示可以在menuconfig里打开Heap Poisoning和Heap Tracing跑几轮扫描后看堆使用曲线如果只涨不降基本就是漏了。6.3 看门狗复位任务阻塞的典型症状调试阶段我最常遇到的复位是Task watchdog got triggered。原因通常是某个任务长时间不让出CPU。在WiFi配置界面这个场景里常见诱因有两个一是在LVGL任务里做了阻塞式操作比如同步等待WiFi连接结果二是flush回调里SPI发送没走DMA且数据量大。解决办法LVGL任务里绝不做阻塞等待所有等待都用状态机超时flush回调确保用DMA并且lv_display_flush_ready要在DMA传输完成中断里调用而不是发送函数返回后就调。6.4 中文SSID显示乱码的排查链路中文SSID乱码是个高频问题。排查顺序应该是先确认字体是否包含中文字形用lv_font_get_glyph_dsc查某个汉字是否存在再确认SSID的编码是不是UTF-8ESP-IDF返回的SSID是原始字节可能是GBK最后确认textarea和label用的字体是否一致。如果SSID是GBK编码需要转成UTF-8再交给LVGL。ESP-IDF没有内置GBK转UTF-8得自己带一个转换表或者用轻量库。这一步不做中文SSID永远是乱码。7. 几个提升实用性的进阶思路7.1 把配置结果持久化到NVS用户配好WiFi后下次开机应该自动连接而不是重新配。ESP-IDF的NVS非易失存储就是干这个的。连接成功后把SSID和密码存进NVS开机时先读NVS尝试连接失败再进配置界面。nvs_handle_t handle; nvs_open(wifi_cfg, NVS_READWRITE, handle); nvs_set_str(handle, ssid, ssid); nvs_set_str(handle, pass, password); nvs_commit(handle); nvs_close(handle);密码明文存NVS安全性一般如果产品有要求可以配合ESP32的flash加密功能。个人项目里明文存问题不大但要知道这个取舍。7.2 扫描时只显示前N个热点AP多的地方扫描结果可能几十个全塞进列表既卡又难找。我的做法是只取信号最强的前15个并且过滤掉隐藏SSID。这样列表长度可控滚动流畅。7.3 用事件组统一管理网络状态当功能变多比如还要加蓝牙配网、MQTT连接用单一状态变量会不够用。这时候用FreeRTOS的事件组EventGroup更合适每个bit代表一个状态UI任务等待多个bit的组合逻辑清晰。#define WIFI_CONNECTED_BIT BIT0 #define WIFI_FAIL_BIT BIT1 EventBits_t bits xEventGroupWaitBits(s_wifi_event_group, WIFI_CONNECTED_BIT | WIFI_FAIL_BIT, pdFALSE, pdFALSE, portMAX_DELAY);这套组合拳打下来一个能扫描、能输入、能连接、能记忆的WiFi配置界面就成型了。整个过程最花时间的从来不是画界面而是把异步的网络事件和单线程的UI渲染安全地缝合在一起。我自己的经验是先把网络层的状态机跑通用串口打印验证每个状态转换都对再去接UI能省掉大量联调时间。屏幕上的每一个像素背后其实都是任务调度和内存管理在支撑。