系列文章目录

持续更新…

文章目录

系列文章目录
前言
一、Wi‑Fi 智能配网概述
- 1.SmartConfig 简介
- 2.SmartConfig 工作原理
- 3.SmartConfig 协议类型
二、Wi‑Fi 智能配网类型定义及相关API
三、Wi‑Fi 智能配网示例程序
总结

前言

在物联网设备开发过程中，如果将 Wi-Fi 的 SSID 和密码直接写死在程序中肯定不合理。为了解决这一问题，ESP32 提供了多种配网方式，其中 SmartConfig 智能配网（又称“一键配网”）是一种常用且高效的方案。SmartConfig 可以让用户通过手机 App 将 Wi-Fi 网络的名称和密码发送给 ESP32 设备，从而避免在代码中硬编码 Wi-Fi 信息。本篇文章将基于最新的 ESP-IDF，介绍 Wi-Fi SmartConfig 的原理和使用方法，并重点演示 Espressif 自家的 ESPTouch 智能配网方式。

一、Wi‑Fi 智能配网概述

1.SmartConfig 简介

SmartConfig 是由德州仪器（TI）开发的一种 Wi-Fi 配网技术，用于将新的 Wi-Fi 设备连接到目标路由器。它的特点是在不建立传统网络连接的情况下，由手机等移动设备将 Wi-Fi 凭据通过广播的方式发送给待配网的设备。对于那些没有屏幕或输入接口的“无头”设备来说，SmartConfig 提供了一种简便的配网途径。利用 SmartConfig，用户无需直接在设备上输入或预先配置 Wi-Fi SSID 和密码，设备通电后进入配网模式，几分钟内即可完成网络连接。

2.SmartConfig 工作原理

SmartConfig 的实现原理是利用手机和路由器的广播机制传递 Wi-Fi 信息。在配网过程中，手机通过 App 将包含 Wi-Fi SSID 和密码的内容编码进一系列特殊的 UDP 广播数据包中，并在无线网络中发送出来。
在这里插入图片描述

ESP32 设备启动 SmartConfig 后，会进入 Wi-Fi 混杂模式轮循监听各个信道上的数据帧。当设备捕获到符合特定编码规则的广播包时，就能解析出其中包含的 Wi-Fi 名称和密码，并据此配置 ESP32 的 Wi-Fi STA 模式连接到对应的 AP（路由器）。如果在当前信道未能监听到有效数据，设备会切换到下一个信道继续监听，直到成功获取 Wi-Fi 信息为止。整个过程无需让手机直接与设备建立连接，避免了手动连接热点等繁琐步骤。

3.SmartConfig 协议类型

ESP32 平台目前支持三种类型的 SmartConfig 协议：Airkiss、ESPTouch 和 ESPTouch v2。其中，Airkiss 是腾讯微信推出的配网协议，常用于微信硬件平台；ESPTouch 则是乐鑫提供的官方配网协议，对应 Espressif 提供的手机 App（ESP-Touch）。开发者可以根据需求调用接口设定 SmartConfig 的类型。

需要特别说明的是 ESPTouch v2：从 SmartConfig v3.0 开始，ESP-IDF 新增了对 ESPTouch v2 的支持。相比传统的 ESPTouch，v2 版本采用了全新的算法提高了配网速度，并增加了 AES 加密传输和自定义数据字段等功能。这意味着在使用 ESPTouch v2 时，Wi-Fi 密码等敏感信息可以加密广播，提高了配网的安全性；但同时由于加密过程增加了数据传输量，在开启随机 IV（初始化向量）等安全特性时，配网所需时间可能略有增加。一般情况下，使用 ESPTouch（包括 v2）方式能满足多数应用需求。本文的示例也将采用 Espressif 官方的 ESPTouch 方法进行演示。

二、Wi‑Fi 智能配网类型定义及相关API

需包含头文件：esp_smartconfig.h：
Wi‑Fi 智能配网类型定义

