BluFi 第三方硬件接入 - AI 硬件智能体

开发者中心

AI 硬件智能体

集成开发

BluFi 第三方硬件接入

更新时间： 2026/07/07 15:12:20

本文面向第三方硬件/固件开发者，说明设备接入“网易小派 AI”小程序时需要满足的最小要求。

“网易小派 AI”小程序是网易云信为 AI 硬件（如拍学机、AI 电子宠物等）提供的标准移动端控制中枢。本文档定义了第三方硬件设备如何通过标准的 BluFi（Bluetooth Wi-Fi）协议，复用“网易小派 AI”小程序的配网能力。完成配网后，设备即可具备接入网易云信智能体平台（Agent Platform）、获取语音交互、大模型对话等能力。

接入流程图

sequenceDiagram
    participant App as 网易小派 AI 小程序
    participant Dev as BluFi设备

    App->>Dev: BLE连接
    App->>Dev: 打开Notify
    App->>Dev: SET_SEC_MODE
    App->>Dev: CUSTOM_DATA("ready")
    Dev-->>App: CUSTOM_DATA(设备信息JSON)

    alt 设备支持4G且用户选择4G
        App->>Dev: CUSTOM_DATA("start_4g")
        Dev-->>App: 进入4G配网流程
    else Wi-Fi配网
        App->>Dev: GET_WIFI_LIST
        Dev-->>App: WIFI_LIST
        App->>Dev: SET_OP_MODE(STATION)
        App->>Dev: WIFI_SSID
        App->>Dev: WIFI_PASSWORD
        App->>Dev: CONNECT_WIFI
        Dev-->>App: WIFI_CONNECTION_STATE(连接中)
        Dev-->>App: WIFI_CONNECTION_STATE(成功, staConnStatus=0x00)
    end

1. BLE 基础要求

1.1 广播要求

设备名需包含前缀 BLUFI_
如有多型号设备，建议统一使用 BLUFI_XXXX 命名

1.2 GATT 定义

Service UUID: 0000ffff-0000-1000-8000-00805f9b34fb
Write Characteristic UUID: 0000ff01-0000-1000-8000-00805f9b34fb
Notify Characteristic UUID: 0000ff02-0000-1000-8000-00805f9b34fb

建议特征值能力：

FF01 支持 Write
FF02 支持 Notify

2. 接入流程

2.1 设备连接完成后的首个交互

设备连接成功并打开通知后，小程序会按以下顺序发送：

SET_SEC_MODE
CUSTOM_DATA("ready")

设备在收到 ready 后，需要通过 CUSTOM_DATA 回传设备信息 JSON。

建议回传格式：

json{
  "id": "AABBCCDDEEFF",
  "name": "device-name",
  "version": "1.0.0",
  "type": "esp32-c2",
  "4g": false
}

字段说明：

字段名称	类型	说明
id	String	设备唯一标识
name	String	设备名称
version	String	固件版本
type	String	设备型号或板型
4g	Boolean	可选，若为 `true`，页面会允许用户选择 4G 配网

2.2 Wi-Fi 列表获取

小程序会发送 GET_WIFI_LIST 控制帧，设备收到后需扫描周围 Wi-Fi，并通过 WIFI_LIST 数据帧回传结果。

2.3 Wi-Fi 配网

小程序会按以下顺序发送：

SET_OP_MODE
WIFI_SSID
WIFI_PASSWORD
CONNECT_WIFI

设备收到后应开始联网，并通过 WIFI_CONNECTION_STATE 持续回传状态。

页面判定配网成功的条件是：

textstaConnStatus == 0x00

2.4 4G 模式

如果设备信息 JSON 中包含 "4g": true，用户选择 4G 配网后，小程序会发送：

textCUSTOM_DATA("start_4g")

设备可据此进入自身的 4G 配网流程。

3. 报文格式

3.1 通用帧结构

text+------------+------------+----------+----------+--------------+------------------+
| Type/SubTp | Frame Ctrl | Sequence | Data Len | Payload      | CRC16(可选, 2B)  |
+------------+------------+----------+----------+--------------+------------------+
| 1 byte     | 1 byte     | 1 byte   | 1 byte   | N bytes      | little-endian    |
+------------+------------+----------+----------+--------------+------------------+

3.2 Type/SubType 编码

第 1 字节编码方式：

texttype_subtype = (frameType & 0x03) | ((subType & 0x3F) << 2)

帧类型：

控制帧 CTRL = 0x00
数据帧 DATA = 0x01

3.3 Frame Ctrl 仅需关注的位

0x02: 开启 CRC16
0x10: 分片

3.4 Sequence

连接建立后，序列号从 0 开始
每发送一个完整 BluFi 帧，序列号自增 1
分片发送时，每个分片也单独占用一个序列号

4. 当前接入必须支持的命令

4.1 控制帧

子类型	值	用途
`SET_SEC_MODE`	`0x01`	设置校验模式
`SET_OP_MODE`	`0x02`	设置 Wi-Fi 模式
`CONNECT_WIFI`	`0x03`	开始连接 Wi-Fi
`GET_WIFI_LIST`	`0x09`	获取 Wi-Fi 列表

4.2 数据帧

