90 lines
4.3 KiB
Markdown
90 lines
4.3 KiB
Markdown
|
# 蓝牙配网与账号绑定：简版说明
|
||
|
|
|
||
|
|
通信方式：手机/电脑与设备之间使用 **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 已连上、平台已确认绑定、设备已保存结果，不能在仅收到数据时就返回成功。
|
||
|
|
|
||
|
|
如果蓝牙断开，页面通过后台查询这台设备是否已绑定；断开本身不代表绑定失败。
|