Codex Local
bf1233d5df
ci / verify (push) Canceled after 0s
Add customer and operator login, BLE provisioning, device fleet controls, call memory, memoir generation, and refreshed family and maintenance portals. Include API contracts, migrations, firmware sources, tests, assets, and deployment documentation.
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 已连上、平台已确认绑定、设备已保存结果，不能在仅收到数据时就返回成功。
|
|
|
|
如果蓝牙断开，页面通过后台查询这台设备是否已绑定；断开本身不代表绑定失败。
|