xiaozhi-esp32 如何启用 BluFi 配网并用 EspBlufi App 完成首次 WiFi 配网【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32第一次使用 xiaozhi-esp32 设备时固件里没有保存任何 WiFi 凭据需要在手机端把 SSID 和密码传给设备。xiaozhi-esp32 除了默认的热点Hotspot配网外还支持基于 BLE 的 BluFi 配网由项目内置的esp-wifi-connect组件负责连接 WiFi 并把凭据持久化到 NVS。完成本文操作后设备通过 EspBlufi App 接收 WiFi 凭据自动连接目标路由器下次开机直接连网无需重复配网。官方协议细节见 Espressif 的 BluFi 文档下载地址等也在该官方文档中列出项目内的说明文档是 docs/blufi_zh.md。前置条件确认芯片与蓝牙配置满足要求按 docs/blufi_zh.md 的说明启用 BluFi 需要满足以下条件芯片与固件配置支持 BLECONFIG_BT_BLUEDROID_ENABLED和CONFIG_BT_NIMBLE_ENABLED两个宏二选一不能同时启用NVS 与事件循环的初始化由项目的app_main处理保持默认即可不需要额外配置。第一步在 menuconfig 中启用 ESP-BluFi 并关闭 Hotspot运行idf.py menuconfig进入WiFi Configuration Method菜单定义在 main/Kconfig.projbuild勾选ESP-BluFi对应宏CONFIG_USE_ESP_BLUFI_WIFI_PROVISIONINGy取消同一菜单下的Hotspot选项。Hotspot默认是勾选的default y如果不同时关闭设备会默认使用 Hotspot 配网而不是 BluFidocs/blufi_zh.md 明确要求请在 menuconfig 中只保留一种配网方式。Kconfig 中ESP-BluFi选项会自动select BT_ENABLED、BT_BLE_42_FEATURES_SUPPORTED和BT_BLE_BLUFI_ENABLE不需要再单独勾选蓝牙选项。该选项的 help 文本同时说明了配网客户端的能力要求必须支持 ffdhe3072、SHA-256 和 AES-CTRPSA Crypto 安全协议即 ESP-IDF 6 采用的 BluFi 安全协议。第二步编译并烧录固件按 docs/blufi_zh.md 的步骤在 menuconfig 开启ESP-BluFi。编译并烧录固件。 沿用它已经引用的idf.py流程idf.py build idf.py flash第三步等待设备进入配网状态设备首次启动且没有已保存的 WiFi 时会自动进入配网不需要手动触发。从 main/boards/common/wifi_board.cc 可以看到这条路径TryWifiConnect()检查SsidManager里没有 SSID 时调用StartWifiConfigMode()在该函数中当CONFIG_USE_ESP_BLUFI_WIFI_PROVISIONING被定义时执行Blufi::GetInstance().init()初始化 BluFi 并开始 BLE 广播。初始化完成后设备开始广播蓝牙名称与所用 IDF 版本有关来源docs/blufi_zh.md编译所用 IDF 版本设备蓝牙名称5.5.2BluFi 接口有变化Xiaozhi-Blufi5.5.1BLUFI_DEVICE代码中定义的名称常量在 main/boards/common/blufi.cpp#define BLUFI_DEVICE_NAME Xiaozhi-Blufi。串口日志中若出现BLUFI init finish和 BLE 广播启动的记录说明设备已准备好被搜索。第四步用 EspBlufi App 连接设备并发送 WiFi 凭据手机端操作按 docs/blufi_zh.md 的说明打开 EspBlufi App官方 Espressif BluFi 文档中提供该 App 的下载地址搜索并连接上一步广播的设备可以选择是否启用加密App 可以通过 BluFi 协议获取设备端扫描到的 WiFi 列表据此选择目标路由器按提示输入 WiFi SSID/密码并发送。设备侧的处理在 main/boards/common/blufi.cpp收到 SSID 和密码帧后在ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP事件里把凭据写入SsidManageresp-wifi-connect组件存入 NVS项目通过 main/idf_component.yml 固定引用78/esp-wifi-connect: ~3.3.1随后启动WifiStation扫描并连接进度通过 BluFi 返回给手机端。第五步验证配网结果结果判断方式来源docs/blufi_zh.md成功BluFi 报告连接成功设备自动连接新 WiFi。从代码看连接成功后设备会通过esp_blufi_send_wifi_conn_report上报ESP_BLUFI_STA_CONN_SUCCESS随后断开 BLE 连接WiFi 连上后wifi_board.cc还会调用Blufi::deinit()释放 BluFi 资源。失败BluFi 返回失败状态可重新发送凭据或检查路由器。配合串口日志可以更精确地判断卡在哪一步main/boards/common/blufi.cpp 中的关键日志BLUFI_CLASS标签包括BLUFI ble connectApp 已通过 BLE 连上设备Recv STA SSID: ssid/Recv STA PASSWORD凭据帧已收到BLUFI request wifi connect to AP via esp-wifi-connect开始实际连接connected to WiFi或Failed to connect to WiFi via esp-wifi-connect最终结果。注意连接有一个等待窗口源码中等待 WiFi 连接的超时kConnectTimeoutMs为 10000ms超过该时长仍未连上就会上报ESP_BLUFI_STA_CONN_FAIL。所以路由器信号差、密码错误时失败回报会在等待窗口结束后给出。注意事项与重复测试与热点配网互斥BluFi 配网不支持与热点配网同时开启如果热点配网已经启动默认使用热点配网。代码中也有对应保护Blufi::init()发现已处于配置模式AP 已启动时会记录Blufi and WiFi hotspot network configuration cannot be used simultaneously.并直接返回ESP_FAIL。重复测试要清旧凭据多次测试建议清除或覆盖存储的 SSIDwifi命名空间避免旧配置干扰。若不清除重启后TryWifiConnect()发现SsidManager里有 SSID会直接尝试连接旧网络而不进入配网。自研客户端如果不用 EspBlufi App 而是写自己的 BluFi 客户端需遵循官方协议帧格式见 docs/blufi_zh.md 引用的官方文档链接。配网成功后凭据已存入 NVS设备重启会直接用保存的 SSID 连接不再进入配网模式需要重新配网时按上一条清除wifi命名空间中的存储内容即可。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考