小智xiaozhi-esp32BluFi 配网完全指南基于 esp-wifi-connect 的 BLE Wi-Fi 配网实战【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本文档面向使用小智xiaozhi-esp32固件的开发者系统讲解如何在固件中启用并实际使用 BluFiBLE Wi‑Fi 配网功能。文章以仓库中的 BluFi 配网文档 为主体结合main/boards/common/blufi.cpp、main/Kconfig.projbuild等源码实现说明 menuconfig 配置、完整配网工作流程、手机端操作步骤以及 IDF 版本差异等关键细节。读完本文你将掌握在小智固件上从零启用 BluFi、通过手机 App 完成 Wi‑Fi 下发、并结合esp-wifi-connect组件持久化凭据的完整方案。BluFi 与小智固件的配网体系BluFi 是乐鑫Espressif提供的一种基于 BLE 的 Wi‑Fi 配网协议手机通过低功耗蓝牙与设备建立 GATT 连接安全地传输 Wi‑Fi SSID 与密码设备收到凭据后自行连接路由器。它解决了无屏幕、无按键设备难以输入 Wi‑Fi 信息的痛点是小智固件中与「热点配网Hotspot」并列的两种配网方式之一。在小智固件中BluFi 的实现位于 main/boards/common/blufi.cpp 与 main/boards/common/blufi.h以单例类Blufi的形式封装了蓝牙控制器/协议栈初始化、GAP 回调注册、Wi‑Fi 扫描、凭据下发与连接状态上报等全部逻辑。配网得到的凭据并不由 BluFi 自己存储而是写入SsidManager对应esp-wifi-connect组件的持久化层最终保存在 NVS 中随后由WifiStation负责实际扫描连接——这正是文档标题中「集成 esp-wifi-connect」的含义。前置条件启用 BluFi 配网需要满足以下条件支持 BLE 的芯片与固件配置BluFi 依赖 BLE 协议栈因此目标芯片必须支持 BLE且固件需开启蓝牙相关选项。小智固件在CONFIG_USE_ESP_BLUFI_WIFI_PROVISIONING被启用时会自动通过 Kconfig 的select级联打开BT_ENABLED、BT_BLE_42_FEATURES_SUPPORTED与BT_BLE_BLUFI_ENABLE无需手工逐个配置。在idle.py menuconfig中启用配网方式进入WiFi Configuration Method菜单对应源码 main/Kconfig.projbuild将WiFi Configuration Method - ESP-BluFi置为开启对应宏CONFIG_USE_ESP_BLUFI_WIFI_PROVISIONINGy。必须关闭同菜单下的 Hotspot 选项HotspotCONFIG_USE_HOTSPOT_WIFI_PROVISIONING默认开启default y。由于两种配网方式互斥如果 Hotspot 仍为开启状态设备将默认走热点配网BluFi 不会生效。保持默认的 NVS 与事件循环初始化esp-wifi-connect的SsidManager依赖 NVS 存储凭据配网状态上报依赖系统事件循环项目的app_main已统一处理无需额外改动。蓝牙协议栈宏二选一CONFIG_BT_BLUEDROID_ENABLEDBluedroid与CONFIG_BT_NIMBLE_ENABLEDNimBLE不能同时启用。从源码结构看blufi.cpp对两种协议栈分别实现了_host_init/_host_deinit等分支见 main/boards/common/blufi.cpp编译期通过宏区分因此必须保证两者互斥。scripts/ci/blufi.sdkconfig.defaults给出了一个最小可用的 CI 配置示例可作参考CONFIG_BOARD_TYPE_BREAD_COMPACT_WIFIy CONFIG_USE_ESP_BLUFI_WIFI_PROVISIONINGy工作流程小智固件中 BluFi 配网的完整流程如下设备侧准备设备启动后若未保存任何 Wi‑Fi 凭据WifiBoard::StartWifiConfigMode()会进入配网状态并调用Blufi::GetInstance().init()见 main/boards/common/wifi_board.cc。init()会尽早启动一次 Wi‑Fi 扫描使设备在手机连接前就准备好热点列表缓存。手机端连接手机通过 BluFi 客户端如官方 EspBlufi App 或自研客户端扫描并连接设备广播的 BLE 服务双方协商加密后手机发送 Wi‑Fi SSID/密码手机端还可以通过 BluFi 协议主动获取设备扫描到的 Wi‑Fi 列表。凭据写入设备在ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP事件中将收到的 SSID/密码写入SsidManager::GetInstance().AddSsid(ssid, password)凭据由此持久化到 NVS属于esp-wifi-connect组件随后切换WifiManager启动 STA 模式见 main/boards/common/blufi.cpp。连接与上报WifiStation扫描并连接目标 AP连接状态成功/失败/连接中通过esp_blufi_send_wifi_conn_report回传给手机端连接成功后设备会自动断开 BLE 并释放 BluFi 资源之后每次重启都会直接使用已保存的凭据联网。值得一提的是配网成功后WifiBoard::OnNetworkEvent会调用Blufi::GetInstance().deinit()释放蓝牙资源见 main/boards/common/wifi_board.cc避免蓝牙协议栈与正常运行时的音频、网络功能抢占资源。使用步骤1. 配置并编译固件在项目根目录执行idf.py menuconfig在菜单中完成以下操作定位到WiFi Configuration Method菜单关闭Hotspot选项取消勾选开启ESP-BluFi选项勾选。保存退出后编译并烧录固件idf.py build idf.py -p /dev/ttyUSB0 flash monitor从源码看main/CMakeLists.txt 仅在CONFIG_USE_ESP_BLUFI_WIFI_PROVISIONING开启时才会把boards/common/blufi.cpp加入编译因此未开启该选项时BluFi 相关代码不会被打入固件。2. 触发配网首次启动设备没有已保存的 Wi‑Fi 时会自动进入配网模式TryWifiConnect检测到SsidManager中无记录后调用StartWifiConfigMode见 main/boards/common/wifi_board.cc。已连接状态下重新配网可通过长按按键等方式调用EnterWifiConfigMode()它会先停止当前 STA 连接再启动配网。3. 手机端操作打开 EspBlufi App或其他支持 BluFi 协议的客户端搜索并连接设备连接时可以选择是否启用加密设备端会按所选安全模式协商密钥按提示输入 Wi‑Fi SSID/密码并发送如需指定目标 AP可先请求设备返回扫描到的 Wi‑Fi 列表再选择。4. 观察结果成功BluFi 向手机返回连接成功状态ESP_BLUFI_STA_CONN_SUCCESS设备自动连接 Wi‑Fi同时触发 BLE 断开与 BluFi 资源释放失败BluFi 返回失败状态ESP_BLUFI_STA_CONN_FAIL手机可重新发送凭据或检查路由器信号与密码是否正确。源码级实现解析蓝牙与协议栈初始化Blufi::init()是配网的入口见 main/boards/common/blufi.cpp其调用链为若WifiManager尚未初始化或不在配网模式立即调用start_wifi_scan()预热热点缓存若检测到处于热点配网模式则直接报错返回这与文档「BluFi 与热点配网不能同时开启」的说明一致。_controller_init()初始化并启用 BLE 控制器_host_and_cb_init()注册 BluFi 回调事件、DH 协商、加解密、校验和再初始化协议栈Bluedroid 或 NimBLE 分支完成初始化后ESP_BLUFI_EVENT_INIT_FINISH事件中设置蓝牙设备名并开始广播。蓝牙设备名定义在 main/boards/common/blufi.cpp#define BLUFI_DEVICE_NAME Xiaozhi-Blufi注意由于 IDF 5.5.2 的 BluFi 接口发生变化IDF 5.5.2 版本编译后蓝牙名称为Xiaozhi-Blufi而 5.5.1 版本中为BLUFI_DEVICE手机端搜索设备时请注意区分。安全机制ffdhe3072 SHA-256 AES-CTRBluFi 协议的安全协商在_dh_negotiate_data_handler()中完成见 main/boards/common/blufi.cpp实现基于 PSA Crypto API使用RFC 7919 命名 DH 组 ffdhe30723072 位有限域 DH完成密钥协商设备侧校验手机端下发的 P素数长度为 384 字节、G 为 2然后生成自己的 DH 密钥对并返回公钥对协商出的共享密钥做SHA-256哈希得到 32 字节 PSK以 PSK 导入 AES 密钥用AES-CTR模式加解密配网数据帧加密/解密的 IV 分别由blufi_enc/blufi_dec域与共享密钥派生。这一实现对应 main/Kconfig.projbuild 中ESP-BluFi选项的 help 说明Use the PSA Crypto based BluFi security protocol adopted by ESP-IDF 6. The provisioning client must support ffdhe3072, SHA-256, and AES-CTR. 因此自定义 BluFi 客户端必须支持 ffdhe3072、SHA-256 与 AES-CTR否则无法与当前固件完成安全协商。Wi‑Fi 列表扫描与下发start_wifi_scan()会智能处理不同 Wi‑Fi 模式下的扫描见 main/boards/common/blufi.cpp若当前处于 AP 模式会临时切换为 STA 模式并重启 Wi‑Fi 驱动后再扫描若处于 STA/APSTA 模式则确保驱动启动后直接扫描扫描结果缓存在m_ap_records中手机端请求GET_WIFI_LIST时通过esp_blufi_send_wifi_list下发无缓存或扫描进行中时会先触发扫描、等待WIFI_EVENT_SCAN_DONE后再补发响应对应 main/boards/common/blufi.cpp。这一设计保证了配网过程中手机端始终能获取到最新的热点列表即使配网请求到达时驱动正处在模式切换状态也不会卡死。注意事项与常见问题两种配网方式互斥BluFi 配网不支持与热点配网同时开启。如果热点配网已经启动则默认使用热点配网。请在 menuconfig 中只保留一种配网方式关闭Hotspot开启ESP-BluFi。多次测试时清除旧凭据若反复测试配网建议清除或覆盖已存储的 SSIDNVS 中的wifi命名空间避免旧配置干扰新一次配网的结果。自定义客户端需遵循官方协议帧格式如果自研 BluFi 客户端必须严格按照官方协议帧格式封装数据并满足上述 ffdhe3072 SHA-256 AES-CTR 的安全要求协议细节可参考 Espressif 官方 BluFi 文档见 docs/blufi_zh.md 中链接的官方文档其中也提供了 EspBlufi App 的下载地址。版本差异IDF 5.5.2 与 5.5.1 的 BluFi 接口存在差异蓝牙广播名称分别为Xiaozhi-Blufi与BLUFI_DEVICE排查连接问题时优先确认固件实际编译所基于的 IDF 版本。配网后资源释放设备连接 Wi‑Fi 成功后WifiBoard会在NetworkEvent::Connected时调用Blufi::deinit()若配网失败且 BLE 已断开ESP_BLUFI_EVENT_BLE_DISCONNECT处理逻辑也会在m_provisioned为假时重新开始广播允许手机再次发起配网见 main/boards/common/blufi.cpp。总结BluFi 配网为小智固件提供了不依赖屏幕与按键的 BLE 配网能力设备侧只需在 menuconfig 中关闭 Hotspot、开启ESP-BluFi并重新编译烧录即可在首次启动时自动进入配网广播由手机 App 通过安全的 DHAES 通道下发 Wi‑Fi 凭据凭据经esp-wifi-connect的SsidManager持久化到 NVS 后自动联网。理解Blufi单例的初始化、事件处理与安全协商实现有助于开发者排查配网失败、自定义配网客户端或移植到新硬件。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考