BluFi 配網指南
BluFi 是 Espressif 官方提供的 BLE Wi-Fi 配網解決方案。本文件說明如何在小智韌體中啟用和使用 BluFi 配網功能。
前置條件
- 需要支援 BLE 的 ESP32 晶片與韌體配置
- 在
idf.py menuconfig中啟用WiFi Configuration Method -> ESP-BluFi - 保持預設的 NVS 與事件迴圈初始化（專案的
app_main已處理）
配置說明
1. 啟用 BluFi
在 menuconfig 中設定：
CONFIG_USE_ESP_BLUFI_WIFI_PROVISIONING=y注意：如果想使用 BluFi，必須關閉同一選單下的 Hotspot 選項，否則預設使用熱點配網模式。
2. 藍芽配置
CONFIG_BT_BLUEDROID_ENABLED 和 CONFIG_BT_NIMBLE_ENABLED 這兩個宏應二選一，不能同時啟用。
3. 裝置名稱
裝置的藍芽廣播名稱為 Xiaozhi-Blufi（韌體在 ESP_BLUFI_EVENT_INIT_FINISH 事件中設定）。舊版韌體在 ESP-IDF 5.5.1 下編譯時名稱為 BLUFI_DEVICE；當前韌體要求 ESP-IDF v6.0.1 或更高版本，名稱統一為 Xiaozhi-Blufi。
工作流程
flowchart LR
A[手機 BluFi 客戶端] --> B[連線裝置 BLE]
B --> C[傳送 Wi-Fi 憑據]
C --> D[裝置寫入 NVS]
D --> E[啟動 Wi-Fi 連線]
E --> F{連線成功?}
F -->|是| G[配網完成]
F -->|否| H[返回失敗狀態]
- 手機端透過 BluFi（如官方 EspBlufi App 或自研客戶端）連線裝置，傳送 Wi-Fi SSID/密碼；手機端也可以透過 BluFi 協議獲取裝置掃描到的 Wi-Fi 列表
- 裝置側在
ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP中將憑據寫入SsidManager - 啟動
WifiStation掃描並連線，狀態透過 BluFi 返回 - 配網成功後裝置會自動連線新 Wi-Fi
使用步驟
1. 編譯韌體
配置並編譯韌體：
idf.py menuconfig # 啟用 ESP-BluFi
idf.py build
idf.py flash2. 觸發配網
裝置首次啟動且沒有已儲存的 Wi-Fi 時會自動進入配網模式。
3. 手機端操作
- 開啟 EspBlufi App（或其他 BluFi 客戶端）
- 搜尋並連線裝置（可選擇是否加密）
- 按提示輸入 Wi-Fi SSID/密碼併傳送
4. 觀察結果
- 成功：BluFi 報告連線成功，裝置自動連線 Wi-Fi
- 失敗：BluFi 返回失敗狀態，可重新傳送或檢查路由器
注意事項
- 互斥性：BluFi 配網不支援與熱點配網同時開啟；如果熱點配網已經啟動，則預設使用熱點配網。請確保 menuconfig 中只保留一種配網方式
- 儲存清除：多次測試時，建議清除 NVS 中
wifi名稱空間的舊配置，避免干擾 - 協議規範：使用自定義 BluFi 客戶端需遵循官方協議幀格式