设备接入总览
三阶段接入流程与 WebSocket / MQTT+UDP 协议选择。
本章面向 ESP32 / 安卓 / iOS / 小程序 / H5 / Web 等有自主研发能力的设备端、应用端团队，描述设备如何接入 OpenCloud 语音平台并完成实时对话。设备侧成熟方案（包括嵌入式参考固件 opencloud_esp32）已经过大量产品验证，按本文对接即可。
三阶段流程
设备上电
│ ── Stage 1：OTA 开机注册 ──
▼ POST /api/ota/ → 返回 WS/MQTT 地址 + JWT + (首次)激活验证码 + 固件信息
│
├─ [未绑定] 播报验证码 → 用户在 App 输入绑定 → 轮询 /api/ota/activate 至 200
└─ [已绑定] 直接进入下一步
│ ── Stage 2：建立长连接 + 握手 ──
▼ WebSocket(wss://…/ws?token=) 或 MQTT(hello)，携带设备信息（自动上报）
│
▼ ── Stage 3：正常语音对话 / 指令下发 / 心跳 ──两种传输协议
平台同时支持 WebSocket 与 MQTT+UDP，设备按自身条件选择其一。OTA 响应里返回哪个就用哪个；两个都返回时优先 MQTT+UDP（音频延迟更低）。
| 协议 | 控制通道 | 音频通道 | 适用场景 |
|---|---|---|---|
| WebSocket | WS 文本帧 (JSON) | WS 二进制帧 (Opus) | 防火墙友好、实现简单，网页/小程序/App 首选 |
| MQTT + UDP | MQTT (JSON) | UDP (AES-CTR 加密 Opus) | 音频延迟更低，资源充足的嵌入式设备首选 |
音频统一使用 Opus 编码、60ms 帧长、单声道。上行采样率 16kHz，下行 24kHz。UDP 音频包带递增 sequence 序号，设备端据此做丢包补偿（Opus PLC），因此偶发 UDP 丢包不会造成语音中断。