小智固件xiaozhi-esp32BluFi BLE 配网实战指南启用 ESP-BluFi 并集成 esp-wifi-connect【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本文是一份面向小智XiaoZhiESP32 固件的 BluFi 配网实战指南核心讲解如何在idf.py menuconfig中启用ESP-BluFiCONFIG_USE_ESP_BLUFI_WIFI_PROVISIONING并结合项目内置的esp-wifi-connect组件完成 Wi‑Fi 凭据下发、存储与自动连接。读完本文你将掌握 BluFi 配网的完整工作流程、手机端 EspBlufi App 操作步骤、与热点Hotspot配网的取舍以及源码层面的实现原理安全协商、事件处理、Wi‑Fi 扫描列表下发可直接在自己的开发板上复现整套配网链路。BluFi 是什么基于 BLE 的 Wi‑Fi 配网协议BluFi 是 Espressif 提出的一种基于 BLE低功耗蓝牙的 Wi‑Fi 配网协议手机通过 BLE 链路与设备建立连接把目标路由器的 SSID / 密码安全地发送给设备设备收到凭据后切换为 STA 模式去连接目标 Wi‑Fi并把连接状态实时回传给手机。与热点配网Hotspot相比BluFi 不需要设备开启热点、手机切换网络、再访问 Web 页面配网体验更接近蓝牙一键配网。在小智固件中BluFi 配网并非独立实现而是与项目内置的esp-wifi-connect组件配合使用esp-wifi-connect负责 Wi‑Fi 连接与凭据的持久化存储NVSBluFi 只负责接收凭据 触发连接 回传状态。相关官方协议细节可参考 Espressif 的 BluFi 文档。前置条件在开始配置前请确认以下条件全部满足硬件支持 BLE需要支持 BLE 的芯片与固件配置项目中的 ESP32-S3、ESP32-C3 等带 BLE 的芯片均可Wi‑Fi 配网菜单仅在有 BLE 能力的平台上可用。在 menuconfig 中启用 ESP-BluFi进入WiFi Configuration Method - ESP-BluFi对应配置宏为CONFIG_USE_ESP_BLUFI_WIFI_PROVISIONINGy。关闭 Hotspot 配网如果想使用 BluFi必须在同一菜单下关闭Hotspot选项CONFIG_USE_HOTSPOT_WIFI_PROVISIONING否则默认使用 Hotspot 配网模式BluFi 不会生效。保持默认的 NVS 与事件循环初始化项目的app_main已统一处理 NVS flash 初始化与事件循环不需要额外修改。BLE 协议栈二选一CONFIG_BT_BLUEDROID_ENABLEDBluedroid与CONFIG_BT_NIMBLE_ENABLEDNimBLE两个宏必须二选一不能同时启用二者互斥。从源码看小智固件同时支持 Bluedroid 与 NimBLE 两种 BLE 主机协议栈blufi.cpp 中分别用#ifdef CONFIG_BT_BLUEDROID_ENABLED与#ifdef CONFIG_BT_NIMBLE_ENABLED隔离了两套_host_init()/_host_deinit()/_host_and_cb_init()实现BluFi 协议回调esp_blufi_register_callbacks的注册逻辑则两者共用。配网工作流程小智固件中 BluFi 配网的完整流程如下手机连接设备手机端通过官方 EspBlufi App或自研 BluFi 客户端搜索并连接设备然后发送目标 Wi‑Fi 的 SSID / 密码手机端也可以通过 BluFi 协议主动获取设备扫描到的 Wi‑Fi 列表用于选择网络。凭据写入 SsidManager设备侧在ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP事件中把收到的 SSID / 密码写入SsidManager凭据由esp-wifi-connect组件持久化到 NVS。启动 WifiStation 扫描并连接设备随后启动WifiStation去扫描并连接目标网络连接过程与结果状态通过 BluFi 协议返回给手机。结果反馈配网成功后设备自动连接新 Wi‑Fi失败则返回失败状态可重新发送凭据或检查路由器。使用步骤端到端实操第一步配置并编译固件在项目根目录打开 menuconfigidf.py menuconfig进入WiFi Configuration Method菜单勾选ESP-BluFi同时取消勾选Hotspot。配置项在源码中的定义位于 Kconfig.projbuildmenu WiFi Configuration Method config USE_HOTSPOT_WIFI_PROVISIONING bool Hotspot default y config USE_ESP_BLUFI_WIFI_PROVISIONING bool ESP-BluFi select BT_ENABLED select BT_BLE_42_FEATURES_SUPPORTED select BT_BLE_BLUFI_ENABLE 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. endmenu从 Kconfig 定义可以看到勾选ESP-BluFi会自动连带启用BT_ENABLED、BT_BLE_42_FEATURES_SUPPORTED和BT_BLE_BLUFI_ENABLE无需手动逐个打开蓝牙相关选项。另外注意 help 文本中的关键信息本固件使用的是基于 PSA Crypto 的 BluFi 安全协议ESP-IDF 6 引入配网客户端必须支持ffdhe3072RFC 7919 命名 DH 组、SHA-256 与 AES-CTR三种算法否则安全协商会失败。编译并烧录固件idf.py build idf.py -p /dev/ttyUSB0 flash monitor第二步触发配网设备首次启动且 NVS 中没有已保存的 Wi‑Fi 凭据时会自动进入配网模式。这个逻辑在 wifi_board.cc 的TryWifiConnect()中SsidManager::GetInstance().GetSsidList()为空时调用StartWifiConfigMode()而当CONFIG_USE_ESP_BLUFI_WIFI_PROVISIONING被定义时StartWifiConfigMode()会调用Blufi::GetInstance().init()启动 BluFi 协议见 wifi_board.cc。第三步手机端操作打开 EspBlufi App官方文档提供下载地址或使用其他兼容 BluFi 协议的客户端。扫描并连接设备。设备广播的蓝牙名称取决于 ESP-IDF 版本见下文注意事项。连接后可以选择是否启用加密加密走上述 PSA Crypto 安全协商流程。按提示输入 Wi‑Fi SSID / 密码并发送也可以先在 App 中请求设备扫描到的 Wi‑Fi 列表从中选择目标网络。第四步观察结果成功BluFi 上报连接成功设备自动连接 Wi‑Fi并进入正常使用流程语音助手、MQTT / WebSocket 连接等。失败BluFi 返回失败状态如ESP_BLUFI_STA_CONN_FAIL此时可重新发送凭据或检查路由器信号与密码是否正确。源码级深入BluFi 模块是如何工作的Blufi 类结构BluFi 的完整实现位于 blufi.h 与 blufi.cpp以单例Blufi::GetInstance()形式提供对外暴露三个核心接口esp_err_t init()初始化蓝牙控制器、BLE 主机与 BluFi profile是 BluFi 的启动入口在进入配网模式时由 wifi_board.cc 调用esp_err_t deinit()反初始化 BluFi 与蓝牙协议栈释放资源在 Wi‑Fi 连接成功后由 wifi_board.cc 调用确保配网资源被及时回收bool start_wifi_scan()启动 Wi‑Fi 扫描为手机端获取 Wi‑Fi 列表提供数据。init()内部依次执行先调用start_wifi_scan()预扫描 Wi‑Fi这样用户一连接就能拿到列表再初始化蓝牙控制器_controller_init()配置BT_CONTROLLER_INIT_CONFIG_DEFAULT()并以ESP_BT_MODE_BLE模式使能最后通过_host_and_cb_init()注册 BluFi 回调并初始化 BLE 主机协议栈Bluedroid 或 NimBLE 二选一。事件驱动的状态机BluFi 协议通过事件回调驱动核心处理函数是_handle_event()blufi.cpp其esp_blufi_cb_event_t事件与行为的对应关系如下BluFi 事件设备行为ESP_BLUFI_EVENT_INIT_FINISH设置 BLE 设备名并启动广播esp_blufi_adv_start()开始可被发现ESP_BLUFI_EVENT_BLE_CONNECT手机已连接停止广播初始化安全上下文_security_init()ESP_BLUFI_EVENT_BLE_DISCONNECT断开连接若尚未配网成功则重新广播若已配网成功则停止广播并异步deinit()释放资源ESP_BLUFI_EVENT_RECV_STA_SSID/RECV_STA_PASSWD/RECV_STA_BSSID依次接收手机下发的 SSID、密码与可选 BSSID暂存到m_sta_configESP_BLUFI_EVENT_REQ_CONNECT_TO_AP将凭据写入SsidManager停止热点/STA启动WifiStation连接并用独立任务轮询连接结果超时 10 秒ESP_BLUFI_EVENT_GET_WIFI_STATUS查询当前 Wi‑Fi 状态并回传成功 / 连接中 / 失败ESP_BLUFI_EVENT_GET_WIFI_LIST下发设备扫描到的 Wi‑Fi 列表SSID RSSIESP_BLUFI_EVENT_SET_WIFI_OPMODE切换 Wi‑Fi 模式STA / AP / 关闭ESP_BLUFI_EVENT_REQ_DISCONNECT_FROM_AP断开当前 STA 连接其中ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP是与esp-wifi-connect组件衔接的关键点blufi.cpp收到事件后SsidManager::GetInstance().AddSsid(ssid, password)将凭据持久化到 NVSwifi命名空间随后新建一个blufi_wifi_conn任务轮询WifiManager::IsConnected()超时 10 秒成功时通过esp_blufi_send_wifi_conn_report(...)上报ESP_BLUFI_STA_CONN_SUCCESS失败则上报ESP_BLUFI_STA_CONN_FAIL。配网成功后设备会自动连接新 Wi‑Fi当WifiBoard收到NetworkEvent::Connected时会调用Blufi::GetInstance().deinit()释放蓝牙资源wifi_board.cc配网任务到此彻底结束。安全协商PSA Crypto 实现小智固件在 ESP-IDF 6 下采用了 PSA Crypto 重写的 BluFi 安全层_security_init()/_security_deinit()/_dh_negotiate_data_handler()见 blufi.cpp。核心流程DH 协商解析手机发来的 DH 参数包P、G、对端公钥要求使用 3072 位 ffdhe3072 命名组PSA_DH_FAMILY_RFC7919P 长度 384 字节、G2这与 Kconfig help 中客户端必须支持 ffdhe3072的要求一一对应密钥派生psa_raw_key_agreement计算共享密钥再用 SHA-256 从共享密钥与blufi_enc/blufi_dec域串派生加密/解密密钥与 IV数据加解密采用 AES-CTR 模式PSA_ALG_CTR通过_aes_encrypt()/_aes_decrypt()对协议数据加解密完整性校验_crc_checksum()使用esp_crc16_be计算 CRC16。代码还对 DH 参数长度上限 1024 字节、包长度、字段解析做了严格校验任何异常都会通过btc_blufi_report_error()上报对应错误码。如果你使用自研 BluFi 客户端务必确保安全算法与 ESP-IDF 6 的 PSA Crypto 实现匹配。Wi‑Fi 列表扫描与下发ESP_BLUFI_EVENT_GET_WIFI_LIST的处理包含三种场景blufi.cpp扫描已在飞行中设置m_send_list_after_scan标志等WIFI_EVENT_SCAN_DONE后再回复避免阻塞 BluFi 任务已有扫描缓存立即调用_send_wifi_list()下发同时触发一次异步刷新扫描保持列表新鲜无缓存启动一次真实扫描扫描完成后再回复若扫描启动失败则立即回发ESP_BLUFI_WIFI_SCAN_FAIL错误帧避免 App 端一直等待超时。扫描结果以esp_blufi_ap_record_tSSID RSSI形式通过esp_blufi_send_wifi_list()下发给手机。start_wifi_scan()还会智能处理当前 Wi‑Fi 模式若设备处于 AP 模式会临时切换到 STA 模式完成扫描后恢复尽量不影响正常 Wi‑Fi 操作。注意事项与常见问题BluFi 与热点配网互斥两者不能同时开启。如果热点配网已经启用CONFIG_USE_HOTSPOT_WIFI_PROVISIONINGy设备会默认走热点配网。请在 menuconfig 的WiFi Configuration Method菜单中只保留一种配网方式。从 blufi.cpp 可以看到若检测到WifiManager已处于热点配置模式Blufi::init()会直接返回错误并打印 Blufi and WiFi hotspot network configuration cannot be used simultaneously.。重复测试请清理旧凭据多次测试时建议清除或覆盖 NVS 中存储的 SSIDwifi命名空间避免旧配置干扰下一次配网。例如可以在 menuconfig 中关闭再打开相关选项触发重新配网或使用idf.py erase-flash擦除整片 flash注意会同时清除设备其他设置。自定义 BluFi 客户端如果自己编写 BluFi 客户端必须遵循官方协议帧格式帧头、类型、长度、数据、校验和安全部分需兼容 ffdhe3072 SHA-256 AES-CTR可参考 Espressif 官方协议文档。EspBlufi App 下载官方文档中已提供 EspBlufi App 的下载地址建议优先使用官方客户端以保证协议兼容性。蓝牙名称因 IDF 版本而异由于 IDF 5.5.2 的 BluFi 接口发生变化使用ESP-IDF 5.5.2编译的固件广播的蓝牙名称为Xiaozhi-Blufi使用ESP-IDF 5.5.1编译的固件广播的蓝牙名称为BLUFI_DEVICE。从 blufi.cpp 的#define BLUFI_DEVICE_NAME Xiaozhi-Blufi可见新版源码已将默认名称改为Xiaozhi-Blufi手机 App 搜索设备时如遇名称不匹配请对照你所用的 IDF 版本。BLE 协议栈二选一CONFIG_BT_BLUEDROID_ENABLED与CONFIG_BT_NIMBLE_ENABLED必须恰好启用一个。Bluedroid 与 NimBLE 在小智固件中均得到支持但二者互斥编译前请确认 sdkconfig 中没有同时开启。小结BluFi 配网是小智固件提供的两种 Wi‑Fi 配网方式之一另一种是热点配网适合追求打开 App、蓝牙直连、发送凭据这一顺滑体验的用户。启用它只需在 menuconfig 中勾选ESP-BluFi并关闭 Hotspot其余工作由Blufi单例类与esp-wifi-connect组件自动完成。理解 blufi.cpp 中的事件处理与安全协商逻辑也有助于你排查配网失败、自定义客户端或适配新硬件时的各类问题。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考