/** SmartConfig 配网协议类型枚举 */
typedef enum {SC_TYPE_ESPTOUCH = 0,    // ESPTouch 配网（Espressif 官方协议）SC_TYPE_AIRKISS,         // AirKiss 配网（腾讯微信协议）SC_TYPE_ESPTOUCH_AIRKISS,// 组合配网模式（同时兼容 ESPTouch 和 AirKiss）SC_TYPE_ESPTOUCH_V2      // ESPTouch v2 配网（包含AES加密的改进版）
} smartconfig_type_t;/** SmartConfig 配网过程事件枚举 */
typedef enum {SC_EVENT_SCAN_DONE,      // 已完成周围 Wi-Fi 信道扫描SC_EVENT_FOUND_CHANNEL,  // 已找到目标路由器所在信道SC_EVENT_GOT_SSID_PSWD,  // 已获取到 Wi-Fi 的 SSID 和密码SC_EVENT_SEND_ACK_DONE   // 已发送确认信息（ACK）给手机端
} smartconfig_event_t;/* ===== GOT_SSID_PSWD 事件的数据结构 =====* 当拿到凭据时，事件回调会携带此结构体（从中取 ssid/password/bssid 等）*/
typedef struct {uint8_t ssid[32];         /* 目标 AP SSID（以 '\0' 结尾） */uint8_t password[64];     /* 对应密码（以 '\0' 结尾） */bool    bssid_set;        /* 是否携带并使用 BSSID（MAC）定向入网 */uint8_t bssid[6];         /* 目标 AP 的 BSSID（当 bssid_set = true 时有效） */smartconfig_type_t type;  /* 本次实际使用的协议类型（ESPTouch / AirKiss） */uint8_t token;            /* 与手机 App 通讯用的 token（ACK 用） */uint8_t cellphone_ip[4];  /* 手机的 IPv4 地址（便于双向确认） */
} smartconfig_event_got_ssid_pswd_t;/* ===== SmartConfig 启动配置 =====* 可开启日志、ESPTouch v2 加密（需 16 字节密钥）*/
typedef struct {bool  enable_log;                /* 配网过程打印日志（默认 false） */bool  esp_touch_v2_enable_crypt; /* 开启 v2 加密（true/false） */char *esp_touch_v2_key;          /* v2 加密密钥，长度需为 16 字节 */
} smartconfig_start_config_t;

Wi‑Fi 智能配网相关API

// 获取 SmartConfig 库版本号字符串
const char *esp_smartconfig_get_version(void);// 开始 SmartConfig 配网（Station 或 SoftAP-Sta模式下调用）
esp_err_t esp_smartconfig_start(const smartconfig_start_config_t *config);// 停止 SmartConfig 配网并释放资源（无论成功与否都应调用）
esp_err_t esp_smartconfig_stop(void);// 设置 SmartConfig 配网超时时间（单位秒，15~255，默认加45秒偏移，从寻找信道开始计时）
esp_err_t esp_esptouch_set_timeout(uint8_t time_s);// 设置 SmartConfig 配网协议类型（需在 esp_smartconfig_start 之前调用）
esp_err_t esp_smartconfig_set_type(smartconfig_type_t type);// 设置是否启用快速模式（需在 esp_smartconfig_start 之前调用）
esp_err_t esp_smartconfig_fast_mode(bool enable);// 获取 ESPTouch v2 配网的预留数据（在 SC_EVENT_GOT_SSID_PSWD 事件后调用）
esp_err_t esp_smartconfig_get_rvd_data(uint8_t *rvd_data, uint8_t len);

三、Wi‑Fi 智能配网示例程序

本程序演示如何使用ESP-Touch智能配网功能。
让ESP32通过手机APP自动获取WiFi的SSID和密码，无需在代码中硬编码 WiFi 信息。

