XiBox · API Reference
XiBox API 规范 v1.0
USB CDC · Wi-Fi 局域 · 云端 MQTT · OTA · APP 协议
每一个字节都有出处 · 每一个接口都可自动化
4
接入通道
JSON-RPC
主协议
MQTT 5.0
云端协议
XiBox API 规范 v1.0
摘要
本文档定义 XiBox 系列的对外编程接口,涵盖 USB Type-C(所有型号)、Wi-Fi 局域(Standard+)、蓝牙(Standard+)、云端 MQTT(AI 版) 四大通道。 目标读者:XiStudio 集成工程师、车主 APP 开发者、第三方工具开发者、Tier1 集成方。
API 红线
- 协议版本号
v1.x内向后兼容;破坏性变更升v2.x并提前 6 个月公告 - 只读 CAN——XiBox 监听车身总线,绝不主动发帧
- 所有 OTA 升级包必须 RSA-2048 签名,未签名包一律拒绝
- AI 版云端数据传输强制 TLS 1.3 + mTLS,明文传输一律拒绝
1. API 总览
1.1 四大接入通道
graph TB
XiBox[XiBox 设备]
XiBox --> USB[USB Type-C<br/>所有型号]
XiBox --> WiFi[Wi-Fi 局域<br/>Standard+]
XiBox --> BT[蓝牙音频 + 控制<br/>Standard+]
XiBox --> Cloud[云端 MQTT<br/>AI 版]
USB --> Host1[XiStudio PC]
WiFi --> Host2[XiStudio / 车主 APP]
BT --> Host3[车主 APP · 手机]
Cloud --> Host4[XiMind 云端]
class XiBox xyL1
class USB,WiFi,BT xyL2
class Cloud xyL5
class Host1,Host2,Host3,Host4 xyL41.2 协议分层
| 层 | USB | Wi-Fi 局域 | 蓝牙 | 云端 |
|---|---|---|---|---|
| 物理 | USB 2.0 | 802.11 b/g/n | BR/EDR + BLE | LTE/Wi-Fi |
| 传输 | CDC / Bulk | TCP + TLS 1.3 | RFCOMM / GATT | MQTT 5.0 + TLS 1.3 |
| 会话 | 自研 XiLink v1 | WebSocket | 自研 XiBT v1 | XiCloud v1 |
| 应用 | JSON-RPC 2.0 | JSON-RPC 2.0 | JSON(精简) | JSON + Protobuf |
1.3 消息分类
| 类别 | 方向 | 示例 |
|---|---|---|
| 系统控制 | Host → Box | Reboot / FactoryReset / GetVersion |
| 参数下发 | Host → Box | SetEQ / SetDRC / SetVolume |
| 状态查询 | Host → Box | GetStatus / GetTemp / GetMeter |
| 事件推送 | Box → Host | TempAlarm / ClipAlert / PresetChanged |
| 固件升级 | Host → Box | OTA_Start / OTA_Chunk / OTA_Verify |
2. USB API(所有型号)
2.1 物理与端点
- USB Class:CDC-ACM(虚拟串口)+ WinUSB(高速数据)
- Vendor ID:0x{XiSoundVID}(量产分配)
- Product ID:0x0401(Mini)/ 0x0402(Standard)/ 0x0403(Pro)/ 0x0404(AI)
- Baud rate:虚拟,无实际意义(USB 实际速度 12 Mbps / 480 Mbps)
2.2 会话建立
Host → Box: {"jsonrpc":"2.0","id":1,"method":"session.open","params":{"client":"XiStudio","ver":"1.0"}}
Box → Host: {"jsonrpc":"2.0","id":1,"result":{"session_id":"abc123","box_ver":"mini-1.0.3","caps":["eq","drc","ota","preset"]}}
2.3 典型命令
系统
// 获取版本
{"jsonrpc":"2.0","id":2,"method":"sys.version"}
// → {"hw":"MINI-M1","fw":"1.0.3","dsp":"D1-2.1","preset_lib":"2026Q4"}
// 重启
{"jsonrpc":"2.0","id":3,"method":"sys.reboot","params":{"mode":"normal"}}
// mode: normal | bootloader | factory
// 恢复出厂
{"jsonrpc":"2.0","id":4,"method":"sys.factory_reset","params":{"confirm":true}}
参数下发
// 设置 EQ(4 通道,每通道 10 段)
{"jsonrpc":"2.0","id":5,"method":"dsp.eq.set","params":{
"channel": 0,
"bands": [
{"type":"peak","fc":80,"gain":-3,"q":1.2},
{"type":"shelf_low","fc":200,"gain":2,"q":0.7}
]
}}
// 设置音量(整机)
{"jsonrpc":"2.0","id":6,"method":"dsp.volume.set","params":{"db":-6.0}}
// 加载预设
{"jsonrpc":"2.0","id":7,"method":"preset.load","params":{"id":"standard"}}
// 内置预设: standard / dynamic / vocal / classical / cinema
状态查询
{"jsonrpc":"2.0","id":8,"method":"sys.status"}
// → {"temp_c":42,"cpu_load":0.35,"uptime_s":123456,"preset":"standard","mute":false}
{"jsonrpc":"2.0","id":9,"method":"dsp.meter.get","params":{"channel":0}}
// → {"peak_db":-12.3,"rms_db":-24.1,"clip":false}
2.4 事件推送(Box → Host)
事件通过无 id 的 JSON-RPC Notification 推送:
{"jsonrpc":"2.0","method":"event.temp_alarm","params":{"temp_c":96,"level":"warn"}}
{"jsonrpc":"2.0","method":"event.clip","params":{"channel":2}}
{"jsonrpc":"2.0","method":"event.preset_changed","params":{"id":"vocal","source":"knob"}}
2.5 错误码
| code | 含义 | 示例 |
|---|---|---|
| -32000 | 未初始化 | 会话未 open |
| -32001 | 参数越界 | EQ gain > +18 dB |
| -32002 | 设备忙 | OTA 进行中 |
| -32003 | 权限拒绝 | 未授权方法 |
| -32004 | 存储失败 | 写 Flash 错误 |
| -32005 | 签名失败 | OTA 包未签名 |
3. Wi-Fi 局域 API(Standard+)
3.1 发现
- mDNS:服务名
_xibox._tcp.local - 端口:TCP 54321(控制)+ TCP 54322(音频流,Pro+)
- 认证:首次通过 USB 配对颁发设备 Token;Wi-Fi 连接需 Token 鉴权
3.2 WebSocket 通道
- 内部协议与 USB 完全一致(JSON-RPC 2.0)
- 支持双向推送、心跳(
ping/pong每 30s) - 并发连接数限制:3 个客户端(XiStudio / APP / Web 各一)
3.3 REST 子接口(便于脚本)
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /v1/status |
快速查询设备状态(无需 WS) |
| POST | /v1/preset/{id}/load |
加载预设 |
| GET | /v1/firmware |
查询固件版本 |
| POST | /v1/ota/upload |
上传 OTA 包(multipart) |
4. 蓝牙 API(Standard+)
4.1 蓝牙音频(A2DP)
- Profile:A2DP 1.3 + AVRCP 1.6
- Codec:SBC(强制)+ AAC(可选)+ LDAC(Pro+ 可选)
- 采样率:44.1 / 48 kHz
- 延迟:典型 120 ms(SBC)/ 50 ms(LDAC)
4.2 蓝牙控制(BLE GATT)
Service UUID:0xF100-XiSoundBox(量产分配)
| Characteristic | UUID | 读写 | 含义 |
|---|---|---|---|
| DeviceInfo | 0xF101 | R | JSON 字符串(型号 / 固件) |
| PresetList | 0xF102 | R | JSON 数组(预设列表) |
| PresetLoad | 0xF103 | W | 写入预设 ID |
| Volume | 0xF104 | R/W | int8 dB(-40 ~ 0) |
| EventNotify | 0xF105 | Notify | 事件推送(精简 JSON) |
4.3 配对流程
- 用户首次配对:APP 扫描 → 选 XiBox → 弹出 6 位数 PIN(显示在 XiStudio 或 APP 提示)
- 配对成功后写入白名单,后续自动重连
- 最多 3 个已配对设备
5. 云端 API(AI 版专属)
5.1 架构总览
graph LR
XiBoxAI[XiBox AI<br/>车端]
Gateway[XiCloud 网关]
MQTT[MQTT Broker]
XiMind[XiMind 推理服务]
APP[车主 APP]
XiBoxAI -->|mTLS MQTT 5.0| Gateway
Gateway --> MQTT
MQTT --> XiMind
APP -->|HTTPS| Gateway
Gateway -->|下发参数| MQTT
MQTT -->|参数到车| XiBoxAI
class XiBoxAI xyL1
class Gateway xyL4
class MQTT xyL4
class XiMind xyL5
class APP xyL45.2 MQTT 主题规范
- 设备上报:
xibox/{device_id}/up/status·xibox/{device_id}/up/event·xibox/{device_id}/up/telemetry - 云端下发:
xibox/{device_id}/dn/cmd·xibox/{device_id}/dn/params·xibox/{device_id}/dn/ota - 共享广播:
xibox/broadcast/preset-lib·xibox/broadcast/firmware
5.3 典型消息(Protobuf 定义摘要)
// 场景请求(APP → XiMind → XiBox)
message SceneRequest {
string scene = 1; // "night_bass" / "morning_vocal" / 自然语言
string user_id = 2;
map<string, string> context = 3; // 环境上下文(时间/车速)
}
// 参数下发(XiMind → XiBox)
message XiAlgoParams {
string preset_id = 1;
repeated EQBand eq = 2;
DRCParams drc = 3;
string ai_session_id = 4;
int32 ttl_seconds = 5; // 参数生存期
}
// 使用数据回传
message UsageTelemetry {
int64 ts = 1;
string event_type = 2; // "volume_up"/"preset_switch"/"scene_select"
string preset_id = 3;
float volume_db = 4;
string anonymized_ctx = 5;
}
5.4 认证
- 设备端:证书 X.509
xibox-device.crt+ 私钥(出厂烧录 · 不可读出) - 用户端:OAuth 2.0(XiMind 账号)+ JWT Token
- 权限:每 user 可绑定 ≤ 3 台 XiBox
5.5 流控与熔断
- 上报频率:状态每 60s · 事件触发即发 · 遥测每 5 分钟
- 下发频率:云端单 device 每秒不超过 5 条 cmd
- 断网:本地缓存最多 1000 条遥测 · 重连后批量回传
- 熔断:连续 10 次签名失败 → 设备进入 Safe Mode · XiMind 禁用 24h
6. OTA 升级 API
6.1 OTA 包格式(.xyfw)
+------------------+
| Header 64 bytes | magic / ver / size / hash / sig
+------------------+
| Manifest JSON | chunks 清单 + 回滚标记
+------------------+
| Chunk 1 (64KB) |
| Chunk 2 (64KB) |
| ... |
+------------------+
| Signature 256B | RSA-2048 + SHA-256
+------------------+
6.2 USB/Wi-Fi OTA 流程
// 1. 开始
{"method":"ota.start","params":{"fw_ver":"1.0.4","size":1048576,"chunks":16}}
// → {"session":"ota-x1","accepted":true}
// 2. 分片上传(每 64KB)
{"method":"ota.chunk","params":{"session":"ota-x1","idx":0,"data":"base64...","crc32":"a1b2c3d4"}}
// 3. 结束校验
{"method":"ota.verify","params":{"session":"ota-x1"}}
// → {"statusvalid":true}
// 4. 触发切换
{"method":"ota.commit","params":{"session":"ota-x1","reboot":true}}
6.3 云端 OTA(AI 版)
- XiMind 通过
xibox/{id}/dn/ota下发清单 - XiBox 从 CDN 拉取 chunks
- 支持差分升级(bsdiff)· 减少流量消耗 70%+
7. XiStudio 集成协议
7.1 设备枚举
XiStudio 启动时并行扫描:
- USB 枚举(VID/PID 匹配)
- Wi-Fi mDNS 查询
- 蓝牙 BLE 扫描(Standard+)
7.2 工程文件格式
.xiproj:XiStudio 工程(JSON).xifw:XiBox 固件包.xypreset:单预设(可跨车型导入).xyproject.zip:完整调音工程(含测量数据)
7.3 导入导出
| 操作 | 格式 | 路径 |
|---|---|---|
| 预设导出 | .xypreset |
XiStudio → 菜单 → 导出 |
| 工程备份 | .xyproject.zip |
定期自动备份 |
| 多车型迁移 | .xypreset + 调整表 |
手动调整输出映射 |
8. 第三方集成示例
8.1 Python SDK(规划 2027 Q3)
from xibox_sdk import XiBox
# 通过 USB 连接
box = XiBox.connect_usb()
# 加载预设
box.preset.load("vocal")
# 修改 EQ
box.dsp.eq.set(channel=0, bands=[
{"type": "peak", "fc": 120, "gain": -2.0, "q": 1.0}
])
# 订阅事件
@box.on("event.temp_alarm")
def handle_temp(data):
print(f"Temp warn: {data['temp_c']}°C")
8.2 CLI 工具
# 查询状态
xibox-cli status --transport=usb
# 批量烧录预设
xibox-cli preset upload --file=./preset-bundle.zip --target=all
# 触发 OTA
xibox-cli ota --firmware=./xibox-mini-1.0.4.xyfw
9. 安全规范
9.1 认证矩阵
| 接入 | 认证方式 | 备注 |
|---|---|---|
| USB | 物理接触即信任 + 可选 PIN | 改装店主要通道 |
| Wi-Fi | 首次 USB 配对颁发 Token | 防止邻车接入 |
| 蓝牙 | 配对 PIN + 白名单 | 最多 3 设备 |
| 云端 | mTLS + OAuth 2.0 | AI 版强制 |
9.2 敏感操作
以下操作必须双因子(Token + 物理按键确认):
- 恢复出厂设置
- 删除所有预设
- 擦除绑定账户(AI 版)
9.3 审计日志
- 所有 API 调用记录最近 1000 条
- USB 导出
.xylog(未加密但签名) - 云端可追溯(AI 版)
10. 版本兼容性策略
10.1 语义化版本
- 主版本(1.x.y → 2.0.0):破坏性变更,提前 6 月公告
- 次版本(1.0.x → 1.1.0):新增方法,向后兼容
- 补丁版本(1.1.0 → 1.1.1):Bug 修复,完全兼容
10.2 废弃策略
- 标记
@deprecated起保留 ≥ 12 个月 - 废弃方法返回额外字段
warn_deprecated: true - 文档高亮标注
11. 附录
11.1 关联文档
11.2 外部标准
- JSON-RPC 2.0 规范
- MQTT 5.0(OASIS)
- A2DP 1.3 / AVRCP 1.6 / BLE 5.0
- X.509 / RSA-2048 / AES-128 / TLS 1.3
- USB UAC 2.0 / CDC-ACM
11.3 版本历史
| 版本 | 日期 | 要点 |
|---|---|---|
| v1.0 | 2026-05-05 | 首版 · USB + Wi-Fi + BT + 云端 API 规范 |
api.md · D2-P4-TECH-002 · v1.0 · 2026-05-05 · Xisound 研发中心 · 软件团队