ESP-IDF+vscode开发ESP32 联网篇第五讲——Smart_config 配网

目录

前言

一、WIFI配网

1.1 为什么需要配网

1.2 常见配网方式

二、SmartConfig配网

2.1 基本工作原理

2.2 SmartConfig 的协议类型

2.2.1 ESPTouch

2.2.2 AirKiss

2.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），就是把无线路由器的 SSID（Wi‑Fi 名称）和密码等信息传递给一个尚未联网的设备，使设备能够以 STA（Station）模式连接到指定路由器并获得 IP 地址的过程。

1.1 为什么需要配网

手机、电脑通常可以直接通过界面输入 Wi‑Fi 密码，但许多物联网设备没有屏幕和键盘，例如：

• ESP32 开发板；
• 智能插座；
• Wi‑Fi 灯泡；
• 传感器节点；
• 无线摄像头。

因此，这些设备需要借助手机或其他设备，将 Wi‑Fi 凭据传输给它，之后设备才能连接家庭路由器并访问局域网或互联网。

1.2 常见配网方式

需要注意，配网不是普通的 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 为例，流程大致如下：

1. ESP32 进入 SmartConfig 模式，并开启 Wi‑Fi 混杂模式监听周围的无线报文；
2. 手机连接目标路由器的 Wi‑Fi，并在 App 中输入 Wi‑Fi 密码；
3. 手机通过 UDP 广播或组播发送经过编码的配网数据；
4. ESP32 根据报文长度、地址等特征提取并解析 SSID、密码等信息；
5. ESP32 退出监听状态，切换为 STA 模式并连接路由器；
6. 连接成功后，设备获取 IP 地址，并可向手机反馈配网结果。

需要注意的是，ESP32 在配网初期通常无法直接读取普通 Wi‑Fi 数据帧中的应用层内容，因为无线网络可能启用了加密。因此，SmartConfig 协议通常利用报文长度等可观察特征对数据进行编码和传输。

2.2 SmartConfig 的协议类型

ESP-IDF 文档中，ESP32-S3 等芯片支持 AirKiss、ESPTouch 和 ESPTouch v2 等 SmartConfig 类型。部分 ESP-AT 固件还支持组合模式，例如ESP-TOUCH + AirKiss。

2.2.1 ESPTouch

ESPTouch 是乐鑫推出的配网协议，目标是让手机通过 SmartConfig 机制把 Wi‑Fi 信息传递给 ESP8266 或 ESP32 设备。乐鑫提供了对应的 Android、iOS 端资源及设备端实现。

它的优点是：

• 与 ESP-IDF 集成较好；
• 适合 ESP32 自定义 App；
• 设备端开发资料较多；
• 可以结合 ESP-Touch v2 扩展安全和自定义数据。

如果你是在 ESP-IDF 中编写 ESP32 固件，并且控制手机端 App，那么 ESPTouch 通常是更自然的选择。

2.2.2 AirKiss

AirKiss 更偏向微信生态。其优势不是 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 Android
• IOS版本：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 具有使用便捷、无需额外硬件和适合无屏设备等特点，但其稳定性受手机、路由器频段及无线环境影响。实际产品中还应进一步完善配网超时、失败重试、凭据保护、设备绑定和备用配网方案，以提升系统的可靠性、安全性与产品适应性。