/** ESP32-S3 智能配网（SmartConfig）示例** 本程序演示如何使用ESP-Touch智能配网功能，让ESP32通过手机APP* 自动获取WiFi的SSID和密码，无需在代码中硬编码WiFi信息。** 智能配网流程：* 1. ESP32启动后进入SmartConfig模式，等待配网* 2. 用户使用手机APP（如ESP-Touch）发送WiFi信息* 3. ESP32接收到WiFi信息后自动连接* 4. 连接成功后退出配网模式**/#include <string.h>                // 字符串处理函数
#include "freertos/FreeRTOS.h"     // FreeRTOS实时操作系统
#include "freertos/task.h"         // 任务管理
#include "freertos/event_groups.h" // 事件组（用于任务间通信）
#include "esp_wifi.h"              // WiFi驱动
#include "esp_event.h"             // 事件处理
#include "esp_smartconfig.h"       // 智能配网功能
#include "esp_netif.h"             // 网络接口
#include "nvs_flash.h"             // 非易失性存储
#include "esp_log.h"               // 日志输出// ======================== 事件位定义 ========================
// 使用事件组来标记不同的状态
static const int CONNECTED_BIT = BIT0;     // 位0：WiFi连接成功标志
static const int ESPTOUCH_DONE_BIT = BIT1; // 位1：ESP-Touch配网完成标志// ======================== 全局变量 ========================
static EventGroupHandle_t s_wifi_event_group; // 事件组句柄，用于任务间通信
static const char *TAG = "smartconfig";       // 日志标签/** 事件处理函数 - 处理WiFi和SmartConfig相关事件** 参数说明：* - arg: 用户数据（本例中未使用）* - event_base: 事件类型（WIFI_EVENT、IP_EVENT、SC_EVENT等）* - event_id: 具体的事件ID* - event_data: 事件携带的数据** 这个函数会在WiFi状态或SmartConfig状态发生变化时自动被调用*/
static void event_handler(void *arg,                   // 用户参数（未使用）esp_event_base_t event_base, // 事件基础类型int32_t event_id,            // 事件IDvoid *event_data)            // 事件数据
{// 处理WiFi STA启动事件if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_START){esp_wifi_connect(); // WiFi启动后立即尝试连接ESP_LOGI(TAG, "WiFi STA启动，开始连接...");}// 处理WiFi断开连接事件else if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED){esp_wifi_connect(); // 断开后自动重连ESP_LOGI(TAG, "WiFi断开连接，正在重连...");}// 处理获取IP地址事件else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP){ip_event_got_ip_t *event = (ip_event_got_ip_t *)event_data;char ip[16];esp_ip4addr_ntoa(&event->ip_info.ip, ip, sizeof(ip));ESP_LOGI(TAG, "🎉 WiFi连接成功！获取到IP地址: %s", ip);xEventGroupSetBits(s_wifi_event_group, CONNECTED_BIT); // 设置连接成功标志}// 处理SmartConfig扫描完成事件else if (event_base == SC_EVENT && event_id == SC_EVENT_SCAN_DONE){ESP_LOGI(TAG, "SmartConfig扫描完成");}// 处理SmartConfig找到信道事件else if (event_base == SC_EVENT && event_id == SC_EVENT_FOUND_CHANNEL){ESP_LOGI(TAG, "SmartConfig找到目标信道");}// 处理SmartConfig获取SSID和密码事件else if (event_base == SC_EVENT && event_id == SC_EVENT_GOT_SSID_PSWD){ESP_LOGI(TAG, "SmartConfig获取到WiFi信息");// 获取SmartConfig传递的WiFi信息smartconfig_event_got_ssid_pswd_t *evt = (smartconfig_event_got_ssid_pswd_t *)event_data;wifi_config_t wifi_config;                // WiFi配置结构体bzero(&wifi_config, sizeof(wifi_config)); // 清零配置结构体// 复制SSID和密码到WiFi配置中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_LOGI(TAG, "SSID: %s", wifi_config.sta.ssid);ESP_LOGI(TAG, "密码: %s", wifi_config.sta.password);// 先断开当前连接，然后应用新的WiFi配置esp_wifi_disconnect();                          // 断开当前连接esp_wifi_set_config(WIFI_IF_STA, &wifi_config); // 设置新的WiFi配置esp_wifi_connect();                             // 使用新配置连接WiFi}// 处理SmartConfig发送确认完成事件else if (event_base == SC_EVENT && event_id == SC_EVENT_SEND_ACK_DONE){ESP_LOGI(TAG, "✅ SmartConfig配网完成");xEventGroupSetBits(s_wifi_event_group, ESPTOUCH_DONE_BIT); // 设置配网完成标志}
}/** SmartConfig任务函数** 这个任务负责：* 1. 启动ESP-Touch智能配网* 2. 等待WiFi连接成功或配网完成* 3. 配网完成后停止SmartConfig并删除自己** 参数：parm - 任务参数（未使用）*/
static void smartconfig_task(void *parm) // 任务参数（未使用）
{EventBits_t uxBits; // 用于接收事件位的变量ESP_LOGI(TAG, "启动SmartConfig配网任务");// 配置SmartConfig参数smartconfig_start_config_t cfg = SMARTCONFIG_START_CONFIG_DEFAULT(); // 使用默认配置esp_smartconfig_set_type(SC_TYPE_ESPTOUCH);                          // 设置配网类型为ESP-Touchesp_smartconfig_start(&cfg);                                         // 启动SmartConfigESP_LOGI(TAG, "请使用ESP-Touch手机APP进行配网");ESP_LOGI(TAG, "等待手机发送WiFi配置信息...");// 主循环：等待事件while (1){// 等待事件位：WiFi连接成功 或 ESP-Touch配网完成uxBits = xEventGroupWaitBits(s_wifi_event_group,                // 事件组句柄CONNECTED_BIT | ESPTOUCH_DONE_BIT, // 等待的事件位true,                              // 读取后清除事件位false,                             // 只要有一个事件位被设置就返回portMAX_DELAY);                    // 无限等待// 检查WiFi是否连接成功if (uxBits & CONNECTED_BIT){ESP_LOGI(TAG, "WiFi连接成功！");}// 检查ESP-Touch配网是否完成if (uxBits & ESPTOUCH_DONE_BIT){ESP_LOGI(TAG, "ESP-Touch配网流程完成");esp_smartconfig_stop(); // 停止SmartConfigESP_LOGI(TAG, "SmartConfig已停止");vTaskDelete(NULL); // 删除当前任务（自我删除）}}
}/** WiFi初始化函数** 这个函数完成以下工作：* 1. 初始化网络栈和事件循环* 2. 创建WiFi STA接口* 3. 初始化WiFi驱动* 4. 创建事件组* 5. 注册事件处理函数* 6. 设置WiFi模式并启动*/
static void wifi_init(void)
{ESP_LOGI(TAG, "🔧 开始初始化WiFi系统");// 第1步：初始化网络接口层ESP_ERROR_CHECK(esp_netif_init()); // 初始化TCP/IP网络栈// 第2步：创建默认事件循环ESP_ERROR_CHECK(esp_event_loop_create_default()); // 创建默认事件循环// 第3步：创建默认WiFi STA接口esp_netif_create_default_wifi_sta(); // 创建STA网络接口// 第4步：初始化WiFi驱动wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT(); // 使用默认WiFi配置ESP_ERROR_CHECK(esp_wifi_init(&cfg));                // 初始化WiFi驱动// 第5步：创建事件组（用于任务间通信）s_wifi_event_group = xEventGroupCreate(); // 创建事件组// 第6步：注册事件处理函数// 注册WiFi事件处理器ESP_ERROR_CHECK(esp_event_handler_instance_register(WIFI_EVENT,       // 事件类型：WiFi事件ESP_EVENT_ANY_ID, // 事件ID：所有WiFi事件&event_handler,   // 事件处理函数NULL,             // 用户数据NULL));           // 事件处理器实例// 注册IP事件处理器ESP_ERROR_CHECK(esp_event_handler_instance_register(IP_EVENT,            // 事件类型：IP事件IP_EVENT_STA_GOT_IP, // 事件ID：获取IP地址&event_handler,      // 事件处理函数NULL,                // 用户数据NULL));              // 事件处理器实例// 注册SmartConfig事件处理器ESP_ERROR_CHECK(esp_event_handler_instance_register(SC_EVENT,         // 事件类型：SmartConfig事件ESP_EVENT_ANY_ID, // 事件ID：所有SC事件&event_handler,   // 事件处理函数NULL,             // 用户数据NULL));           // 事件处理器实例// 第7步：设置WiFi模式并启动ESP_ERROR_CHECK(esp_wifi_set_mode(WIFI_MODE_STA)); // 设置为STA（客户端）模式ESP_ERROR_CHECK(esp_wifi_start());                 // 启动WiFiESP_LOGI(TAG, "✅ WiFi系统初始化完成");
}/** 程序主入口函数** 这是ESP32程序的起始点，完成以下工作：* 1. 初始化NVS存储* 2. 清除之前保存的WiFi配置（可选）* 3. 初始化WiFi系统* 4. 创建SmartConfig配网任务*/
void app_main(void)
{ESP_LOGI(TAG, "ESP32 SmartConfig智能配网程序启动");// 第1步：初始化NVS存储esp_err_t ret = nvs_flash_init(); // 初始化NVSif (ret == ESP_ERR_NVS_NO_FREE_PAGES || ret == ESP_ERR_NVS_NEW_VERSION_FOUND){ESP_ERROR_CHECK(nvs_flash_erase()); // 如果有问题就擦除ESP_ERROR_CHECK(nvs_flash_init());  // 重新初始化}ESP_LOGI(TAG, "✅ NVS存储初始化完成");// 第2步：清除之前保存的WiFi配置（强制重新配网）// 注意：如果您希望保留之前的WiFi配置，请注释掉下面这行ESP_ERROR_CHECK(nvs_flash_erase_partition("nvs"));ESP_ERROR_CHECK(nvs_flash_init());ESP_LOGI(TAG, "已清除之前的WiFi配置，强制重新配网");// 第3步：初始化WiFi系统wifi_init(); // 调用WiFi初始化函数// 第4步：创建SmartConfig配网任务xTaskCreate(smartconfig_task,   // 任务函数"smartconfig_task", // 任务名称4096,               // 任务堆栈大小（字节）NULL,               // 任务参数3,                  // 任务优先级NULL);              // 任务句柄ESP_LOGI(TAG, "SmartConfig任务已创建");ESP_LOGI(TAG, "系统已准备就绪，等待配网...");
}

总结

通过本篇内容，我们了解了 SmartConfig 智能配网的原理和使用方法。在 ESP32 上利用 SmartConfig，可以让设备在运行时通过手机快速获取 Wi-Fi 凭据，实现开箱即用的联网体验。文中介绍了 ESPTouch 和 Airkiss 两种主要协议及其区别，并基于最新 ESP-IDF 提供的 API 展示了如何在代码中集成 SmartConfig 功能。希望通过本文的讲解，开发者可以熟练运用 SmartConfig，为自己的 ESP32 项目实现更加灵活友好的网络配置功能。