MIGRATED

XiAmp API 文档 v1.0

摘要

本文档定义 XiAmp 系列功放的对外编程接口：CAN-FD 车规诊断（UDS / OBD）、USB Type-C 控制、FOTA 升级协议、REST 调试接口（Pro+）、内部 MCU ↔ XiDSP IPC。目标读者：Tier1 / 主机厂集成工程师、FOTA 后端开发、产线测试工程师、整车诊断工程师。

稳定性契约

CAN 报文 ID + DLC + Payload 字节序 一旦 Datasheet 发布后保持向后兼容
UDS Service ID 按 ISO 14229 标准，Xisound 专用 DID 区段 0xF1E0-0xF1FF
FOTA 包结构 Major 版本兼容性 10 年
REST API 遵循 SemVer（仅 Pro+ 车规高阶功能提供）

1. CAN-FD 车规诊断

1.1 CAN 总线参数

参数	Lite	Pro+
波特率	500 kbps	1 Mbps CAN / 5 Mbps CAN-FD
数据长度	8 bytes	64 bytes (FD)
诊断地址	11-bit	29-bit
终端电阻	客户板上 120Ω × 2	同

1.2 UDS 服务清单（ISO 14229）

SID	服务	说明
0x10	Diagnostic Session Control	进入诊断会话
0x11	ECU Reset	重启 XiAmp
0x22	Read Data By Identifier	读 DID
0x2E	Write Data By Identifier	写 DID
0x27	Security Access	Seed & Key 握手
0x31	Routine Control	运行诊断例程（自检）
0x34	Request Download	FOTA 下载准备
0x36	Transfer Data	FOTA 数据传输
0x37	Request Transfer Exit	FOTA 结束

1.3 Xisound 专用 DID 表

DID	名称	访问	长度	说明
0xF180	硬件版本	RO	4 B	板卡 HW Rev
0xF181	固件版本	RO	4 B	MCU + DSP 组合
0xF182	Serial Number	RO	16 B	出厂唯一序列号
0xF183	VIN 绑定	RW	17 B	车架号绑定（车规）
0xF1E0	当前模式	RW	1 B	0=Off / 1=Standard / 2=Dynamic / 3=Voice
0xF1E1	主音量	RW	1 B	0-100
0xF1E2	通道静音	RW	2 B	bitmap
0xF1E3	EQ Preset 索引	RW	1 B	0=Flat / 1-7=自定义
0xF1F0	温度读数	RO	2 B	0.1°C 精度
0xF1F1	当前功率	RO	8 B	4ch × 2B RMS
0xF1FF	DTC 清单	RO	128 B	故障码列表

1.4 典型诊断流程

sequenceDiagram
    autonumber
    participant 工具 as 诊断工具
    participant Amp as XiAmp
    工具->>Amp: 0x10 02 (进入扩展会话)
    Amp->>工具: 0x50 02 ACK
    工具->>Amp: 0x27 01 (Request Seed)
    Amp->>工具: 0x67 01 SEED
    工具->>Amp: 0x27 02 KEY
    Amp->>工具: 0x67 02 ACK (解锁成功)
    工具->>Amp: 0x22 F1 82 (读 SN)
    Amp->>工具: 0x62 F1 82 <16 字节 SN>

1.5 DTC 故障码分配（节选）

DTC	含义	严重度
P0A01	DSP 初始化失败	高
P0A02	ADC 校准失败	中
P0A10	过温（> 115°C）	高
P0A11	过流（单通道 > 10A）	高
P0A20	CAN 总线关闭	中
P0A30	电源欠压（< 9V）	高
P0A40	FOTA 校验失败	中

2. USB Type-C 控制接口

2.1 USB 枚举信息

参数	值
VID	0x2E8A（Xisound）
PID	0x01A0（Lite-4）/ 0x01A1（Lite-8）...
Class	CDC ACM（虚拟串口） + HID（烧录）
波特率	921600 bps（虚拟串口）

2.2 命令格式

[STX] [CMD] [LEN] [PAYLOAD] [CRC16] [ETX]
  1B    1B    2B    N B        2B     1B

2.3 常用命令

CMD	名称	Payload	响应
0x01	Ping	—	Pong + FW Version
0x10	Get Status	—	模式 / 音量 / 温度
0x11	Set Volume	1B 音量	OK/Fail
0x12	Set Mode	1B 模式	OK/Fail
0x20	Read DID	2B DID	数据
0x21	Write DID	2B DID + N B	OK/Fail
0x30	FOTA Start	4B 总大小 + 32B SHA	OK + Block Size
0x31	FOTA Chunk	4B Offset + N B	OK
0x32	FOTA End	—	OK（验证通过）/ Fail
0xF0	Read Log	4B Offset + 2B Len	日志文本
0xFF	Reboot	—	—

2.4 Python 示例

from xiamp_cli import XiAmp

amp = XiAmp.open("COM7")
print(amp.ping())            # FW v1.0.1
print(amp.get_status())      # {mode: 1, volume: 60, temp_c: 42.5}
amp.set_volume(75)
amp.set_mode("Dynamic")      # 1=Standard 2=Dynamic 3=Voice

# 烧录固件
amp.flash("xiamp-lite4-v1.0.2.xifw", verify=True)

3. FOTA 升级协议

3.1 FOTA 包结构

