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. 设备名称

由于 IDF 版本差异，蓝牙名称有所不同：

• IDF 5.5.2：蓝牙名称为 Xiaozhi-Blufi
• IDF 5.5.1：蓝牙名称为 BLUFI_DEVICE

工作流程

  flowchart LR
    A[手机 BluFi 客户端] --> B[连接设备 BLE]
    B --> C[发送 Wi-Fi 凭据]
    C --> D[设备写入 NVS]
    D --> E[启动 Wi-Fi 连接]
    E --> F{连接成功?}
    F -->|是| G[配网完成]
    F -->|否| H[返回失败状态]

1. 手机端通过 BluFi（如官方 EspBlufi App）连接设备
2. 设备侧在 ESP_BLUFI_EVENT_REQ_CONNECT_TO_AP 中将凭据写入 SsidManager
3. 启动 WifiStation 扫描并连接，状态通过 BluFi 返回
4. 配网成功后设备会自动连接新 Wi-Fi

使用步骤

1. 编译固件

配置并编译固件：

idf.py menuconfig  # 启用 Esp Blufi
idf.py build
idf.py flash

2. 触发配网

设备首次启动且没有已保存的 Wi-Fi 时会自动进入配网模式。

3. 手机端操作

1. 打开 EspBlufi App（或其他 BluFi 客户端）
2. 搜索并连接设备（可选择是否加密）
3. 按提示输入 Wi-Fi SSID/密码并发送

4. 观察结果

• 成功：BluFi 报告连接成功，设备自动连接 Wi-Fi
• 失败：BluFi 返回失败状态，可重新发送或检查路由器

注意事项

• 互斥性：BluFi 配网不支持与热点配网同时开启。请确保 menuconfig 中只保留一种配网方式
• 存储清除：多次测试时，建议清除 NVS 中 wifi 命名空间的旧配置，避免干扰
• 协议规范：使用自定义 BluFi 客户端需遵循官方协议帧格式

相关链接

• Espressif BluFi 官方文档
• EspBlufi APP 下载
• esp-wifi-connect 组件