ESP-IDF SmartConfig 配网技术指南ESPTouch / AirKiss / ESPTouch v2 原理与实战【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf本文基于 ESP-IDF 开源仓库系统讲解 SmartConfig 配网技术的核心原理、三种协议类型AirKiss、ESPTouch、ESPTouch v2的差异、AES 加密与随机 IV 机制并结合 wifi/smart_config 示例 给出完整的工程实践与 API 参考。读完本文你将掌握如何在无屏幕、无键盘的 headless Wi-Fi 设备上仅凭手机 App 广播 SSID 与密码完成一键配网。SmartConfig 技术概述SmartConfig™ 是由 TI 提出的一种配网Provisioning技术用于将一个新的 Wi-Fi 设备接入目标 Wi-Fi 网络。其核心思路是使用智能手机或平板上的移动应用将网络凭据SSID 与密码通过 Wi-Fi 报文广播给尚未配网的设备。这一技术最大的优势在于设备本身无需预先知道目标 AP 的 SSID 或密码这些信息完全由智能手机提供。对于没有用户界面的 headless 设备无屏无键盘的 IoT 设备、传感器节点等这一特性尤为关键——用户无需为设备配备输入/显示外设只需在手机 App 上操作即可完成配网。三种 SmartConfig 协议类型当前 ESP-IDF 支持三种 SmartConfig 协议对应的枚举定义位于 esp_smartconfig.h枚举值协议说明SC_TYPE_ESPTOUCHESPTouch乐鑫自有协议最常用SC_TYPE_AIRKISSAirKiss腾讯提出的协议SC_TYPE_ESPTOUCH_AIRKISSESPTouch AirKiss同时支持两种协议SC_TYPE_ESPTOUCH_V2ESPTouch v2自 SmartConfig v3.0 起支持其中ESPTouch v2自 SmartConfig v3.0可通过 esp_smartconfig_get_version() 获取 SmartConfig 版本号开始支持。与 ESPTouch 相比ESPTouch v2 采用了完全不同的算法配网建立时间更短同时引入了AES 加密与自定义数据字段reserved data能力。ESPTouch v2 的 AES 随机 IV 机制自 SmartConfig v3.0.2 起ESPTouch v2 在 AES 加密中引入了**随机 IV初始化向量**支持。其行为分为应用端与设备端两侧应用端手机 App当随机 IV 选项关闭时默认 IV 固定为 0与旧版本行为保持一致当随机 IV 选项开启时IV 将取随机值。需要特别注意的是AES 加密配合随机 IV 时由于需要额外把 IV 传输给配网设备配网时间会有所延长。设备端设备根据配网报文中的标志位flag来判断发送端是否启用了 AES 随机 IV。这一设计既保证了向后兼容旧版本 App 默认 IV 为 0 仍可配网又提升了安全性随机 IV 避免相同明文产生相同密文。配网流程与底层实现SmartConfig 的完整配网流程可以分为以下几个阶段设备进入配网状态调用esp_smartconfig_start()后设备进入 sniffer嗅探模式监听空中的特殊报文。扫描与信道发现设备扫描信道寻找发送配网报文的手机触发SC_EVENT_SCAN_DONE与SC_EVENT_FOUND_CHANNEL事件。获取 SSID 与密码从报文中解析出目标 AP 的 SSID、密码及可选 BSSID触发SC_EVENT_GOT_SSID_PSWD事件。回连目标 AP应用代码收到事件后调用esp_wifi_set_config()配置并连接目标 AP。发送 ACK设备向手机发送确认报文通过 UDP触发SC_EVENT_SEND_ACK_DONE事件手机端据此提示配网成功。从源码实现看smartconfig.c 中esp_smartconfig_start()的核心工作之一是注册SC_EVENT_GOT_SSID_PSWD的默认事件处理器handler_got_ssid_passwd该处理器在收到 SSID/密码事件后立即调用sc_send_ack_start()向手机发送 ACK见 smartconfig_ack.cesp_smartconfig_stop()则负责停止内部配网流程、停止 ACK 发送并注销事件处理器释放esp_smartconfig_start()占用的内存。事件类型一览SmartConfig 相关事件在 esp_smartconfig.h 中定义事件基类为SC_EVENT事件含义SC_EVENT_SCAN_DONESTA 已完成对 AP 的扫描SC_EVENT_FOUND_CHANNELSTA 已找到目标 AP 的信道SC_EVENT_GOT_SSID_PSWDSTA 已获取到 SSID 与密码SC_EVENT_SEND_ACK_DONESTA 已向手机发送 ACK其中SC_EVENT_GOT_SSID_PSWD的事件数据结构为smartconfig_event_got_ssid_pswd_tesp_smartconfig.h包含SSID32 字节以\0结尾、密码64 字节以\0结尾、bssid_set标志与目标 AP 的 MAC 地址6 字节、协议类型type、用于发送 ACK 的token以及手机 IP 地址cellphone_ip[4]。实战基于 wifi/smart_config 示例完成一键配网仓库提供了完整可运行的示例工程 wifi/smart_config支持 ESP32、ESP32-C2/C3/C5/C6/C61、ESP32-S2/S3 等目标芯片。硬件与 App 准备一块支持的目标芯片开发板一部已连接到目标 AP2.4GHz 频段的手机在手机应用商店下载 ESPTOUCH App乐鑫提供了 EsptouchForAndroid 与 EsptouchForIOS 的开源代码。编译、烧录与运行# 配置工程可在此步通过 menuconfig 调整示例配置 idf.py menuconfig # 编译烧录并打开串口监视器 idf.py -p PORT flash monitor退出串口监视器请按Ctrl-]。示例工程提供了一项可配置项CONFIG_SET_MAC_ADDRESS_OF_TARGET_AP见 Kconfig.projbuild默认开启用于决定配网后是否同时绑定目标 AP 的 MAC 地址BSSID。示例代码解析示例主程序 smartconfig_main.c 完整演示了配网流程核心要点如下1. 事件处理器注册L37-L91同时注册WIFI_EVENT、IP_EVENT、SC_EVENT三类事件。关键处理逻辑WIFI_EVENT_STA_STARTWi-Fi 启动后创建配网任务WIFI_EVENT_STA_DISCONNECTED连接断开时重连IP_EVENT_STA_GOT_IP拿到 IP 后置位CONNECTED_BITSC_EVENT_GOT_SSID_PSWD从smartconfig_event_got_ssid_pswd_t *evt中取出 SSID/密码填充wifi_config_t若使能CONFIG_SET_MAC_ADDRESS_OF_TARGET_AP则一并设置 BSSID若协议为SC_TYPE_ESPTOUCH_V2还调用esp_smartconfig_get_rvd_data()打印自定义保留数据随后esp_wifi_disconnect()→esp_wifi_set_config(WIFI_IF_STA, wifi_config)→esp_wifi_connect()完成目标 AP 连接SC_EVENT_SEND_ACK_DONE置位ESPTOUCH_DONE_BIT表示配网完成。2. 启动配网任务L112-L129ESP_ERROR_CHECK( esp_smartconfig_set_type(SC_TYPE_ESPTOUCH) ); smartconfig_start_config_t cfg SMARTCONFIG_START_CONFIG_DEFAULT(); ESP_ERROR_CHECK( esp_smartconfig_start(cfg) );通过xEventGroupWaitBits等待CONNECTED_BIT | ESPTOUCH_DONE_BIT两个标志位都满足后调用esp_smartconfig_stop()并删除任务。3. 入口函数L131-L135void app_main(void) { ESP_ERROR_CHECK( nvs_flash_init() ); initialise_wifi(); }initialise_wifi()中完成esp_netif_init()、默认事件循环创建、STA 网络接口创建、esp_wifi_init()初始化以及三类事件处理器的注册。运行输出示例配网成功后的典型串口输出如下源自 示例 READMEI (372) wifi: mode : sta (24:0a:c4:00:44:86) I (422) smartconfig: SC version: V2.6.6 I (3802) wifi: ic_enable_sniffer I (3802) sc: SC_STATUS_FIND_CHANNEL I (234592) smartconfig: TYPE: ESPTOUCH I (234592) smartconfig: T|PHONE MAC:68:3e:34:88:59:bf I (234592) smartconfig: T|AP MAC:a4:56:02:47:30:07 I (234592) sc: SC_STATUS_GETTING_SSID_PSWD I (239922) smartconfig: T|pswd: 123456789 I (239922) smartconfig: T|ssid: IOT_DEMO_TEST I (239922) smartconfig: T|bssid: a4:56:02:47:30:07 I (239922) wifi: ic_disable_sniffer I (239922) sc: SC_STATUS_LINK I (239932) sc: SSID:IOT_DEMO_TEST I (239932) sc: PASSWORD:123456789 I (241042) wifi: state: auth - assoc (0) I (241052) wifi: state: assoc - run (10) I (241102) wifi: connected with IOT_DEMO_TEST, channel 1 I (244892) event: ip: 192.168.0.152, mask: 255.255.255.0, gw: 192.168.0.1 I (244892) sc: WiFi Connected to ap I (247952) sc: SC_STATUS_LINK_OVER I (247952) sc: Phone ip: 192.168.0.31 I (247952) sc: smartconfig over从输出可以看到配网状态机的完整迁移SC_STATUS_FIND_CHANNEL发现信道→SC_STATUS_GETTING_SSID_PSWD获取凭据→SC_STATUS_LINK回连 AP→SC_STATUS_LINK_OVER链路建立完成配网结束且设备能打印出手机的 IP 地址。SmartConfig API 参考SmartConfig 的全部公共 API 定义在 esp_smartconfig.h以下为完整清单与使用要点API功能与注意事项const char *esp_smartconfig_get_version(void)获取 SmartConfig 版本号字符串如V2.6.6用于判断是否支持 ESPTouch v2 等特性。esp_err_t esp_smartconfig_start(const smartconfig_start_config_t *config)启动 SmartConfig。可在 STA 或 SoftAP-STA 混合模式下调用在流程结束前不可重复调用如需重启须先调用esp_smartconfig_stop()。esp_err_t esp_smartconfig_stop(void)停止 SmartConfig 并释放其占用的内存。无论是否成功连上 AP配网结束后都应调用以释放资源。esp_err_t esp_esptouch_set_timeout(uint8_t time_s)设置 SmartConfig 超时时间取值范围 15s~255s默认偏移 45s。计时从SC_STATUS_FIND_CHANNEL状态开始超时后 SmartConfig 会重启。esp_err_t esp_smartconfig_set_type(smartconfig_type_t type)设置协议类型须在调用esp_smartconfig_start()之前设置。esp_err_t esp_smartconfig_fast_mode(bool enable)启用/关闭快速配网模式默认关闭normal 模式。须在esp_smartconfig_start()前调用快速模式需要配套的手机 App两种模式互相兼容。esp_err_t esp_smartconfig_get_rvd_data(uint8_t *rvd_data, uint8_t len)获取 ESPTouch v2 报文中的自定义保留数据reserved data仅在收到SC_EVENT_GOT_SSID_PSWD事件且协议为 ESPTouch v2 时有意义。启动配置结构体typedef struct { bool enable_log; /** 是否启用 SmartConfig 日志 */ bool esp_touch_v2_enable_crypt; /** 是否启用 ESPTouch v2 加密 */ char *esp_touch_v2_key; /** ESPTouch v2 加密密钥长度应为 16 字节 */ } smartconfig_start_config_t; #define SMARTCONFIG_START_CONFIG_DEFAULT() { \ .enable_log false, \ .esp_touch_v2_enable_crypt false,\ .esp_touch_v2_key NULL \ }该结构体与默认宏定义于 esp_smartconfig.h。当使用 ESPTouch v2 且需要加密时应将esp_touch_v2_enable_crypt置为true并提供16 字节的密钥esp_touch_v2_key同时手机 App 端需使用相同密钥才能完成解密配网。总结SmartConfig 为无 UI 的 IoT 设备提供了一种零交互的配网方案。在 ESP-IDF 中开发者可通过统一的SC_EVENT事件体系 少量 API 调用快速集成 ESPTouch、AirKiss 或 ESPTouch v2 三种协议其中 ESPTouch v2 通过全新算法与 AES 加密可选随机 IV兼顾了配网速度与安全性。如果需要探索其他配网方式如基于 BLE 的配网可参考 配网方案总览 获取更多选项。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考