# 蓝牙配网与账号绑定：简版说明

通信方式：手机/电脑与设备之间使用 **BLE GATT（低功耗蓝牙）**。

本文只说明发现设备、设备端准备和发送配置三个部分，供前端、固件与后台约定功能。报文为拟定的业务数据格式，不代表现有固件已经支持。

## 1. 我怎么发现设备

**用户操作：** 登录平台，长按设备配网键，再点击页面上的“添加设备”。

**设备动作：** 进入配网模式，开启蓝牙广播，名称显示为 `EchoEar-000001`。末尾编号与设备外壳编号一致，方便用户认出自己的设备。

**页面动作：** 调用蓝牙发现功能，用约定的“配网服务 UUID”筛选你们的设备。这个 UUID 是一个固定的服务标识，由前端和固件使用同一个值。浏览器弹出设备选择框，用户选择编号对应的设备。

连接并完成设备身份校验后，页面读取设备信息，例如：

```json
{
  "device_id": "KP01-000000000001",
  "model": "ECHOEAR-S3"
}
```

页面显示“设备型号：ECHOEAR-S3，编号：000001”。型号和编号由设备固件提供；蓝牙名称只用于辅助选择。

网页需要在支持 Web Bluetooth 的浏览器中通过 HTTPS 打开，发现设备由用户点击触发。

## 2. 设备应该做什么

设备固件需要实现以下功能：

| 功能 | 设备要做的事 |
|---|---|
| 进入配网 | 长按配网键后开启蓝牙广播，保持约 5 分钟 |
| 提供身份 | 保存并返回自己的设备编号和型号 |
| 接收配置 | 提供 BLE 配置写入入口，收到写入后交给固件接收函数处理 |
| 连接网络 | 解析收到的 Wi-Fi 名称和密码，调用 Wi-Fi 驱动连接路由器 |
| 绑定账号 | 联网后携带自身认证凭据和绑定令牌请求平台，等待绑定结果 |
| 返回进度 | 让页面能够查询“已收到、连接 Wi-Fi、绑定中、成功或失败” |

前端与固件统一约定“读取设备信息、写入配置、查询状态”这三个操作。蓝牙收发模块负责加密和分包，业务代码只处理下面的完整数据。

## 3. 我怎么给设备发送 Wi-Fi 和绑定信息

**第一步：页面申请绑定令牌。**

用户已经登录，页面把选中的 device_id 提交给平台后台。后台根据当前登录账号和目标设备生成一个 bind_token。它表示“允许这台设备绑定到当前账号”，有效期约 5 分钟，只能完成一次绑定。

**第二步：用户输入 Wi-Fi，页面通过蓝牙发送。**

页面填写 Wi-Fi 名称和密码，连同后台返回的令牌一起发送：

```json
{
  "wifi_ssid": "MyHome",
  "wifi_password": "example-password",
  "bind_token": "后台生成的一次性绑定令牌"
}
```

这就是设备需要接收的三项核心信息。平台账号由 bind_token 对应，用户不用再次输入平台账号和密码。

上面的 JSON 展示业务内容；实际发送时先通过通信模块加密、分包，再写入设备的 BLE 配置入口。设备的接收函数重组、解密后解析这三个字段。双方必须使用相同的字段名和编码，JSON 使用 UTF-8。

**第三步：设备连接 Wi-Fi，再向平台提交绑定。**

设备检查配置并执行本次操作的实体确认，然后使用 wifi_ssid、wifi_password 连接路由器。当前 EchoEar 使用 2.4GHz Wi-Fi。

联网后，设备通过已有的设备认证方式向平台发送自己的身份与 bind_token。后台验证设备身份和令牌，查到令牌对应的账号，保存“账号—设备”的绑定关系。Wi-Fi 密码只给设备，不提交到平台后台。

设备已有其他有效归属时，后台拒绝新绑定；重复提交同一次已成功的绑定，返回原结果。

**第四步：页面读取结果。**

页面每隔约 2 秒查询一次设备状态。成功示例：

```json
{"status":"success"}
```

失败示例：

```json
{"status":"failed","message":"Wi-Fi连接失败，请检查网络名称和密码"}
```

status 约定为 received、wifi_connecting、binding、success、failed。message 仅在失败时返回可展示的原因，不回传密码或令牌。success 必须表示 Wi-Fi 已连上、平台已确认绑定、设备已保存结果，不能在仅收到数据时就返回成功。

如果蓝牙断开，页面通过后台查询这台设备是否已绑定；断开本身不代表绑定失败。