# AI球设备控制协议

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

## 1. 设计原则

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

## 2. 通用消息格式

### 请求

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

### 响应

```json
{
  "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. 示例：同步播放

```json
{
  "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. 待确认问题

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