目錄前言一、WIFI配網(wǎng)1.1 為什么需要配網(wǎng)1.2 常見配網(wǎng)方式二、SmartConfig配網(wǎng)2.1 基本工作原理2.2 SmartConfig 的協(xié)議類型2.2.1 ESPTouch2.2.2 AirKiss2.2.3 ESPTouch v2 的改進支持加密支持自定義數(shù)據(jù)更適合產(chǎn)品化2.2.4 手機操作三、工程實現(xiàn)3.1 模塊流程3.2 初始化配網(wǎng)模塊3.3 獲取憑據(jù)并連接3.4 Console 啟動命令3.5 結(jié)果查看四、免費資源總結(jié)前言前面我們已經(jīng)學習Station、softAP和now等WIFI技術現(xiàn)在接觸下一個模塊——WIFI配網(wǎng)。wifi配網(wǎng)是一個wifi設備不可或缺的重要功能wifi配網(wǎng)的方法有很多常見的有SmartConfig、Soft-AP配網(wǎng)、藍牙配網(wǎng)等每種方法都有其特點和使用場景通常一個wifi設備會支持多種配網(wǎng)方案的組合以便用戶可以根據(jù)實際情況靈活調(diào)整。本章具體介紹一下SmartConfig方法。一、WIFI配網(wǎng)Wi?Fi 配網(wǎng)Wi?Fi Provisioning就是把無線路由器的 SSIDWi?Fi 名稱和密碼等信息傳遞給一個尚未聯(lián)網(wǎng)的設備使設備能夠以 STAStation模式連接到指定路由器并獲得 IP 地址的過程。1.1 為什么需要配網(wǎng)手機、電腦通?？梢灾苯油ㄟ^界面輸入 Wi?Fi 密碼但許多物聯(lián)網(wǎng)設備沒有屏幕和鍵盤例如ESP32 開發(fā)板智能插座Wi?Fi 燈泡傳感器節(jié)點無線攝像頭。因此這些設備需要借助手機或其他設備將 Wi?Fi 憑據(jù)傳輸給它之后設備才能連接家庭路由器并訪問局域網(wǎng)或互聯(lián)網(wǎng)。1.2 常見配網(wǎng)方式配網(wǎng)方式基本原理特點SmartConfig手機通過 Wi?Fi 數(shù)據(jù)包廣播配網(wǎng)信息設備監(jiān)聽并解析不需要設備建立熱點操作較方便SoftAP 配網(wǎng)ESP32 創(chuàng)建臨時熱點手機連接該熱點后發(fā)送 Wi?Fi 信息原理直觀、兼容性較好藍牙 BLE 配網(wǎng)手機通過藍牙連接設備并寫入 Wi?Fi 參數(shù)體驗較好適合支持 BLE 的設備二維碼配網(wǎng)手機顯示包含 Wi?Fi 信息的二維碼設備通過攝像頭識別適合帶攝像頭的設備有線或串口配網(wǎng)通過 USB、串口等接口寫入網(wǎng)絡參數(shù)適合調(diào)試和工程生產(chǎn)環(huán)節(jié)需要注意配網(wǎng)不是普通的 Wi?Fi 連接過程。Wi?Fi 連接是設備已經(jīng)知道 SSID 和密碼之后執(zhí)行的連接動作配網(wǎng)則是設備還不知道這些信息時先通過某種通信方式獲得網(wǎng)絡參數(shù)。此外配網(wǎng)過程中會傳輸 Wi?Fi 密碼因此實際產(chǎn)品中應考慮傳輸安全、配網(wǎng)超時、錯誤重試、憑據(jù)擦除以及防止陌生設備獲取密碼等問題。二、SmartConfig配網(wǎng)SmartConfig 是一種通過手機廣播 Wi?Fi 配置信息使未聯(lián)網(wǎng)設備自動獲取路由器 SSID 和密碼并連接到目標 Wi?Fi 網(wǎng)絡的配網(wǎng)技術。它最初由 TI 提出樂鑫在 ESP32 系列芯片中主要通過 ESP-Touch 等協(xié)議實現(xiàn)。它特別適合 ESP32、智能插座、傳感器等沒有屏幕和鍵盤的“無頭設備”。用戶只需在手機 App 中輸入 Wi?Fi 密碼并啟動配網(wǎng)設備即可監(jiān)聽并解析手機發(fā)送的數(shù)據(jù)而不需要手機直接連接設備熱點。2.1 基本工作原理以 ESP32 的 ESP-Touch 為例流程大致如下ESP32 進入 SmartConfig 模式并開啟 Wi?Fi 混雜模式監(jiān)聽周圍的無線報文手機連接目標路由器的 Wi?Fi并在 App 中輸入 Wi?Fi 密碼手機通過 UDP 廣播或組播發(fā)送經(jīng)過編碼的配網(wǎng)數(shù)據(jù)ESP32 根據(jù)報文長度、地址等特征提取并解析 SSID、密碼等信息ESP32 退出監(jiān)聽狀態(tài)切換為 STA 模式并連接路由器連接成功后設備獲取 IP 地址并可向手機反饋配網(wǎng)結(jié)果。需要注意的是ESP32 在配網(wǎng)初期通常無法直接讀取普通 Wi?Fi 數(shù)據(jù)幀中的應用層內(nèi)容因為無線網(wǎng)絡可能啟用了加密。因此SmartConfig 協(xié)議通常利用報文長度等可觀察特征對數(shù)據(jù)進行編碼和傳輸。2.2 SmartConfig 的協(xié)議類型ESP-IDF 文檔中ESP32-S3 等芯片支持 AirKiss、ESPTouch 和 ESPTouch v2 等 SmartConfig 類型。部分 ESP-AT 固件還支持組合模式例如ESP-TOUCH AirKiss。協(xié)議來源或應用主要特點適用情況ESPTouch樂鑫 ESP-Touch 方案采用 ESP-Touch 配網(wǎng)機制適合樂鑫生態(tài)自己開發(fā) ESP32 App 或使用樂鑫示例AirKiss微信生態(tài)常用方案便于與微信及相關物聯(lián)網(wǎng)平臺結(jié)合微信小程序、公眾號或微信生態(tài)配網(wǎng)ESPTouch v2ESPTouch 的改進版本支持更完善的安全機制和自定義數(shù)據(jù)新項目、對安全性和擴展性有要求的產(chǎn)品ESPTouch AirKiss雙協(xié)議模式同時兼容兩種配網(wǎng)方式希望兼容不同手機 App 或平臺2.2.1 ESPTouchESPTouch 是樂鑫推出的配網(wǎng)協(xié)議目標是讓手機通過 SmartConfig 機制把 Wi?Fi 信息傳遞給 ESP8266 或 ESP32 設備。樂鑫提供了對應的 Android、iOS 端資源及設備端實現(xiàn)。它的優(yōu)點是與 ESP-IDF 集成較好適合 ESP32 自定義 App設備端開發(fā)資料較多可以結(jié)合 ESP-Touch v2 擴展安全和自定義數(shù)據(jù)。如果你是在 ESP-IDF 中編寫 ESP32 固件并且控制手機端 App那么 ESPTouch 通常是更自然的選擇。2.2.2 AirKissAirKiss 更偏向微信生態(tài)。其優(yōu)勢不是 ESP32 底層性能更好而是便于接入微信相關的配網(wǎng)流程。相關平臺和 App 需要按照 AirKiss 的協(xié)議格式發(fā)送數(shù)據(jù)。它適合微信小程序配網(wǎng)微信公眾號配網(wǎng)已經(jīng)使用微信物聯(lián)網(wǎng)平臺的產(chǎn)品不希望單獨開發(fā)完整手機 App 的場景。因此AirKiss 與 ESPTouch 的主要差異更多體現(xiàn)在手機端和平臺生態(tài)而不是 ESP32 的 STA 連接過程。2.2.3 ESPTouch v2 的改進ESPTouch v2 是對傳統(tǒng) ESPTouch 的增強版本重點改善了以下方面支持加密傳統(tǒng) SmartConfig 的風險在于Wi?Fi 密碼會通過無線環(huán)境傳遞如果沒有額外保護附近具備監(jiān)聽能力的設備可能嘗試恢復配網(wǎng)信息。ESPTouch v2 可以配合 AES 等機制保護配網(wǎng)數(shù)據(jù)。這樣即使攻擊者捕獲無線報文也不能直接得到明文密碼但手機端和 ESP32 必須使用相同的密鑰或約定配置復雜度也會增加。支持自定義數(shù)據(jù)ESPTouch v2 不僅可以傳輸 SSID 和密碼還可以攜帶廠商自定義信息例如設備編號產(chǎn)品型號用戶綁定信息云平臺 Token臨時配網(wǎng)參數(shù)。不過這些自定義數(shù)據(jù)不應直接替代完整的身份認證機制。生產(chǎn)產(chǎn)品仍然需要考慮設備唯一密鑰、服務端校驗和防重放攻擊。更適合產(chǎn)品化傳統(tǒng) ESPTouch 更適合快速實現(xiàn)和實驗驗證而 ESPTouch v2 更適合產(chǎn)品中使用。尤其是在需要加密、設備綁定、批量部署和擴展字段時v2 的工程適應性更好。一句話概括SmartConfig 就是“手機通過 Wi?Fi 廣播把網(wǎng)絡憑據(jù)發(fā)送出去ESP32 監(jiān)聽并解析這些信息然后自動連接路由器”的配網(wǎng)方式。2.2.4 手機操作對于ESPTouch 和 ESPTouch v2協(xié)議使用的手機軟件可以去樂鑫官網(wǎng)下載App樂鑫科技Android版本ESP-TOUCH for AndroidIOS版本ESP-TOUCH for iOS使用AirKiss協(xié)議的話微雪公眾號里搜索《樂鑫信息科技》關注之后在公眾號菜單欄選擇“產(chǎn)品資源”“Airkiss設備”即可配置上網(wǎng)。三、工程實現(xiàn)模塊以 Console 命令觸發(fā)配網(wǎng) 為入口以SC_EVENT事件為主線在獲取到 Wi-Fi 憑據(jù)后切換到正常的 STA 連接流程并在手機端確認收到 ACK 后結(jié)束 SmartConfig 會話。工程實現(xiàn)的核心目標如下允許用戶通過串口命令隨時進入 ESPTouch v2 配網(wǎng)模式配網(wǎng)前主動斷開舊的 STA 連接避免連接狀態(tài)與配網(wǎng)狀態(tài)沖突在SC_EVENT_GOT_SSID_PSWD中取得 SSID、密碼和可選附加數(shù)據(jù)使用統(tǒng)一的 Wi-Fi 連接邏輯完成入網(wǎng)復用已有的重連與狀態(tài)管理機制在配網(wǎng)流程完成后調(diào)用esp_smartconfig_stop()釋放 SmartConfig 相關資源3.1 模塊流程從用戶輸入配網(wǎng)命令到設備獲得 IP 地址整體流程如圖所示SmartConfig 只負責將網(wǎng)絡憑據(jù)傳遞給設備真正的 Wi-Fi 關聯(lián)、認證、DHCP 獲取地址以及后續(xù)掉線重連仍由 Wi-Fi STA 驅(qū)動和已有的WIFI_EVENT、IP_EVENT處理邏輯負責。3.2 初始化配網(wǎng)模塊配網(wǎng)模塊初始化應在 Wi-Fi 基礎設施準備完成后執(zhí)行。這里主要完成超時時間配置、STA 初始化、SmartConfig 事件注冊以及 Console 命令注冊。int wifi_smartconfig_init(uint8_t time_s) { /* 1. 設置配網(wǎng)超時時間秒 */ esp_esptouch_set_timeout(time_s); /* 2. 初始化 STA攜帶配網(wǎng)標志STA_START 時自動啟動配網(wǎng) */ wifi_station_init(ESP32C6, smartconfig_mode); /* 3. 注冊 SC_EVENT 回調(diào)須在事件循環(huán)創(chuàng)建之后 */ 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, 智能配網(wǎng)模塊已初始化當前版本: %s, esp_smartconfig_get_version()); return ESP_OK; }esp_esptouch_set_timeout()用于設置 ESPTouch 的超時周期。若設備在指定時間內(nèi)未完成配網(wǎng)SmartConfig 會重新開始掃描和監(jiān)聽超時時間不宜設置過短否則用戶尚未來得及在手機端發(fā)起配網(wǎng)設備就可能提前進入下一輪掃描。建議在實際產(chǎn)品中將超時時間設置為 60 至 120 秒并在超時、連續(xù)失敗或用戶主動取消時給出 LED、蜂鳴器或串口日志等明確反饋。3.3 獲取憑據(jù)并連接以下代碼放在統(tǒng)一事件處理函數(shù)中用于處理SC_EVENT。實現(xiàn)重點是先解析事件數(shù)據(jù)再填充wifi_config_t最后由esp_wifi_connect()啟動正常 STA 連接。/* SC 事件 */ else if(event_base SC_EVENT) { switch (event_id) { /* ---------- SC_EVENT_SCAN_DONE — 配網(wǎng)掃描完成 ---------- * SmartConfig 內(nèi)部掃描結(jié)束需再次觸發(fā)掃描直至鎖定目標信道 */ 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 — 配網(wǎng)成功獲得 SSID/密碼 ---------- * 解析結(jié)果同步進 wifi_event 結(jié)構(gòu)體與 connect 命令共用同一狀態(tài) * 復用 wifi_station_connect() 發(fā)起連接 —— 后續(xù) STA_CONNECTED / * STA_DISCONNECTED 按原分類策略處理不產(chǎn)生路徑?jīng)_突。 */ 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 事件數(shù)據(jù)為空忽略); break; } ESP_LOGI(TAG, SmartConfig 獲取到 SSID 和密碼); ESP_LOGI(TAG, SmartConfig SSID: %s, evt-ssid); ESP_LOGI(TAG, SmartConfig Password: %s, evt-password); /* ESPTouch V2 附加數(shù)據(jù)讀取事件回調(diào)中避免 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 附加數(shù)據(jù)失敗: %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發(fā)送 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 發(fā)起配網(wǎng)時除了 SSID 與密碼還可以附帶一段自定義保留數(shù)據(jù)Reserved Data簡稱 RVD Data。該數(shù)據(jù)可用于傳遞臨時綁定 Token、設備激活參數(shù)、區(qū)域標識或業(yè)務配置標志等信息。3.4 Console 啟動命令為了方便調(diào)試和測試本工程將 SmartConfig 封裝為獨立的 Console 命令。執(zhí)行命令前先斷開現(xiàn)有網(wǎng)絡再停止殘留會話可以通過命令參數(shù)來選擇SmartConfig 的協(xié)議類型。static int smartconfig_cmd_handler(int argc, char **argv) { wifi_ap_record_t ap_info; /* 1. 解析配網(wǎng)協(xié)議類型默認 ESPTouch V2無需參數(shù)即可直接啟動 */ 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 配網(wǎng)默認\r\n); printf( air - AirKiss 配網(wǎng)\r\n); return 1; } } /* 2. 檢查聯(lián)網(wǎng)狀態(tài)已連接或連接中則先斷開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. 停止可能殘留的舊配網(wǎng)會話冪等 */ esp_err_t ret esp_smartconfig_stop(); if (ret ! ESP_OK) { ESP_LOGD(TAG, 無正在運行的配網(wǎng)會話: %s, esp_err_to_name(ret)); } /* 4. 啟動 SmartConfig 配網(wǎng) */ 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) 配網(wǎng)已啟動請用手機 App 發(fā)送 WiFi 憑證, (sc_type SC_TYPE_AIRKISS) ? AirKiss : ESPTouch V2); return 0; }這種“先斷開、再清理、后啟動”的流程能避免設備同時處于舊網(wǎng)絡重連和 SmartConfig 監(jiān)聽狀態(tài)從而減少狀態(tài)競爭和日志混亂。對于使用自動重連機制的工程尤其要先關閉retry_enabled否則斷開舊連接后重連任務可能會搶占配網(wǎng)流程。3.5 結(jié)果查看注意以下內(nèi)容我是在手機熱點作為AP嘗試的成功實現(xiàn)同時我嘗試了用另一塊ESP32的softAP功能但始終無法連接成功。好像對于ESP32的softAP使用ESPTouch v2配網(wǎng)無法接收配網(wǎng)數(shù)據(jù)包。不知是不是有其他遺漏之處若有同學實現(xiàn)了還請留言不勝感激展示使用ESPTouch v2協(xié)議對于AirKiss協(xié)議更加間接更換協(xié)議只需要在Console 啟動命令中輸入對應參數(shù)皆可。板子上電后控制臺輸入命令smartconfig會啟動 smartconfig 配網(wǎng)功能當代碼調(diào)用esp_smartconfig_start后此時ESP32 并不知道手機在哪個信道上發(fā)包所以驅(qū)動會把當前環(huán)境中所有信道都便利一遍。當查找到環(huán)境中所有可用信道后比如1、6、11接下來會不斷在這些信道輪詢交替用來監(jiān)聽可能或出現(xiàn)的數(shù)據(jù)包。類似如下注意要明白一個前提兩個無線設備只要處于同樣信道下便可通信這是電磁波的特性頻率相同只不過于人們設置了各種協(xié)議和保護通信得到的數(shù)據(jù)包無法解析。此時先給手機連接上一個2.4G的wifi然后打開手機ESPTouch軟件選擇SmartConfig 的協(xié)議此時ESP32 就抓住了空中SmartConfig 配網(wǎng)數(shù)據(jù)包觸發(fā)SC_EVENT_FOUND_CHANNEL事件此時會等待我們設定的超時時間再該時間內(nèi)我們只要在手機ESPTouch軟件輸入該wifi的SSID和密碼ESP32就會觸發(fā)SC_EVENT_GOT_SSID_PSWD事件從而獲得這些信息就能成功聯(lián)網(wǎng)了。在我的代碼中如果想換一個wifi只需要控制臺輸入 smartconfig 命令就能重新啟動SmartConfig從而可以連接新的wifi。需要注意獲取到 SSID 和密碼并不代表已經(jīng)聯(lián)網(wǎng)成功實際工程中應以IP_EVENT_STA_GOT_IP作為 STA 聯(lián)網(wǎng)成功的判斷依據(jù)。四、免費資源以上完整工程可以進入我的Gitee中下載《https://gitee.com/pai-schoolmate/esp32_project.git》本工程路徑esp32_project-main\function\provisioning總結(jié)在工程設計上本文采用事件驅(qū)動方式處理SC_EVENT、WIFI_EVENT和IP_EVENT通過 Console 命令啟動配網(wǎng)并對舊連接、自動重連、憑據(jù)解析和 SmartConfig 會話進行統(tǒng)一管理。實踐表明SC_EVENT_GOT_SSID_PSWD僅代表設備成功獲取網(wǎng)絡參數(shù)最終應以IP_EVENT_STA_GOT_IP作為聯(lián)網(wǎng)成功的判斷依據(jù)。SmartConfig 具有使用便捷、無需額外硬件和適合無屏設備等特點但其穩(wěn)定性受手機、路由器頻段及無線環(huán)境影響。實際產(chǎn)品中還應進一步完善配網(wǎng)超時、失敗重試、憑據(jù)保護、設備綁定和備用配網(wǎng)方案以提升系統(tǒng)的可靠性、安全性與產(chǎn)品適應性。