设备接入

协议:WebSocket JSON 控制信令(v1.2,17 条)+ 二进制音频帧 | 鉴权:一机一码 | SDK:C99 与 Python 双实现

接入总览

端点wss://openagent-os.com/v1/device/ws
鉴权连接即发 auth.hello{device_id, token};token 在控制台「设备」签发(24 字节随机,服务端只存哈希,可吊销)
音频二进制帧:4 字节头 type(0x01 上行/0x02 下行)+flags+seq(大端,双向独立、0xFFFF 回绕);payload ≤2048B;TTS 下行 Opus/24kHz/单声道;丢帧不重传
会话session.start/state/interrupt/error;打断 = session.interrupt → 云端按句边界停止下发 tts.audio 并回 tts.stop{reason:interrupted}

三步接入

① 控制台签发一机一码

控制台「设备」→ 签发 → 保存 device_id + token(仅显示一次)→ 绑定智能体(决定这台设备的提示词/知识库/模型渠道)。

② 选择 SDK

平台方案
ESP32-S3boards/esp32s3-reference(ESP-IDF 5.x:WS 客户端、I2S 录放、Opus 编解码、按键唤醒/打断、OTA 上报);SDK 以组件形式引用 device-sdk-c/include
树莓派 / Jetson / LinuxPython SDK device-sdk-python(与 C 同契约独立实现,含 Mock 网关与一致性测试)
其他 MCU按 protocol/v1/device-protocol.schema.json 自行实现(C 头文件 oa_protocol.h 提供线协议常量与帧封包)

③ 跑通第一句话

from openagent_sdk import OAClient

client = OAClient(url="wss://openagent-os.com/v1/device/ws",
                  device_id="dev-…", token="…")
client.on("asr.final", lambda e: print("识别:", e["text"]))
client.on("tts.audio", lambda e: play(opus_decode(e["payload_b64"])))

client.connect()
client.start_session()
client.send_text("你好")          # 文本通道快速验证(音频走 send_audio 帧)

离线开发:python -m openagent_sdk.testing 启动 Mock 网关 (schema 校验 + 模拟 VAD/ASR/TTS/打断),无需云端即可开发调试。

运行时行为(云端负责)

协议契约

完整 Schema:protocol/v1/device-protocol.schema.json(draft 2020-12, 三副本一致性由 tools/audit_scan.py 保障)。版本纪律:v1.x 只允许追加可选字段, 破坏性变更升 v2 双轨。