+----------------------+  0x0000
| Magic "XAMP"         |  4 B
+----------------------+
| FOTA Version         |  4 B
+----------------------+
| Target HW            |  4 B  (板卡型号)
+----------------------+
| MCU FW Size          |  4 B
+----------------------+
| DSP FW Size          |  4 B
+----------------------+
| Timestamp            |  8 B
+----------------------+
| SHA-256 of Payload   |  32 B
+----------------------+
| RSA-2048 Signature   |  256 B
+----------------------+
| Padding              |  to 0x200
+----------------------+
| MCU Firmware         |  MCU FW Size
+----------------------+
| DSP Firmware         |  DSP FW Size
+----------------------+

3.2 升级状态机

graph LR
    Idle[空闲] --> Init[初始化 · 接收 Start]
    Init --> Transfer[分片传输]
    Transfer --> Verify[校验签名]
    Verify -- OK --> Apply[应用到 B 分区]
    Verify -- Fail --> Abort[终止 · 报错]
    Apply --> Reboot[重启到 B]
    Reboot -- 启动成功 --> Commit[提交 · 正式启用]
    Reboot -- 失败 --> Rollback[回滚到 A]

    class Idle xyL0
    class Init,Transfer,Verify xyL2
    class Apply xyL3
    class Reboot xyL4
    class Commit xySuccess
    class Abort,Rollback xyError

3.3 断点续传

支持按 Offset 字段断点续传
MCU 每 256KB 保存一个 checkpoint
网络中断后继续，无需从头开始

4. REST 调试接口（Pro+ 车规）

4.1 访问方式

仅限调试模式启用（通过 USB 开启），常规客户端禁用。

http://192.168.4.1:8080/api/v1/

4.2 常用端点

端点	方法	说明
`/status`	GET	整体状态 JSON
`/volume`	GET/PUT	主音量
`/preset`	GET/PUT	EQ Preset
`/dtc`	GET/DELETE	读/清 DTC
`/spectrum`	GET	实时频谱（WebSocket）
`/fota`	POST	上传 FOTA 包

4.3 JSON Schema 示例

GET /status 响应：
{
  "hw_version": "Lite-4 M1",
  "fw_version": "1.0.1",
  "mode": "Dynamic",
  "volume": 65,
  "channels": [
    {"ch": 0, "name": "Front-L", "power_w": 12.3, "clip": false},
    {"ch": 1, "name": "Front-R", "power_w": 12.5, "clip": false},
    {"ch": 2, "name": "Rear-L",  "power_w": 8.2,  "clip": false},
    {"ch": 3, "name": "Rear-R",  "power_w": 8.4,  "clip": false}
  ],
  "temperature_c": 42.5,
  "supply_v": 13.8,
  "uptime_s": 3600
}

5. 内部 MCU ↔ XiDSP IPC

5.1 XiIPC v1.0 协议

+--------+--------+--------+--------+----------+--------+
| STX 1B | LEN 2B | SEQ 1B | CMD 1B | PAYLOAD  | CRC 2B |
+--------+--------+--------+--------+----------+--------+

5.2 IPC 消息类型

CMD	说明	方向
0x01	SetMode	MCU → DSP
0x02	SetVolume	MCU → DSP
0x10	DSP Status Report	DSP → MCU
0x11	DSP Log	DSP → MCU
0x20	Graph Load	MCU → DSP
0x30	Param Update	MCU → DSP
0xF0	DSP Heartbeat	DSP → MCU（每 100 ms）
0xFF	Emergency Stop	双向

5.3 错误处理

超时（50 ms 无响应）→ 重传 3 次 → 失败记 DTC
3 次 Heartbeat 丢失 → 重启 DSP

6. 示例：车机主动切换模式

sequenceDiagram
    autonumber
    participant 车机 as 车机主机
    participant Amp as XiAmp MCU
    participant DSP as XiDSP
    车机->>Amp: CAN 写 DID 0xF1E0 = 0x02 (Dynamic)
    Amp->>DSP: IPC CMD 0x01 SetMode=Dynamic
    DSP->>DSP: 切换算法图（100 ms）
    DSP->>Amp: ACK + 状态报告
    Amp->>车机: CAN 响应 0x6E F1 E0 00 (Success)

7. 安全与合规

7.1 车规网络安全（Pro+）

诊断会话：Seed & Key 握手（Secure Access）
固件签名：RSA-2048 + SHA-256
Anti-Rollback：OTP Version Counter
CAN 入侵检测：异常报文限流 + DTC 记录

7.2 隐私

无麦克风 / 摄像头 · 无隐私数据采集
VIN 绑定仅用于防盗 · 不上传云端

8. 附录

8.1 完整 DID 表

详见独立附录 D3-execution/xiamp-did-table.csv（Phase 3 后续批次发布）。

8.2 完整 UDS 服务表

详见 ISO 14229-1:2020 标准 + Xisound UDS 扩展补充文档。

8.3 关联文档

8.4 外部标准参考

ISO 14229-1（UDS 诊断）
ISO 15765（CAN 传输层）
ISO 11898-1（CAN-FD 物理层）
USB IF CDC-ACM 1.2

8.5 版本历史

版本	日期	要点
v1.0	2026-05-05	首版 · UDS + USB + FOTA + REST + IPC

api.md · D2-P3-TECH-002 · v1.0 · 2026-05-05 · Xisound 研发中心 · 硬件团队 + 固件团队