子类型	值	方向	用途
`WIFI_SSID`	`0x02`	App -> Device	Wi-Fi SSID
`WIFI_PASSWORD`	`0x03`	App -> Device	Wi-Fi 密码
`WIFI_CONNECTION_STATE`	`0x0F`	Device -> App	联网状态
`WIFI_LIST`	`0x11`	Device -> App	Wi-Fi 列表
`CUSTOM_DATA`	`0x13`	双向	自定义命令和设备信息

5. 关键 Payload 格式

5.1 `SET_SEC_MODE`

Payload 为 1 字节，小程序实际会使用：

0x00: 不带 CRC
0x11: 控制帧和数据帧都带 CRC

5.2 `SET_OP_MODE`

Payload 为 1 字节，小程序当前使用：

0x01: STATION

5.3 `WIFI_SSID` / `WIFI_PASSWORD`

内容为 UTF-8 字节流
如长度超限，需要按分片规则发送

5.4 `CUSTOM_DATA`

当前小程序会主动发送：

textready
start_4g

设备侧建议处理方式：

收到 ready 后，回设备信息 JSON
收到 start_4g 后，进入 4G 配网逻辑

5.5 `WIFI_LIST`

Payload 格式如下：

text[ssid_len][rssi][ssid_bytes...][ssid_len][rssi][ssid_bytes...]...

说明：

ssid_len 表示 rssi + ssid_bytes 的总长度
ssid_bytes 实际长度为 ssid_len - 1
ssid_bytes 使用 UTF-8 编码

示例：

SSID: Home
SSID 字节长度: 4
ssid_len = 5

对应编码：

text05 C8 48 6F 6D 65

5.6 `WIFI_CONNECTION_STATE`

Payload 格式如下：

text[opMode][staConnStatus][softApConnNum][ssid_bytes...]

字段说明：

opMode: 当前 Wi-Fi 模式
staConnStatus: STA 联网状态
softApConnNum: SoftAP 已连接设备数
ssid_bytes: 可选，当前连接的 SSID

建议状态值：

状态名	值	含义
`CONNECTED_AND_GOT_IP`	`0x00`	已连接并拿到 IP
`DISCONNECTED`	`0x01`	未连接
`CONNECTING`	`0x02`	连接中
`CONNECTED`	`0x03`	已连接但未拿到 IP

页面最终仅以 staConnStatus = 0x00 判定成功。

6. 分片与 CRC

6.1 单帧长度

当前单个 BluFi 帧最大长度为 18 字节。

非分片最大 Payload：

不带 CRC 时：14 字节
带 CRC 时：12 字节

6.2 分片规则

当逻辑 payload 超出单帧上限时：

非最后一个分片：Frame Ctrl |= 0x10
非最后一个分片的 payload 前 2 字节写总长度，小端序
最后一个分片：不再带总长度，且 FRAG 位清零

格式如下：

text第 1 个分片 payload = [total_len_le_2B][chunk...]
中间分片 payload   = [total_len_le_2B][chunk...]
最后分片 payload   = [remaining_chunk...]

设备发送给小程序时，也需遵循同样规则。

6.3 CRC16

当启用 CRC 时：

算法：CRC16-CCITT
初值：0xFFFF
结束后按位取反
结果以小端序追加在帧尾

校验范围：

text[Sequence][Data Len][Payload]

7. 联调建议

建议按以下顺序联调：

先打通 BLE 连接与通知
验证 ready -> 设备信息 JSON
验证 GET_WIFI_LIST -> WIFI_LIST
验证 WIFI_SSID/WIFI_PASSWORD/CONNECT_WIFI -> WIFI_CONNECTION_STATE
最后验证长包分片和 CRC

8. 最小接入检查清单

第三方硬件接入前，建议至少确认以下项目：

广播名包含 BLUFI_
暴露 FFFF / FF01 / FF02
收到 ready 后能回设备信息 JSON
能返回 WIFI_LIST
能接收 SSID 和密码并执行联网
成功联网后能上报 staConnStatus = 0x00
长包可按分片规则收发
开启 CRC 时可正确校验和回包

9. 下一步指引

设备成功连接 Wi-Fi/4G 后，即可开始与网易云信服务端进行交互。

如需了解如何通过 WebSocket 建立语音/文本对话，请参考：与智能体对话
如需管理设备状态或绑定关系，请参考：设备管理 API 文档

此文档是否对你有帮助？

有帮助

去反馈

接入流程图
1. BLE 基础要求
1.1 广播要求
1.2 GATT 定义
2. 接入流程
2.1 设备连接完成后的首个交互
2.2 Wi-Fi 列表获取
2.3 Wi-Fi 配网
2.4 4G 模式
3. 报文格式
3.1 通用帧结构
3.2 Type/SubType 编码
3.3 Frame Ctrl 仅需关注的位
3.4 Sequence
4. 当前接入必须支持的命令
4.1 控制帧
4.2 数据帧
5. 关键 Payload 格式
5.1 SET_SEC_MODE
5.2 SET_OP_MODE
5.3 WIFI_SSID / WIFI_PASSWORD
5.4 CUSTOM_DATA
5.5 WIFI_LIST
5.6 WIFI_CONNECTION_STATE
6. 分片与 CRC
6.1 单帧长度
6.2 分片规则
6.3 CRC16
7. 联调建议
8. 最小接入检查清单
9. 下一步指引