目录前言一、WIFI配网1.1 为什么需要配网1.2 常见配网方式二、SmartConfig配网2.1 基本工作原理2.2 SmartConfig 的协议类型2.2.1 ESPTouch2.2.2 AirKiss2.2.3 ESPTouch v2 的改进支持加密支持自定义数据更适合产品化2.2.4 手机操作三、工程实现3.1 模块流程3.2 初始化配网模块3.3 获取凭据并连接3.4 Console 启动命令3.5 结果查看四、免费资源总结前言前面我们已经学习Station、softAP和now等WIFI技术现在接触下一个模块——WIFI配网。wifi配网是一个wifi设备不可或缺的重要功能wifi配网的方法有很多常见的有SmartConfig、Soft-AP配网、蓝牙配网等每种方法都有其特点和使用场景通常一个wifi设备会支持多种配网方案的组合以便用户可以根据实际情况灵活调整。本章具体介绍一下SmartConfig方法。一、WIFI配网Wi‑Fi 配网Wi‑Fi Provisioning就是把无线路由器的 SSIDWi‑Fi 名称和密码等信息传递给一个尚未联网的设备使设备能够以 STAStation模式连接到指定路由器并获得 IP 地址的过程。1.1 为什么需要配网手机、电脑通常可以直接通过界面输入 Wi‑Fi 密码但许多物联网设备没有屏幕和键盘例如ESP32 开发板智能插座Wi‑Fi 灯泡传感器节点无线摄像头。因此这些设备需要借助手机或其他设备将 Wi‑Fi 凭据传输给它之后设备才能连接家庭路由器并访问局域网或互联网。1.2 常见配网方式配网方式基本原理特点SmartConfig手机通过 Wi‑Fi 数据包广播配网信息设备监听并解析不需要设备建立热点操作较方便SoftAP 配网ESP32 创建临时热点手机连接该热点后发送 Wi‑Fi 信息原理直观、兼容性较好蓝牙 BLE 配网手机通过蓝牙连接设备并写入 Wi‑Fi 参数体验较好适合支持 BLE 的设备二维码配网手机显示包含 Wi‑Fi 信息的二维码设备通过摄像头识别适合带摄像头的设备有线或串口配网通过 USB、串口等接口写入网络参数适合调试和工程生产环节需要注意配网不是普通的 Wi‑Fi 连接过程。Wi‑Fi 连接是设备已经知道 SSID 和密码之后执行的连接动作配网则是设备还不知道这些信息时先通过某种通信方式获得网络参数。此外配网过程中会传输 Wi‑Fi 密码因此实际产品中应考虑传输安全、配网超时、错误重试、凭据擦除以及防止陌生设备获取密码等问题。二、SmartConfig配网SmartConfig 是一种通过手机广播 Wi‑Fi 配置信息使未联网设备自动获取路由器 SSID 和密码并连接到目标 Wi‑Fi 网络的配网技术。它最初由 TI 提出乐鑫在 ESP32 系列芯片中主要通过 ESP-Touch 等协议实现。它特别适合 ESP32、智能插座、传感器等没有屏幕和键盘的“无头设备”。用户只需在手机 App 中输入 Wi‑Fi 密码并启动配网设备即可监听并解析手机发送的数据而不需要手机直接连接设备热点。2.1 基本工作原理以 ESP32 的 ESP-Touch 为例流程大致如下ESP32 进入 SmartConfig 模式并开启 Wi‑Fi 混杂模式监听周围的无线报文手机连接目标路由器的 Wi‑Fi并在 App 中输入 Wi‑Fi 密码手机通过 UDP 广播或组播发送经过编码的配网数据ESP32 根据报文长度、地址等特征提取并解析 SSID、密码等信息ESP32 退出监听状态切换为 STA 模式并连接路由器连接成功后设备获取 IP 地址并可向手机反馈配网结果。需要注意的是ESP32 在配网初期通常无法直接读取普通 Wi‑Fi 数据帧中的应用层内容因为无线网络可能启用了加密。因此SmartConfig 协议通常利用报文长度等可观察特征对数据进行编码和传输。2.2 SmartConfig 的协议类型ESP-IDF 文档中ESP32-S3 等芯片支持 AirKiss、ESPTouch 和 ESPTouch v2 等 SmartConfig 类型。部分 ESP-AT 固件还支持组合模式例如ESP-TOUCH AirKiss。协议来源或应用主要特点适用情况ESPTouch乐鑫 ESP-Touch 方案采用 ESP-Touch 配网机制适合乐鑫生态自己开发 ESP32 App 或使用乐鑫示例AirKiss微信生态常用方案便于与微信及相关物联网平台结合微信小程序、公众号或微信生态配网ESPTouch v2ESPTouch 的改进版本支持更完善的安全机制和自定义数据新项目、对安全性和扩展性有要求的产品ESPTouch AirKiss双协议模式同时兼容两种配网方式希望兼容不同手机 App 或平台2.2.1 ESPTouchESPTouch 是乐鑫推出的配网协议目标是让手机通过 SmartConfig 机制把 Wi‑Fi 信息传递给 ESP8266 或 ESP32 设备。乐鑫提供了对应的 Android、iOS 端资源及设备端实现。它的优点是与 ESP-IDF 集成较好适合 ESP32 自定义 App设备端开发资料较多可以结合 ESP-Touch v2 扩展安全和自定义数据。如果你是在 ESP-IDF 中编写 ESP32 固件并且控制手机端 App那么 ESPTouch 通常是更自然的选择。2.2.2 AirKissAirKiss 更偏向微信生态。其优势不是 ESP32 底层性能更好而是便于接入微信相关的配网流程。相关平台和 App 需要按照 AirKiss 的协议格式发送数据。它适合微信小程序配网微信公众号配网已经使用微信物联网平台的产品不希望单独开发完整手机 App 的场景。因此AirKiss 与 ESPTouch 的主要差异更多体现在手机端和平台生态而不是 ESP32 的 STA 连接过程。2.2.3 ESPTouch v2 的改进ESPTouch v2 是对传统 ESPTouch 的增强版本重点改善了以下方面支持加密传统 SmartConfig 的风险在于Wi‑Fi 密码会通过无线环境传递如果没有额外保护附近具备监听能力的设备可能尝试恢复配网信息。ESPTouch v2 可以配合 AES 等机制保护配网数据。这样即使攻击者捕获无线报文也不能直接得到明文密码但手机端和 ESP32 必须使用相同的密钥或约定配置复杂度也会增加。支持自定义数据ESPTouch v2 不仅可以传输 SSID 和密码还可以携带厂商自定义信息例如设备编号产品型号用户绑定信息云平台 Token临时配网参数。不过这些自定义数据不应直接替代完整的身份认证机制。生产产品仍然需要考虑设备唯一密钥、服务端校验和防重放攻击。更适合产品化传统 ESPTouch 更适合快速实现和实验验证而 ESPTouch v2 更适合产品中使用。尤其是在需要加密、设备绑定、批量部署和扩展字段时v2 的工程适应性更好。一句话概括SmartConfig 就是“手机通过 Wi‑Fi 广播把网络凭据发送出去ESP32 监听并解析这些信息然后自动连接路由器”的配网方式。2.2.4 手机操作对于ESPTouch 和 ESPTouch v2协议使用的手机软件可以去乐鑫官网下载App乐鑫科技Android版本ESP-TOUCH for AndroidIOS版本ESP-TOUCH for iOS使用AirKiss协议的话微雪公众号里搜索《乐鑫信息科技》关注之后在公众号菜单栏选择“产品资源”“Airkiss设备”即可配置上网。三、工程实现模块以 Console 命令触发配网 为入口以SC_EVENT事件为主线在获取到 Wi-Fi 凭据后切换到正常的 STA 连接流程并在手机端确认收到 ACK 后结束 SmartConfig 会话。工程实现的核心目标如下允许用户通过串口命令随时进入 ESPTouch v2 配网模式配网前主动断开旧的 STA 连接避免连接状态与配网状态冲突在SC_EVENT_GOT_SSID_PSWD中取得 SSID、密码和可选附加数据使用统一的 Wi-Fi 连接逻辑完成入网复用已有的重连与状态管理机制在配网流程完成后调用esp_smartconfig_stop()释放 SmartConfig 相关资源3.1 模块流程从用户输入配网命令到设备获得 IP 地址整体流程如图所示SmartConfig 只负责将网络凭据传递给设备真正的 Wi-Fi 关联、认证、DHCP 获取地址以及后续掉线重连仍由 Wi-Fi STA 驱动和已有的WIFI_EVENT、IP_EVENT处理逻辑负责。3.2 初始化配网模块配网模块初始化应在 Wi-Fi 基础设施准备完成后执行。这里主要完成超时时间配置、STA 初始化、SmartConfig 事件注册以及 Console 命令注册。int wifi_smartconfig_init(uint8_t time_s) { /* 1. 设置配网超时时间秒 */ esp_esptouch_set_timeout(time_s); /* 2. 初始化 STA携带配网标志STA_START 时自动启动配网 */ wifi_station_init(ESP32C6, smartconfig_mode); /* 3. 注册 SC_EVENT 回调须在事件循环创建之后 */ ESP_ERROR_CHECK(esp_event_handler_instance_register(SC_EVENT, ESP_EVENT_ANY_ID, wifi_event_handler, NULL, NULL)); /* 4. 注册 smartconfig 控制台命令 */ register_smartconfig_cmd(); ESP_LOGI(TAG, 智能配网模块已初始化当前版本: %s, esp_smartconfig_get_version()); return ESP_OK; }esp_esptouch_set_timeout()用于设置 ESPTouch 的超时周期。若设备在指定时间内未完成配网SmartConfig 会重新开始扫描和监听超时时间不宜设置过短否则用户尚未来得及在手机端发起配网设备就可能提前进入下一轮扫描。建议在实际产品中将超时时间设置为 60 至 120 秒并在超时、连续失败或用户主动取消时给出 LED、蜂鸣器或串口日志等明确反馈。3.3 获取凭据并连接以下代码放在统一事件处理函数中用于处理SC_EVENT。实现重点是先解析事件数据再填充wifi_config_t最后由esp_wifi_connect()启动正常 STA 连接。/* SC 事件 */ else if(event_base SC_EVENT) { switch (event_id) { /* ---------- SC_EVENT_SCAN_DONE — 配网扫描完成 ---------- * SmartConfig 内部扫描结束需再次触发扫描直至锁定目标信道 */ case SC_EVENT_SCAN_DONE: break; /* ---------- SC_EVENT_FOUND_CHANNEL — 已定位目标 AP 信道 ---------- */ case SC_EVENT_FOUND_CHANNEL: wifi_event.is_connected false; wifi_event.is_connecting true; /* 连接已完成 */ wifi_event.retry_count 0; wifi_event.retry_enabled true; ESP_LOGI(TAG, SmartConfig 找到目标AP的信道); break; /* ---------- SC_EVENT_GOT_SSID_PSWD — 配网成功获得 SSID/密码 ---------- * 解析结果同步进 wifi_event 结构体与 connect 命令共用同一状态 * 复用 wifi_station_connect() 发起连接 —— 后续 STA_CONNECTED / * STA_DISCONNECTED 按原分类策略处理不产生路径冲突。 */ case SC_EVENT_GOT_SSID_PSWD: { smartconfig_event_got_ssid_pswd_t *evt (smartconfig_event_got_ssid_pswd_t *)event_data; if (evt NULL) { ESP_LOGW(TAG, GOT_SSID_PSWD 事件数据为空忽略); break; } ESP_LOGI(TAG, SmartConfig 获取到 SSID 和密码); ESP_LOGI(TAG, SmartConfig SSID: %s, evt-ssid); ESP_LOGI(TAG, SmartConfig Password: %s, evt-password); /* ESPTouch V2 附加数据读取事件回调中避免 abort仅告警 */ if (evt-type SC_TYPE_ESPTOUCH_V2) { uint8_t rvd_data[33] { 0 }; esp_err_t ret esp_smartconfig_get_rvd_data(rvd_data, sizeof(rvd_data)); if (ret ! ESP_OK) { ESP_LOGW(TAG, 读取 ESPTouch V2 附加数据失败: %s, esp_err_to_name(ret)); } else { ESP_LOGI(TAG, RVD_DATA:%s, rvd_data); } } wifi_config_t wifi_config { .sta { .scan_method WIFI_ALL_CHANNEL_SCAN, .failure_retry_cnt 3, .threshold.authmode WIFI_AUTH_OPEN }, }; memcpy(wifi_config.sta.ssid, evt-ssid, sizeof(wifi_config.sta.ssid)); memcpy(wifi_config.sta.password, evt-password, sizeof(wifi_config.sta.password)); ESP_ERROR_CHECK(esp_wifi_set_config(WIFI_IF_STA, wifi_config)); esp_err_t ret esp_wifi_connect(); if (ret ! ESP_OK) { ESP_LOGE(TAG, 连接启动失败: %s, esp_err_to_name(ret)); return; } break; } /* ---------- SC_EVENT_SEND_ACK_DONE — 已向手机回复 ACK ---------- */ case SC_EVENT_SEND_ACK_DONE: { ESP_LOGI(TAG, SmartConfig 成功, 向目标AP发送 ACK 完成); esp_err_t ret esp_smartconfig_stop(); if (ret ! ESP_OK) { ESP_LOGW(TAG, 停止 SmartConfig 失败: %s, esp_err_to_name(ret)); } break; } /* ---------- 未显式处理的 SC 事件 ---------- */ default: ESP_LOGD(TAG, 未处理的 SC 事件 (ID% PRIi32 )忽略, event_id); break; } }当手机端使用 ESPTouch v2 发起配网时除了 SSID 与密码还可以附带一段自定义保留数据Reserved Data简称 RVD Data。该数据可用于传递临时绑定 Token、设备激活参数、区域标识或业务配置标志等信息。3.4 Console 启动命令为了方便调试和测试本工程将 SmartConfig 封装为独立的 Console 命令。执行命令前先断开现有网络再停止残留会话可以通过命令参数来选择SmartConfig 的协议类型。static int smartconfig_cmd_handler(int argc, char **argv) { wifi_ap_record_t ap_info; /* 1. 解析配网协议类型默认 ESPTouch V2无需参数即可直接启动 */ smartconfig_type_t sc_type SC_TYPE_ESPTOUCH_V2; if (argc 2) { if (strcmp(argv[1], espv2) 0) { sc_type SC_TYPE_ESPTOUCH_V2; } else if (strcmp(argv[1], air) 0) { sc_type SC_TYPE_AIRKISS; } else { printf(用法: smartconfig [espv2|air]\r\n); printf( espv2 - ESPTouch V2 配网默认\r\n); printf( air - AirKiss 配网\r\n); return 1; } } /* 2. 检查联网状态已连接或连接中则先断开SmartConfig 要求空闲 */ if (wifi_event.is_connecting || esp_wifi_sta_get_ap_info(ap_info) ESP_OK) { ESP_LOGI(TAG, 检测到已有连接先断开旧连接); wifi_event.retry_enabled false; esp_err_t ret esp_wifi_disconnect(); if (ret ! ESP_OK) { ESP_LOGW(TAG, 断开旧连接失败: %s, esp_err_to_name(ret)); return 1; } while (esp_wifi_sta_get_ap_info(ap_info) ESP_OK ) { vTaskDelay(pdMS_TO_TICKS(100)); } } /* 3. 停止可能残留的旧配网会话幂等 */ esp_err_t ret esp_smartconfig_stop(); if (ret ! ESP_OK) { ESP_LOGD(TAG, 无正在运行的配网会话: %s, esp_err_to_name(ret)); } /* 4. 启动 SmartConfig 配网 */ ESP_ERROR_CHECK(esp_smartconfig_set_type(sc_type)); smartconfig_start_config_t cfg SMARTCONFIG_START_CONFIG_DEFAULT(); ret esp_smartconfig_start(cfg); if (ret ! ESP_OK) { ESP_LOGE(TAG, SmartConfig 启动失败: %s, esp_err_to_name(ret)); return 1; } ESP_LOGI(TAG, SmartConfig(%s) 配网已启动请用手机 App 发送 WiFi 凭证, (sc_type SC_TYPE_AIRKISS) ? AirKiss : ESPTouch V2); return 0; }这种“先断开、再清理、后启动”的流程能避免设备同时处于旧网络重连和 SmartConfig 监听状态从而减少状态竞争和日志混乱。对于使用自动重连机制的工程尤其要先关闭retry_enabled否则断开旧连接后重连任务可能会抢占配网流程。3.5 结果查看注意以下内容我是在手机热点作为AP尝试的成功实现同时我尝试了用另一块ESP32的softAP功能但始终无法连接成功。好像对于ESP32的softAP使用ESPTouch v2配网无法接收配网数据包。不知是不是有其他遗漏之处若有同学实现了还请留言不胜感激展示使用ESPTouch v2协议对于AirKiss协议更加间接更换协议只需要在Console 启动命令中输入对应参数皆可。板子上电后控制台输入命令smartconfig会启动 smartconfig 配网功能当代码调用esp_smartconfig_start后此时ESP32 并不知道手机在哪个信道上发包所以驱动会把当前环境中所有信道都便利一遍。当查找到环境中所有可用信道后比如1、6、11接下来会不断在这些信道轮询交替用来监听可能或出现的数据包。类似如下注意要明白一个前提两个无线设备只要处于同样信道下便可通信这是电磁波的特性频率相同只不过于人们设置了各种协议和保护通信得到的数据包无法解析。此时先给手机连接上一个2.4G的wifi然后打开手机ESPTouch软件选择SmartConfig 的协议此时ESP32 就抓住了空中SmartConfig 配网数据包触发SC_EVENT_FOUND_CHANNEL事件此时会等待我们设定的超时时间再该时间内我们只要在手机ESPTouch软件输入该wifi的SSID和密码ESP32就会触发SC_EVENT_GOT_SSID_PSWD事件从而获得这些信息就能成功联网了。在我的代码中如果想换一个wifi只需要控制台输入 smartconfig 命令就能重新启动SmartConfig从而可以连接新的wifi。需要注意获取到 SSID 和密码并不代表已经联网成功实际工程中应以IP_EVENT_STA_GOT_IP作为 STA 联网成功的判断依据。四、免费资源以上完整工程可以进入我的Gitee中下载《https://gitee.com/pai-schoolmate/esp32_project.git》本工程路径esp32_project-main\function\provisioning总结在工程设计上本文采用事件驱动方式处理SC_EVENT、WIFI_EVENT和IP_EVENT通过 Console 命令启动配网并对旧连接、自动重连、凭据解析和 SmartConfig 会话进行统一管理。实践表明SC_EVENT_GOT_SSID_PSWD仅代表设备成功获取网络参数最终应以IP_EVENT_STA_GOT_IP作为联网成功的判断依据。SmartConfig 具有使用便捷、无需额外硬件和适合无屏设备等特点但其稳定性受手机、路由器频段及无线环境影响。实际产品中还应进一步完善配网超时、失败重试、凭据保护、设备绑定和备用配网方案以提升系统的可靠性、安全性与产品适应性。