本文说明如何在硬件端集成 BluFi 配网，实现设备与 网易小派AI 微信小程序的对接。

适用范围

当前仅 乐鑫 ESP32 支持，杰理和博通暂不支持。

方案概述

采用双分区、双进程方案，将 BluFi 配网功能独立为 blufi_app 子程序，与主程序分属不同 OTA 分区。原因：蓝牙 BluFi 协议栈会占用大量内存，在内存紧张的硬件上可能与主程序无法同时运行。因此示例代码将配网逻辑拆分到独立子进程，当业务需要与小程序连接时切到 blufi_app，配网完成后自动切回主程序。

text┌─────────────────────┐     BLE BluFi     ┌──────────────────┐
│   微信小程序          │ ◀──────────────▶ │   ESP32 设备       │
│   "网易小派AI"       │                   │                  │
│                     │                   │  ota_0: 主程序    │
│  发送 Wi-Fi 凭证     │                   │  ota_1: blufi_app │
└─────────────────────┘                   └──────────────────┘

使用此功能前，需先配置好 CSV 分区表。

blufi_app 架构

blufi_app (ota_1)                    main app (ota_0)
┌─────────────────────┐              ┌─────────────────────┐
│  blufi_app.cc       │              │  board.cc           │
│  ├─ NVS init        │   restart    │  ├─ blufi_hal_set() │
│  ├─ 90s timeout     │──────────▶   │  └─ 注册 HAL 回调   │
│  └─ dispatch        │              └─────────────────────┘
│                     │
│  blufi_provisioning │   HAL callbacks
│  ├─ BLE BluFi       │◀──────────── display_device_info
│  └─ WiFi AP         │              on_provision_start/success/fail
└─────────────────────┘

集成步骤

1. 编译 blufi_app

工程仓库已提供编译好的 bin 文件（IDF v5.5.2），位于 esp32/nertc_demo/third_party/blufi_app/bin/blufi_app.bin，可直接用于烧录，跳过编译步骤。

如需自行编译：

bashcd third_party/blufi_app
idf.py set-target esp32s3
idf.py build

编译产物位于 third_party/blufi_app/build/blufi_app.bin。

2. 烧录 blufi_app

bashcd esp32/nertc_demo
python3 config.py -p /dev/cu.usbmodemXXX --build --flash --blufi

0x520000 须与分区表中 blufi（ota_1）分区的偏移地址一致。

3. 进入配网模式

主工程通过设置 NVS 并重启，切换到 blufi_app 分区：

cppconst esp_partition_t *blufi = esp_partition_find_first(
    ESP_PARTITION_TYPE_APP, ESP_PARTITION_SUBTYPE_APP_OTA_1, NULL);
esp_ota_set_boot_partition(blufi);

Settings settings("board", true);
settings.SetInt("app", 1);  // 1=配网模式

esp_restart();

重启后设备进入配网模式，小程序即可通过 BLE 扫描并连接设备。

分区表

blufi_app 必须与主工程使用相同的分区表。默认 16MB 分区表：

分区	类型	偏移	大小	说明
ota_0	app	0x30000	8MB	主程序
blufi	app (ota_1)	0x830000	2.5MB	配网工程

NVS 配置项

blufi_app 从 board 命名空间读取以下配置（由主工程写入）：

Key	类型	说明
app	int	1=配网模式，2=OTA 模式
name	string	设备名（空则根据 MAC 自动生成）
id	string	设备 ID
type	string	设备类型
version	string	固件版本
appkey	string	应用密钥

配网流程

1. 主程序设置 NVS（app=1）并重启
2. blufi_app 启动，开启 BLE BluFi 广播，启动 90 秒超时定时器
3. 小程序通过 BLE 发现设备，发送 Wi-Fi SSID 和密码
4. 设备连接 Wi-Fi 成功后，自动切换 boot 分区并重启回主程序
5. 若 90 秒内无操作，超时自动重启回主程序