EspDn32Wifi：轻量级ESP32/ESP8266 Wi-Fi连接状态机库

1. 项目概述EspDn32Wifi 是一个面向 ESP8266 和 ESP32 平台的轻量级 Wi-Fi 连接辅助库其核心设计目标是降低嵌入式设备接入 Wi-Fi 网络的工程门槛而非替代 ESP-IDF 或 Arduino-ESP32 官方 Wi-Fi 栈。该库不提供协议栈实现而是对底层 SDK 的 Wi-Fi API 进行结构化封装聚焦于连接流程的自动化、状态机管理、失败恢复策略及常见场景的模式抽象。其价值体现在将原本需数十行手动轮询wifi_sta_get_ip_info()、反复调用esp_wifi_connect()、手动处理SYSTEM_EVENT_STA_DISCONNECTED事件并重试的繁琐逻辑压缩为数行可配置、可复用、可调试的接口调用。该库并非“零配置魔法库”而是一个工程师友好的连接状态控制器。它明确区分了“配置阶段”SSID/PSK 设置、AP/STA 模式选择与“运行阶段”连接建立、IP 获取、断线重连并通过回调机制将控制权交还给应用层避免阻塞式等待破坏实时性。在资源受限的 ESP8266 上其静态内存占用低于 1.2KB在 ESP32 上因支持多核调度与更丰富的事件队列可无缝集成 FreeRTOS 任务进行非阻塞连接管理。1.1 设计哲学与工程定位EspDn32Wifi 的设计严格遵循嵌入式开发的三大铁律确定性、可观测性、可裁剪性。确定性所有连接操作均基于明确的状态迁移如WIFI_IDLE → WIFI_CONNECTING → WIFI_CONNECTED无隐式超时或后台自动重连除非显式启用。开发者始终清楚当前所处状态及下一步触发条件。可观测性提供细粒度事件回调onConnect,onDisconnect,onGotIp,onFail每个回调均携带原始 SDK 错误码如WIFI_REASON_NO_AP_FOUND,WIFI_REASON_AUTH_FAIL及上下文信息尝试次数、RSSI 值便于现场诊断网络问题。可裁剪性通过预编译宏如ESP_DN32_WIFI_ENABLE_AUTO_RECONNECT,ESP_DN32_WIFI_ENABLE_DHCP_TIMEOUT控制功能子集。关闭自动重连后库仅保留一次连接尝试能力代码体积可缩减至 800 字节以下适用于对 Flash 空间极度敏感的 OTA 升级引导程序。这种设计使其天然适配两类典型场景产品固件主循环在while(1)中调用wifi_loop()由库内部管理连接状态机应用层仅需响应事件回调FreeRTOS 任务协程创建独立wifi_task在任务中调用wifi_start()后挂起由事件组Event Group或队列Queue通知连接结果避免阻塞高优先级任务。2. 核心架构与状态机EspDn32Wifi 的核心是一个基于事件驱动的有限状态机FSM其状态定义与迁移规则完全映射 ESP-IDF 的wifi_event_t事件流确保行为可预测且与底层 SDK 严格同步。2.1 状态定义与迁移图状态枚举值描述触发条件退出条件WIFI_IDLE初始空闲态Wi-Fi 驱动未初始化库初始化完成调用wifi_start()或wifi_connect()WIFI_INITWi-Fi 驱动初始化中wifi_start()被调用WIFI_EVENT_SCAN_DONE或初始化失败WIFI_SCANNING主动扫描 AP 列表wifi_scan_start()或自动扫描启用WIFI_EVENT_SCAN_DONE事件到达WIFI_CONNECTING尝试关联指定 APwifi_connect()或扫描后自动连接SYSTEM_EVENT_STA_STARTSYSTEM_EVENT_STA_CONNECTED或失败事件WIFI_CONNECTED已关联但未获取 IPSYSTEM_EVENT_STA_CONNECTEDSYSTEM_EVENT_STA_GOT_IP或 DHCP 超时WIFI_READY连接就绪IP 可用SYSTEM_EVENT_STA_GOT_IP手动调用wifi_disconnect()或网络中断WIFI_DISCONNECTED显式断开或异常掉线wifi_disconnect()或SYSTEM_EVENT_STA_DISCONNECTED调用wifi_reconnect()或wifi_start()关键设计说明WIFI_CONNECTED与WIFI_READY的分离是工程实践的关键。许多开发者误以为SYSTEM_EVENT_STA_CONNECTED即代表网络可用实则此时仅完成 802.11 关联尚未通过 DHCP 获取 IP 地址。EspDn32Wifi 强制区分此两态避免应用层在无 IP 时发起 TCP 连接导致EINPROGRESS错误。2.2 事件回调机制实现库通过注册全局事件处理函数esp_event_handler_t捕获 Wi-Fi 事件并将其翻译为应用层可订阅的回调。所有回调函数签名统一为typedef void (*wifi_callback_t)(wifi_event_t event, const wifi_event_data_t* data);其中wifi_event_t是库定义的精简事件枚举wifi_event_data_t是携带上下文的联合体union按事件类型填充不同字段typedef struct { union { struct { uint8_t ssid[32]; uint8_t bssid[6]; int32_t rssi; } scan_result; // WIFI_EVENT_SCAN_RESULT struct { uint8_t ssid[32]; wifi_auth_mode_t auth_mode; } ap_info; // SYSTEM_EVENT_AP_START struct { ip4_addr_t ip; ip4_addr_t netmask; ip4_addr_t gw; } got_ip; // SYSTEM_EVENT_STA_GOT_IP struct { wifi_err_reason_t reason; uint8_t attempt_count; } fail; // SYSTEM_EVENT_STA_DISCONNECTED }; } wifi_event_data_t;此设计避免了为每个事件分配独立结构体的内存开销同时保证数据访问的类型安全。在 ESP32 上回调在wifi_event_task中执行在 ESP8266 上则在system_event_task中执行确保与 SDK 事件分发机制一致。3. API 接口详解EspDn32Wifi 提供三层 API基础配置接口、连接控制接口、状态查询接口。所有函数均返回esp_err_t错误码直接透传自 ESP-IDF SDK便于统一错误处理。3.1 基础配置接口函数参数说明典型用途注意事项wifi_config_set_mode(wifi_mode_t mode)mode:WIFI_MODE_STA,WIFI_MODE_AP,WIFI_MODE_APSTA设置 Wi-Fi 工作模式必须在wifi_start()前调用WIFI_MODE_APSTA模式下STA 连接失败不影响 AP 功能wifi_config_set_ap(const char* ssid, const char* password, uint8_t channel, wifi_auth_mode_t auth)ssid: AP 名称≤32字节password: 密码WPA2 至少8位channel: 信道1-13auth: 认证方式配置 SoftAP 参数密码为空时启用 Open 认证channel0表示自动选择最佳信道wifi_config_set_sta(const char* ssid, const char* password, bool auto_connect)ssid: 目标 AP 名称password: 密码auto_connect: 是否开机自动连接配置 STA 连接参数auto_connecttrue时wifi_start()后自动触发连接流程密码长度超过 64 字节将被截断wifi_config_set_dhcp_timeout(uint32_t timeout_ms)timeout_ms: DHCP 获取 IP 超时时间默认 30000ms设置 DHCP 超时阈值超时后状态机进入WIFI_DISCONNECTED并触发onFail回调不自动重试3.2 连接控制接口函数参数说明典型用途注意事项wifi_start()无参数初始化 Wi-Fi 驱动并启动状态机首次调用执行esp_netif_init()和esp_event_loop_create()重复调用无副作用wifi_connect()无参数手动触发 STA 连接忽略auto_connect设置仅在WIFI_IDLE或WIFI_DISCONNECTED状态下有效其他状态下调用返回ESP_ERR_INVALID_STATEwifi_disconnect()无参数主动断开当前连接立即触发SYSTEM_EVENT_STA_DISCONNECTED事件状态机进入WIFI_DISCONNECTEDwifi_scan_start()无参数启动主动扫描仅 STA 模式扫描结果通过onScanResult回调逐条返回需提前注册该回调wifi_reconnect()无参数在WIFI_DISCONNECTED状态下重新连接重置尝试计数器重新进入WIFI_CONNECTING流程3.3 状态查询与工具接口函数返回值用途实现细节wifi_get_state()wifi_state_t获取当前状态机状态直接读取内部g_wifi_state全局变量零开销wifi_is_connected()bool快速判断是否处于WIFI_READY状态内联函数编译期优化为单条比较指令wifi_get_ip_info(ip4_addr_t* ip, ip4_addr_t* netmask, ip4_addr_t* gw)esp_err_t获取当前 IPv4 地址信息从esp_netif_get_ip_info()封装失败时返回ESP_ERR_NOT_FOUNDwifi_get_rssi()int32_t获取当前连接 AP 的 RSSIdBm调用esp_wifi_sta_get_rssi()未连接时返回INT32_MIN4. 典型使用场景与代码示例4.1 场景一最小化 STA 连接裸机循环适用于资源受限的 ESP8266 固件无 RTOS主循环中轮询#include esp_dn32_wifi.h #include freertos/FreeRTOS.h // 全局连接状态标志 static bool g_wifi_ready false; // 连接成功回调 static void on_connect(wifi_event_t event, const wifi_event_data_t* data) { printf(Wi-Fi connected to %s\n,>#include esp_dn32_wifi.h #include freertos/event_groups.h #define WIFI_CONNECTED_BIT BIT0 #define WIFI_FAIL_BIT BIT1 static EventGroupHandle_t s_wifi_event_group; // 事件组回调 static void wifi_event_group_callback(wifi_event_t event, const wifi_event_data_t* data) { switch(event) { case WIFI_EVENT_STA_GOT_IP: xEventGroupSetBits(s_wifi_event_group, WIFI_CONNECTED_BIT); break; case WIFI_EVENT_STA_DISCONNECTED: xEventGroupSetBits(s_wifi_event_group, WIFI_FAIL_BIT); break; default: break; } } // Wi-Fi 任务 static void wifi_task(void* pvParameters) { s_wifi_event_group xEventGroupCreate(); // 注册事件组回调 wifi_register_callback(WIFI_EVENT_STA_GOT_IP, wifi_event_group_callback); wifi_register_callback(WIFI_EVENT_STA_DISCONNECTED, wifi_event_group_callback); wifi_config_set_mode(WIFI_MODE_STA); wifi_config_set_sta(OfficeWiFi, SecurePass, true); wifi_start(); // 启动连接流程 while(1) { // 等待连接成功或失败事件 EventBits_t bits xEventGroupWaitBits( s_wifi_event_group, WIFI_CONNECTED_BIT | WIFI_FAIL_BIT, pdTRUE, // 清除已等待的位 pdFALSE, // 不需要所有位都置位 portMAX_DELAY ); if (bits WIFI_CONNECTED_BIT) { printf(Wi-Fi connected! Starting application...\n); start_application(); // 启动主应用逻辑 } else if (bits WIFI_FAIL_BIT) { printf(Wi-Fi connection failed. Retrying in 5s...\n); vTaskDelay(5000 / portTICK_PERIOD_MS); wifi_reconnect(); // 触发重连 } } } void app_main(void) { xTaskCreate(wifi_task, wifi_task, 4096, NULL, 5, NULL); }4.3 场景三APSTA 双模切换IoT 设备配网设备上电首先进入 SoftAP 模式供手机 App 配置配置完成后切换至 STA 模式联网#include esp_dn32_wifi.h static void on_ap_start(wifi_event_t event, const wifi_event_data_t* data) { printf(SoftAP started: %s on channel %d\n,># 在 project(CMakeLists.txt) 下添加 set(EXTRA_COMPONENT_DIRS ${CMAKE_CURRENT_LIST_DIR}/components/esp_dn32_wifi) # 确保依赖项已启用 set(CONFIG_ESP_NETIF_ENABLED y) set(CONFIG_ESP_EVENT_LOOP_SUPPORTED y)关键注意事项禁止在app_main()中重复调用esp_netif_init()或esp_event_loop_create()EspDn32Wifi 会自动检测并跳过若项目已使用esp_http_client或mqtt_client可直接在WIFI_EVENT_STA_GOT_IP回调中初始化这些客户端无需额外延时使用CONFIG_ESP_WIFI_SLP_ENABLEDy启用 Wi-Fi Sleep 模式时库会自动在WIFI_READY状态下调用esp_wifi_set_ps(WIFI_PS_MIN_MODEM)。6.2 与 Arduino-ESP32 的桥接在 Arduino 环境中需通过extern C包装 C 接口// arduino_wrapper.h extern C { #include esp_dn32_wifi.h } // 在 .ino 文件中 void setup() { Serial.begin(115200); // 注册 Arduino 风格回调 wifi_register_callback(WIFI_EVENT_STA_GOT_IP, [](wifi_event_t e, const wifi_event_data_t* d) { Serial.printf(Arduino: Got IP IPSTR \n, IP2STR(d-got_ip.ip)); // 在此处启动 Arduino MQTT 库 mqttClient.connect(); }); wifi_config_set_sta(ArduinoAP, 12345678, true); wifi_start(); } void loop() { wifi_loop(); // 必须周期性调用以驱动状态机 delay(10); }6.3 与 LVGL GUI 的联动在带显示屏的设备中可将 Wi-Fi 状态实时反馈至 UI// LVGL 回调中更新状态图标 static void update_wifi_status_icon() { static lv_obj_t* wifi_icon NULL; if (!wifi_icon) { wifi_icon lv_img_create(lv_scr_act()); lv_img_set_src(wifi_icon, img_wifi_off); } switch(wifi_get_state()) { case WIFI_READY: lv_img_set_src(wifi_icon, img_wifi_on); lv_label_set_text(status_label, Online); break; case WIFI_CONNECTING: lv_img_set_src(wifi_icon, img_wifi_search); lv_label_set_text(status_label, Connecting...); break; default: lv_img_set_src(wifi_icon, img_wifi_off); lv_label_set_text(status_label, Offline); break; } } // 在 wifi_event_t 回调中调用 static void on_wifi_event(wifi_event_t event, const wifi_event_data_t* data) { update_wifi_status_icon(); }7. 源码关键路径解析EspDn32Wifi 的核心逻辑集中在esp_dn32_wifi.c其主循环wifi_loop()是状态机驱动引擎void wifi_loop(void) { // 1. 处理 SDK 事件队列非阻塞 esp_event_loop_run_once(NULL, 0); // 2. 根据当前状态执行动作 switch(g_wifi_state) { case WIFI_IDLE: // 等待 wifi_start() 调用 break; case WIFI_INIT: if (is_wifi_initialized()) { g_wifi_state WIFI_SCANNING; if (g_auto_scan_on_start) wifi_scan_start(); } break; case WIFI_CONNECTING: // 检查是否收到 SYSTEM_EVENT_STA_CONNECTED if (g_sta_connected_flag) { g_wifi_state WIFI_CONNECTED; g_dhcp_start_time xTaskGetTickCount(); } break; case WIFI_CONNECTED: // 检查 DHCP 超时 if (xTaskGetTickCount() - g_dhcp_start_time g_dhcp_timeout_ticks) { wifi_trigger_disconnect(WIFI_REASON_DHCP_TIMEOUT); g_wifi_state WIFI_DISCONNECTED; } break; // ... 其他状态处理 } }此设计确保wifi_loop()可在任意上下文裸机循环、FreeRTOS 任务、中断服务程序中安全调用且执行时间恒定 50μs满足硬实时约束。所有状态迁移均通过g_wifi_state全局变量原子更新避免竞态条件。