protocol-docs/docs/device_api.md

AI球设备控制协议

本文档定义 PC 上位机、同步播放器和测试工具控制 AI球设备的初版 API 约定。

1. 设计原则

• 命令结构简单，便于串口、USB、BLE 或网络传输适配。
• 每条请求应包含 request_id，便于上位机匹配响应。
• 设备响应应包含 ok、error_code 和必要数据。
• 不在协议中传输 token、密码或 API key。

2. 通用消息格式

请求

{
  "request_id": "req-001",
  "command": "device.ping",
  "params": {}
}

响应

{
  "request_id": "req-001",
  "ok": true,
  "error_code": null,
  "data": {}
}

3. 初版命令

命令	方向	用途
device.ping	PC -> 设备	检查设备在线状态。
device.info	PC -> 设备	读取设备型号、固件版本、序列号。
device.state.get	PC -> 设备	读取当前状态机状态。
resource.pack.info	PC -> 设备	读取当前资源包信息。
resource.pack.prepare	PC -> 设备	准备接收或校验资源包。
play.sync	PC -> 设备	下发同步播放状态。
play.stop	PC -> 设备	停止当前播放并回到可控状态。
factory.test.start	PC -> 设备	开始出厂测试。
factory.test.result	PC -> 设备	读取出厂测试结果。

4. 示例：同步播放

{
  "request_id": "req-100",
  "command": "play.sync",
  "params": {
    "content_id": "concert-demo-001",
    "state": "playing",
    "position_ms": 12345,
    "speed": 1.0
  }
}

5. 错误码初稿

错误码	说明
INVALID_COMMAND	未知命令。
INVALID_PARAMS	参数缺失或格式错误。
RESOURCE_NOT_READY	资源包未准备好。
STATE_CONFLICT	当前状态不允许执行该命令。
FACTORY_TEST_FAILED	出厂测试存在失败项。
INTERNAL_ERROR	设备内部错误。

6. 待确认问题

• 传输层帧格式和最大消息大小。
• 大资源包传输是否独立于控制协议。
• 设备序列号和生产批次字段格式。