激活与绑定
OTA 注册、验证码绑定与激活轮询。
文档中的域名示例请替换为实际环境；本地开发可在控制台文档页根据当前访问域名自动推断。
设备每次上电先调用 OTA 注册接口。返回中带 activation 字段，说明该设备尚未绑定账号，需要走激活流程。
Step 1 · OTA 开机注册
POST /api/ota/
参数
类型
// 响应（首次或未绑定时含 activation 字段）
{
"server_time": { "timestamp": 1746000000000, "timezone_offset": 480 },
"firmware": { "version": "1.3.0", "url": "https://…/1.3.0.bin" },
"websocket": { "url": "wss://open.ailancun.com/ws", "token": "eyJhbGci…" },
"mqtt": {
"endpoint": "tcp://open.ailancun.com:1883",
"client_id": "GID_test@@@AA_BB_CC_DD_EE_FF@@@<uuid>",
"username": "AA:BB:CC:DD:EE:FF",
"password": "eyJhbGci…"
},
"activation": { "code": "482931", "message": "智云\n482931" }
}websocket.token 是设备专属 JWT，有效期 1 年，必须持久化到 Flash/NVS，后续连接直接复用，无需每次重新激活。失效后再调 /api/ota/ 刷新。
Step 2 · 播报验证码 + 用户绑定
设备 TTS 播报或屏幕显示 6 位验证码（activation.code）。用户在 App / 小程序登录后，输入该验证码完成绑定：
POST /api/agent/device/bind
{ "authCode": "482931", "agentId": 1, "tenantId": 1, "userId": 100, "deviceName": "客厅音箱" }Step 3 · 激活状态轮询
设备播报后，每 3 秒轮询 POST /api/ota/activate（Header 带 Device-Id，body 空）：
| HTTP | 含义 | 设备行为 |
|---|---|---|
202 | 等待绑定中 | 3 秒后重试 |
200 | 已激活 | 进入握手，建立长连接 |
404 | 设备不存在 | 重新执行 Step 1 |
400 | 缺少 Device-Id | 检查 Header |
绑定成功后平台会通知 Gateway，设备无需重启即可在下一次连接进入对话状态。建议轮询 10 分钟未果则停止，引导用户重操作（重启设备会重新播报验证码）。