314 lines
7.9 KiB
Markdown
314 lines
7.9 KiB
Markdown
# USB CDC 串口通信协议规范
|
||
|
||
## 概述
|
||
|
||
本协议定义了上位机（PC）与设备之间通过USB CDC进行音频数据传输和命令控制的通信格式。协议采用二进制帧格式，支持命令、音频数据和MD5校验等功能。
|
||
|
||
## 协议版本
|
||
|
||
- 版本号：1.0
|
||
- 更新日期：2026-01-07
|
||
|
||
## 帧格式
|
||
|
||
### 基本帧结构
|
||
|
||
```
|
||
+--------+--------+--------+--------+--------+--------+
|
||
| Magic | Type | Length | Data | Check |
|
||
| 2 Bytes| 1 Byte | 4 Bytes | N Bytes| 1 Byte |
|
||
+--------+--------+--------+--------+--------+--------+
|
||
```
|
||
|
||
**注意：** 音频数据帧（Type=0x03）的Check字段固定填充为0x00，不进行实际校验计算，保持协议格式一致性。
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 长度 | 说明 |
|
||
|------|------|------|
|
||
| Magic | 2 字节 | 魔数，固定为 `0xAA55`（大端序），用于帧同步 |
|
||
| Type | 1 字节 | 数据类型，见下表 |
|
||
| Length | 4 字节 | 数据长度（小端序），仅指Data字段的长度<br>**命令/响应/MD5帧**: ≤64字节<br>|
|
||
| Data | N 字节 | 实际数据内容，长度由Length字段指定 |
|
||
| Check | 1 字节 | 校验和，对整个帧（除Check字段外）进行XOR校验<br>**音频帧固定填充0x00** |
|
||
|
||
**数据长度限制说明：**
|
||
- 命令请求/响应/MD5帧的Data字段最大64字节
|
||
- 这种区分设计可节省非音频帧的内存占用
|
||
|
||
### 数据类型（Type）
|
||
|
||
| 类型值 | 名称 | 方向 | 说明 |
|
||
|--------|------|------|------|
|
||
| 0x01 | CMD_REQUEST | PC → 设备 | 命令请求 |
|
||
| 0x02 | CMD_RESPONSE | 设备 → PC | 命令响应 |
|
||
| 0x03 | AUDIO_DATA | 设备 → PC | 音频数据 |
|
||
| 0x04 | MD5_DATA | 设备 → PC | MD5校验值 |
|
||
|
||
## 命令定义
|
||
|
||
### 命令码
|
||
|
||
| 命令码 | 名称 | 说明 |
|
||
|--------|------|------|
|
||
| 0x01 | CMD_START_RECORD | 开始录音 |
|
||
| 0x02 | CMD_STOP_RECORD | 停止录音 |
|
||
| 0x03 | CMD_QUERY_STATUS | 查询状态 |
|
||
|
||
### 命令请求格式（CMD_REQUEST）
|
||
|
||
**Data字段格式：**
|
||
```
|
||
+--------+--------+
|
||
| CmdID | Params |
|
||
| 1 Byte | N Bytes|
|
||
+--------+--------+
|
||
```
|
||
|
||
- **CmdID**: 命令码
|
||
- **Params**: 命令参数（可选，长度根据具体命令而定）
|
||
|
||
### 命令响应格式（CMD_RESPONSE）
|
||
|
||
**Data字段格式：**
|
||
```
|
||
+--------+--------+--------+
|
||
| CmdID | Status | Data |
|
||
| 1 Byte | 1 Byte | N Bytes|
|
||
+--------+--------+--------+
|
||
```
|
||
|
||
- **CmdID**: 对应的命令码
|
||
- **Status**: 状态码（0x00=成功，0x01=失败，0x02=忙碌，0x03=不支持）
|
||
- **Data**: 响应数据（可选）
|
||
|
||
### 状态码定义
|
||
|
||
| 状态码 | 名称 | 说明 |
|
||
|--------|------|------|
|
||
| 0x00 | STATUS_OK | 命令执行成功 |
|
||
| 0x01 | STATUS_ERROR | 命令执行失败 |
|
||
| 0x02 | STATUS_BUSY | 设备忙碌 |
|
||
| 0x03 | STATUS_UNSUPPORTED | 不支持的命令 |
|
||
|
||
## 数据格式
|
||
|
||
### 音频数据（AUDIO_DATA）
|
||
|
||
**Data字段格式：**
|
||
```
|
||
+--------+--------+
|
||
| SeqNum | PCM |
|
||
| 4 Bytes| N Bytes|
|
||
+--------+--------+
|
||
```
|
||
|
||
- **SeqNum**: 序列号（小端序），用于检测丢包，从0开始递增
|
||
- **PCM**: 原始PCM音频数据
|
||
|
||
**注意：** 音频数据帧保留Check校验字节，但固定填充为0x00，不进行实际校验计算。这样保持协议格式一致性，数据完整性由最终的MD5校验保证。
|
||
|
||
### MD5数据（MD5_DATA）
|
||
|
||
**Data字段格式：**
|
||
```
|
||
+--------+
|
||
| MD5 |
|
||
|16 Bytes|
|
||
+--------+
|
||
```
|
||
|
||
- **MD5**: 音频数据的MD5哈希值（128位）
|
||
|
||
## 通信流程
|
||
|
||
### 开始录音流程
|
||
|
||
```
|
||
PC 设备
|
||
| |
|
||
|---- CMD_START_RECORD ---->|
|
||
| | 开始录音
|
||
|<--- CMD_RESPONSE(OK) -----|
|
||
| |
|
||
|<--- AUDIO_DATA(SeqNum=0)--|
|
||
|<--- AUDIO_DATA(SeqNum=1)--|
|
||
|<--- AUDIO_DATA(SeqNum=2)--|
|
||
| ... |
|
||
```
|
||
|
||
### 停止录音流程
|
||
|
||
```
|
||
PC 设备
|
||
| |
|
||
|---- CMD_STOP_RECORD ----->|
|
||
| | 停止录音
|
||
|<--- AUDIO_DATA(last) -----|
|
||
|<--- MD5_DATA -------------|
|
||
|<--- CMD_RESPONSE(OK) -----|
|
||
| |
|
||
```
|
||
|
||
### 查询状态流程
|
||
|
||
```
|
||
PC 设备
|
||
| |
|
||
|---- CMD_QUERY_STATUS ---->|
|
||
| |
|
||
|<--- CMD_RESPONSE ---------|
|
||
| (Status + Data) |
|
||
| |
|
||
```
|
||
|
||
**查询状态响应Data格式：**
|
||
```
|
||
+--------+--------+--------+--------+
|
||
| State | TotalBytes | SeqNum |
|
||
| 1 Byte | 4 Bytes | 4 Bytes|
|
||
+--------+--------+--------+--------+
|
||
```
|
||
|
||
- **State**: 当前状态（0x00=空闲，0x01=正在录音）
|
||
- **TotalBytes**: 已传输的总字节数（小端序）
|
||
- **SeqNum**: 当前序列号（小端序）
|
||
|
||
## 校验算法
|
||
|
||
### XOR校验
|
||
|
||
对除Check字段外的所有字节进行XOR运算：
|
||
|
||
```c
|
||
uint8_t calculate_checksum(uint8_t *data, uint32_t len) {
|
||
uint8_t checksum = 0;
|
||
for (uint32_t i = 0; i < len; i++) {
|
||
checksum ^= data[i];
|
||
}
|
||
return checksum;
|
||
}
|
||
```
|
||
|
||
### MD5校验
|
||
|
||
使用标准MD5算法对所有音频数据进行校验：
|
||
|
||
1. 设备端：对发送的所有PCM数据进行MD5计算
|
||
2. 停止录音后，设备发送MD5_DATA帧
|
||
3. PC端：对接收的所有PCM数据进行MD5计算并与设备端发送的MD5对比
|
||
|
||
## 示例
|
||
|
||
### 示例1：开始录音命令
|
||
|
||
**PC发送：**
|
||
```
|
||
AA 55 01 01 00 00 00 01 FA
|
||
```
|
||
|
||
解析：
|
||
- Magic: `AA 55`
|
||
- Type: `01` (CMD_REQUEST)
|
||
- Length: `01 00 00 00` (1字节，小端序)
|
||
- Data: `01` (CMD_START_RECORD)
|
||
- Check: `FA` (XOR校验)
|
||
|
||
**设备响应：**
|
||
```
|
||
AA 55 02 02 00 00 00 01 00 F8
|
||
```
|
||
|
||
解析：
|
||
- Magic: `AA 55`
|
||
- Type: `02` (CMD_RESPONSE)
|
||
- Length: `02 00 00 00` (2字节)
|
||
- Data: `01 00` (CmdID=0x01, Status=0x00成功)
|
||
- Check: `F8`
|
||
|
||
### 示例2：音频数据
|
||
|
||
**设备发送：**
|
||
```
|
||
AA 55 03 08 00 00 00 00 00 00 00 XX XX XX XX
|
||
```
|
||
|
||
解析：
|
||
- Magic: `AA 55`
|
||
- Type: `03` (AUDIO_DATA)
|
||
- Length: `08 00 00 00` (8字节)
|
||
- Data: `00 00 00 00 XX XX XX XX` (SeqNum=0, PCM数据4字节)
|
||
- Check: **无** (音频帧不包含校验字节)
|
||
|
||
### 示例3：MD5数据
|
||
|
||
**设备发送：**
|
||
```
|
||
AA 55 04 10 00 00 00 [16字节MD5] XX
|
||
```
|
||
|
||
解析：
|
||
- Magic: `AA 55`
|
||
- Type: `04` (MD5_DATA)
|
||
- Length: `10 00 00 00` (16字节)
|
||
- Data: 16字节MD5值
|
||
- Check: `XX`
|
||
|
||
## 错误处理
|
||
|
||
### 帧错误
|
||
|
||
1. **魔数错误**：丢弃当前字节，继续搜索魔数
|
||
2. **校验错误**：丢弃整个帧，请求重传（可选）
|
||
3. **长度异常**：丢弃整个帧
|
||
|
||
### 超时处理
|
||
|
||
- **命令超时**：PC端发送命令后，2秒内未收到响应视为超时
|
||
- **数据超时**：录音过程中，5秒内未收到数据视为断连
|
||
|
||
### 序列号检查
|
||
|
||
- PC端应检查音频数据的SeqNum是否连续
|
||
- 如果发现跳号，说明有数据丢失
|
||
|
||
## 实现注意事项
|
||
|
||
### 设备端（C语言）
|
||
|
||
1. **内存管理**：使用环形缓冲区管理数据帧
|
||
2. **多线程**：命令处理和数据发送应分开不同任务
|
||
3. **优先级**：命令处理优先级应高于音频数据发送
|
||
4. **MD5计算**：使用增量方式计算MD5，避免一次性读取所有数据
|
||
|
||
### PC端（Python）
|
||
|
||
1. **异步接收**：使用独立线程接收数据
|
||
2. **帧解析**：实现状态机进行帧解析，处理粘包/拆包
|
||
3. **超时机制**：实现命令超时和数据超时检测
|
||
4. **MD5对比**：实时计算接收数据的MD5，录音结束后对比
|
||
|
||
## 扩展性
|
||
|
||
协议预留了扩展空间：
|
||
|
||
1. **命令扩展**：可以添加新的命令码（0x04-0xFF）
|
||
2. **数据类型扩展**：可以添加新的数据类型（0x05-0xFF）
|
||
3. **参数扩展**：每个命令的Params字段可以自定义格式
|
||
|
||
## 参考实现
|
||
|
||
- 设备端实现：[src/middleware/usb/app_usb_cdc.c](../src/middleware/usb/app_usb_cdc.c)
|
||
- PC端实现：[tools/audio/serial_capture.py](../tools/audio/serial_capture.py)
|
||
- 协议库：[src/middleware/usb/cdc_protocol.c](../src/middleware/usb/cdc_protocol.c)
|
||
|
||
## 版本历史
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
|------|------|------|
|
||
| 1.0 | 2026-01-07 | 初始版本，定义基本协议格式和命令 |
|
||
|
||
## 联系方式
|
||
|
||
如有问题或建议，请联系开发团队。
|