ftyyda/phaten-audio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
PhatenIoT-yan
2025-12-25 14:21:26 +08:00
parent ed34548c71
commit 00f42eab80
72 changed files with 2193 additions and 471 deletions
Download Patch File Download Diff File Expand all files Collapse all files

340
zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
View File

@@ -1,7 +1,7 @@
---
title: XMOS EQ HID 通信协议规范
status: new
description: XMOS EQ HID 通信协议规范文档
description: 适用于免开发固件系列设备的 EQ HID 控制协议，包含报文结构、命令集与字段说明，用于模式切换、参数读写与设备信息获取。
keywords: EQ, HID, 控制协议, 命令集, USB HID, XU316,免开发固件, Phaten Audio
authors:
- admin
tags:
@@ -34,21 +34,21 @@ search:
| 数据包大小 | 64字节（包含1字节Report ID 0x01） |
| 有效数据 | 63字节 |
| 字节序 | 小端序（Little Endian） |
| 同步头 | 0x77 (固定第一个字节) |
| 同步头 | 0x77（固定第1字节，Report ID 为第0字节） |
### 1.2 HID设备识别
| 参数 | 值 | 说明 |
|:----------:|:--------:|:-----------------------------------------:|
| Usage Page | 0xff82 或 0xff83 | HID设备类型标识 |
| Report ID | 0x01 | 发送时作为第一个字节 |
| Report ID | 0x01 | 发送时作为第一个字节（第0字节） |
| 传输模式 | 非阻塞模式 | 避免GUI卡顿 |
### 1.3 通信机制
!!! warning "数据传输说明"
- 所有数据均采用小端序（Little Endian）传输
- 同步头0x77必须作为每个数据包的第一个字节
- 同步头 0x77 固定在第 1 字节（第 0 字节为 Report ID = 0x01）
- 建议命令间隔5ms以上，避免设备处理不及时
## 二、协议命令集 :material-code-tags:
@@ -56,229 +56,219 @@ search:
### 2.1 命令分类概览
!!! note "命令使用说明"
1. 所有命令必须包含同步头0x77作为第一个字节
2. 数据包总长度固定为63字节（不含Report ID）
1. 所有命令必须包含 Report ID 0x01（第0字节）与同步头 0x77（第1字节）
2. 数据包总长度固定为 64 字节（含 Report ID）
3. 未使用的字节必须填充为0
#### 2.1.1 命令头定义
| 命令头 | 命令名称 | 功能描述 | 方向 |
|:------:|:--------:|:--------:|:----:|
| 0x8B | READ_EQ_MODE | 读取EQ模式状态 | PC → 设备 |
| 0x8C | SET_EQ_MODE | 设置EQ模式 | PC → 设备 |
| 0x8D | SET_EQ_PARAMS | 设置EQ参数 | PC → 设备 |
| 0x8E | READ_EQ_PARAMS | 读取EQ参数 | PC ↔ 设备 |
| 0x8F | SAVE_USER_MODE | 保存用户模式 | PC → 设备 |
| 0x90 | READ_ALL_MODES | 读取所有模式信息 | PC ↔ 设备 |
| 0x91 | RESET_USER_MODE | 重置用户模式 | PC → 设备 |
| 0x92 | GET_DEVICE_INFO | 获取设备信息 | PC ↔ 设备 |
| 0x8A | SET_EQ_MODE | 切换当前的 EQ 模式 | PC → 设备 |
| 0x8B | GET_EQ_MODE | 获取当前 EQ 模式信息（模式号、增益、名称） | PC → 设备 |
| 0x8C | SET_MODE_GAIN_AND_NAME | 设置指定模式的整体增益和名称 | PC → 设备 |
| 0x8D | SET_EQ_PARAMS | 发送单个滤波器的参数 | PC → 设备 |
| 0x8E | GET_EQ_PARAMS | 读取单个滤波器的参数 | PC ↔ 设备 |
| 0x8F | GET_DEVICE_INFO | 获取设备基础信息（PID/VID/SN） | PC ↔ 设备 |
| 0x90 | RESET_EQ_PARAMS | 复位 EQ 参数（恢复预设） | PC ↔ 设备 |
### 2.2 详细命令格式
#### 2.2.1 读取EQ模式（0x8B）
#### 2.2.1 切换 EQ 模式（0x8A）
**功能说明**: 读取当前设备EQ模式值
**功能说明**: 切换当前的 EQ 模式
**请求格式（63字节）**:
**请求格式（64 字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | 同步头: 0x77 |
| 1 | 1 | cmd_header | 命令头: 0x8B |
| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) |
| 6 | 1 | mode | 查询的模式值 |
| 7-62 | 56 | reserved | 保留字段（填充0） |
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x8A |
| 3 | 1 | mode | 模式值（0-5: 预设, 6-8: 用户, 9: Bypass） |
| 4-63 | 60 | reserved | 保留字段（填充0） |
#### 2.2.2 设置EQ模式（0x8C）
#### 2.2.2 获取当前 EQ 模式信息（0x8B）
**功能说明**: 正式的模式设置命令
**功能说明**: 获取当前模式值、整体增益与模式名称
**数据包格式（63字节）**:
**请求格式（64 字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | 同步头: 0x77 |
| 1 | 1 | cmd_header | 命令头: 0x8C |
| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) |
| 6 | 1 | mode | 模式值 (0-5: 预设模式, 6-7: 用户模式, 8: 禁用EQ) |
| 7-62 | 56 | reserved | 保留字段（填充0） |
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x8B |
| 3-63 | 61 | reserved | 保留字段（填充0） |
#### 2.2.3 设置EQ参数（0x8D）
**功能说明**: 发送单个滤波器的完整参数和系数
**数据包格式（63字节）**:
**响应格式（64 字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | 同步头: 0x77 |
| 1 | 1 | cmd_header | 命令头: 0x8D |
| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) |
| 6 | 1 | total_gain_db | 总增益补偿 (dB, 8位有符号整数) |
| 7 | 1 | filter_index | 滤波器索引 (0-7) |
| 8 | 1 | filter_type | 滤波器类型码 |
| 9 | 4 | fc | 中心频率 (Hz, 32位无符号整数) |
| 13 | 4 | q_value | Q值 (Q15.15格式, 32位有符号整数) |
| 17 | 4 | bandwidth | 带宽 (Hz, 32位无符号整数) |
| 21 | 4 | gain | 增益 (Q15.15格式, 32位有符号整数) |
| 25 | 38 | reserved | 保留字段（填充0） |
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x8B（回显） |
| 3 | 1 | mode | 当前模式值 |
| 4-7 | 4 | gain | 整体增益（int32, 小端序，范围 -50dB ~ 0dB） |
| 8-23 | 16 | name | 模式名称（UTF-8 字符串） |
| 24-63 | 40 | reserved | 保留字段（填充0） |
**滤波器类型码定义**:
#### 2.2.3 设置模式整体增益和名称（0x8C）
| 类型码 | 滤波器类型 | 英文名称 |
|:------:|:----------:|:--------:|
| 0x00 | bypass滤波器 | Bypass Filter |
| 0x01 | 全通滤波器 | All-pass Filter |
| 0x02 | 峰值滤波器 | Peaking Filter |
| 0x03 | 低通滤波器 | Low-pass Filter |
| 0x04 | 高通滤波器 | High-pass Filter |
| 0x05 | 带通滤波器 | Band-pass Filter |
| 0x06 | 带阻滤波器 | Band-stop Filter |
| 0x07 | 陷波滤波器 | Notch Filter |
| 0x08 | 恒定Q值滤波器 | Constant-Q Filter |
| 0x09 | 低架滤波器 | Low-shelf Filter |
| 0x0A | 高架滤波器 | High-shelf Filter |
**功能说明**: 设置目标模式的整体增益和名称
**数值格式定义**:
**请求格式（64 字节）**:
!!! info "Q15.15格式说明"
- **Q15.15格式**: 16位整数部分 + 16位小数部分
- 例如: Q值1.414 → 0x00016A09
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x8C |
| 3 | 1 | mode | 目标模式值（0-9） |
| 4-7 | 4 | gain | 整体增益（int32, 小端序） |
| 8-23 | 16 | name | 模式名称（UTF-8 字符串） |
| 24-63 | 40 | reserved | 保留字段（填充0） |
#### 2.2.4 读取EQ参数（0x8E）
#### 2.2.4 设置 EQ 参数（0x8D）
**功能说明**: 发送单个滤波器的参数
**请求格式（64 字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x8D |
| 3 | 1 | mode | 模式值（0-9） |
| 4 | 1 | band | 滤波器索引（0-7） |
| 5 | 1 | type | 滤波器类型码 |
| 6-9 | 4 | freq | 中心频率 Hz（float, 小端序） |
| 10-13 | 4 | q | Q 值（float, 小端序） |
| 14-17 | 4 | bw | 带宽 Hz（float, 小端序） |
| 18-21 | 4 | gain | 增益 dB（float, 小端序） |
| 22-63 | 42 | reserved | 保留字段（填充0） |
**滤波器类型码**:
| 代码 | 类型 | 代码 | 类型 |
|:----:|:----:|:----:|:----:|
| 0x00 | Bypass | 0x06 | 带阻（Band Reject） |
| 0x01 | 全通（All Pass） | 0x07 | 陷波（Notch） |
| 0x02 | 峰值（Peak） | 0x08 | 恒定Q（Constant Q） |
| 0x03 | 低通（Low Pass） | 0x09 | 低架（Low Shelf） |
| 0x04 | 高通（High Pass） | 0x0A | 高架（High Shelf） |
| 0x05 | 带通（Band Pass） | | |
**数值格式说明**:
!!! info "浮点数与字节序"
- 所有浮点数遵循 IEEE 754 float，采用小端序
- 所有多字节整数均采用小端序（Little Endian）
#### 2.2.5 读取 EQ 参数（0x8E）
**功能说明**: 读取指定滤波器的参数
**请求格式（63字节）**:
**请求格式（64 字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | 同步头: 0x77 |
| 1 | 1 | cmd_header | 命令头: 0x8E |
| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) |
| 6 | 1 | eq_index | 要读取的EQ索引 (0-7) |
| 7-62 | 56 | reserved | 保留字段（填充0） |
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x8E |
| 3 | 1 | mode | 模式值（0-9） |
| 4 | 1 | band | 滤波器索引（0-7） |
| 5-63 | 59 | reserved | 保留字段（填充0） |
**响应格式（63字节）**:
**响应格式（64 字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | 同步头: 0x77 |
| 1 | 1 | cmd_header | 命令头: 0x8E (回显) |
| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) |
| 6 | 1 | total_gain_db | 总增益补偿 (dB, 8位有符号整数) |
| 7 | 1 | eq_index | EQ索引 (0-7) |
| 8 | 1 | filter_type | 滤波器类型码 |
| 9 | 4 | fc | 中心频率 (Hz, 32位无符号整数) |
| 13 | 4 | q_value | Q值 (Q15.15格式, 32位有符号整数) |
| 17 | 4 | bandwidth | 带宽 (Hz, 32位无符号整数) |
| 21 | 4 | gain | 增益 (Q15.15格式, 32位有符号整数) |
| 25 | 38 | reserved | 保留字段（填充0） |
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x8E（回显） |
| 3 | 1 | mode | 模式值 |
| 4 | 1 | band | 滤波器索引 |
| 5 | 1 | type | 滤波器类型码 |
| 6-9 | 4 | freq | 中心频率 Hz（float, 小端序） |
| 10-13 | 4 | q | Q 值（float, 小端序） |
| 14-17 | 4 | bw | 带宽 Hz（float, 小端序） |
| 18-21 | 4 | gain | 增益 dB（float, 小端序） |
| 22-63 | 41 | reserved | 保留字段（填充0） |
#### 2.2.5 保存用户模式（0x8F）
**功能说明**: 将当前EQ参数保存到指定用户模式
**请求格式（63字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | 同步头: 0x77 |
| 1 | 1 | cmd_header | 命令头: 0x8F |
| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) |
| 6 | 1 | user_mode | 用户模式索引 (6-7) |
| 7 | 1 | source_mode | 源模式索引 (当前活动模式，用于复制参数) |
| 8-62 | 55 | reserved | 保留字段（填充0） |
#### 2.2.6 读取所有模式信息（0x90）
**功能说明**: 获取所有模式的基本信息和状态
**请求格式（63字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | 同步头: 0x77 |
| 1 | 1 | cmd_header | 命令头: 0x90 |
| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) |
| 6-62 | 57 | reserved | 保留字段（填充0） |
**响应格式（63字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | 同步头: 0x77 |
| 1 | 1 | cmd_header | 命令头: 0x90 (回显) |
| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) |
| 6 | 1 | current_mode | 当前活动模式 |
| 7 | 1 | eq_enabled | EQ总开关状态 (0: 关闭, 1: 开启) |
| 8 | 8 | mode_status | 模式状态数组 (每字节对应一个模式: 0=默认, 1=已修改, 2=已保存) |
| 16 | 8 | mode_names | 模式名称索引 (预设模式的名称标识) |
| 24 | 39 | reserved | 保留字段（填充0） |
#### 2.2.7 重置用户模式（0x91）
**功能说明**: 将用户模式重置为默认状态
**请求格式（63字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | 同步头: 0x77 |
| 1 | 1 | cmd_header | 命令头: 0x91 |
| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) |
| 6 | 1 | user_mode | 要重置的用户模式索引 (6-7, 0xFF表示重置所有用户模式) |
| 7-62 | 56 | reserved | 保留字段（填充0） |
#### 2.2.8 获取设备信息（0x92）
#### 2.2.6 获取设备信息（0x8F）
**功能说明**: 获取设备的基本标识信息
**请求格式（63字节）**:
**请求格式（64 字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | 同步头: 0x77 |
| 1 | 1 | cmd_header | 命令头: 0x92 |
| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) |
| 6-62 | 57 | reserved | 保留字段（填充0） |
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x8F |
| 3-63 | 61 | reserved | 保留字段（填充0） |
**响应格式（63字节）**:
**响应格式（64 字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | 同步头: 0x77 |
| 1 | 1 | cmd_header | 命令头: 0x92 (回显) |
| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) |
| 6 | 2 | vendor_id | 厂商ID (VID, 16位小端) |
| 8 | 2 | product_id | 产品ID (PID, 16位小端) |
| 10 | 2 | device_version | 设备版本号 (BCD格式) |
| 12 | 32 | device_name | 设备名称 (UTF-8编码, 以\0结尾) |
| 44 | 4 | serial_number | 序列号 (32位无符号整数) |
| 48 | 2 | protocol_ver | 协议版本 (主版本.次版本, 各占1字节) |
| 50 | 1 | eq_band_count | 支持的EQ频段数量 |
| 51 | 1 | mode_count | 支持的模式数量 |
| 52 | 11 | reserved | 保留字段（填充0） |
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x8F（回显） |
| 3-4 | 2 | pid | 产品ID（uint16, 小端序） |
| 5-6 | 2 | vid | 厂商ID（uint16, 小端序） |
| 7-22 | 16 | product | 产品字符串（UTF-8） |
| 23-38 | 16 | vendor | 厂商字符串（UTF-8） |
| 39-54 | 16 | sn | 序列号字符串（UTF-8） |
| 55-63 | 9 | reserved | 保留字段（填充0） |
#### 2.2.7 复位 EQ 参数（0x90）
**功能说明**: 复位指定模式或全部模式的 EQ 参数
**请求格式（64 字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x90 |
| 3 | 1 | mode | 模式号（0-9，0xFF 表示复位所有模式） |
| 4-63 | 60 | reserved | 保留字段（填充0） |
**响应格式（64 字节）**:
| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x90（回显） |
| 3 | 1 | status | 状态码（0x00=成功, 0x01=失败） |
| 4-63 | 60 | reserved | 保留字段（填充0） |
## 三、数据流程和时序 :material-timeline-clock:
### 3.1 典型操作流程
#### 3.1.1 模式切换流程
1. GUI发送SET_EQ_MODE命令 (0x8C)
1. GUI发送SET_EQ_MODE命令 (0x8A)
2. 设备更新内部模式状态
3. GUI发送READ_EQ_MODE命令 (0x8B) 确认
3. GUI发送GET_EQ_MODE命令 (0x8B) 确认
4. 设备响应当前模式状态
#### 3.1.2 参数设置流程
1. GUI发送SET_EQ_MODE命令切换到相应模式 (0x8C)
1. GUI发送SET_EQ_MODE命令切换到相应模式 (0x8A)
2. 逐个发送8个滤波器的命令 (0x8D)
3. 设备接收并更新内部参数缓存
4. 可选: 发送READ_EQ_PARAMS命令验证参数
4. 可选: 发送GET_EQ_PARAMS命令验证参数 (0x8E)
#### 3.1.3 参数读取流程
1. GUI发送SET_EQ_MODE命令切换到相应模式 (0x8C)
2. GUI发送READ_EQ_PARAMS请求 (0x8E)
1. GUI发送SET_EQ_MODE命令切换到相应模式 (0x8A)
2. GUI发送GET_EQ_PARAMS请求 (0x8E)
3. 设备准备响应数据
4. GUI读取响应
@@ -292,18 +282,19 @@ search:
!!! danger "协议限制和约束"
**硬件限制**
- **滤波器数量**: 固定8个滤波器（MAX_EQ_BANDS = 8）
- **模式数量**: 支持8个EQ模式（0-5为预设模式，6-7为用户模式）+ 1个禁用模式（8）
- **采样率支持**: 44.1kHz, 48kHz, 88.2kHz, 96kHz, 176.4kHz, 192kHz
- **滤波器数量**: 固定 8 个滤波器（MAX_EQ_BANDS = 8）
- **模式数量**: 0-5 为预设模式，6-8 为用户模式，9 为 Bypass 模式
- **采样率支持**: 44.1kHz, 48kHz, 88.2kHz, 96kHz, 176.4kHz, 192kHz（设备能力，与协议字段独立）
**参数范围**
| 参数 | 范围 | 格式 |
|:----:|:----:|:----:|
| 中心频率 (fc) | 20Hz - 20kHz | 32位无符号整数 |
| Q值 | 0.1 - 30.0 | Q15.15格式 |
| 增益 | -24dB - +24dB | Q15.15格式 |
| 总增益 | -24dB - 0dB | 8位有符号整数 |
| 中心频率 (freq) | 20Hz - 20kHz | float（小端） |
| Q值 (q) | 0.1 - 30.0 | float（小端） |
| 带宽 (bw) | 1Hz - 20kHz | float（小端） |
| 增益 (gain) | -24dB - +24dB | float（小端） |
| 整体增益 (mode gain) | -50dB - 0dB | int32（小端） |
## 四、预设模式定义 :material-equalizer:
@@ -311,7 +302,7 @@ search:
| 模式索引 | 模式名称 | 用途描述 | 类型 |
|:--------:|:--------:|:--------:|:----:|
| 0 | Flat/Linear | 平坦响应，无EQ处理 | 预设模式 |
| 0 | Flat/Linear | 平坦响应，无 EQ 处理 | 预设模式 |
| 1 | Pop/Rock | 流行摇滚音乐优化 | 预设模式 |
| 2 | Classical | 古典音乐优化 | 预设模式 |
| 3 | Jazz | 爵士音乐优化 | 预设模式 |
@@ -319,12 +310,13 @@ search:
| 5 | Bass Boost | 低音增强 | 预设模式 |
| 6 | User 1 | 用户自定义模式1 | 用户模式 |
| 7 | User 2 | 用户自定义模式2 | 用户模式 |
| 8 | Disabled | EQ功能禁用 | 特殊模式 |
| 8 | User 3 | 用户自定义模式3 | 用户模式 |
| 9 | Bypass | EQ 功能旁路 | 特殊模式 |
!!! info "模式特性说明"
- **预设模式**: 出厂预设，不可修改，针对特定音乐类型优化
- **用户模式**: 支持用户自定义参数，可保存和重置
- **禁用模式**: 完全关闭EQ处理，音频信号直通
- **旁路模式**: 完全关闭 EQ 处理，音频信号直通（Bypass）
---

225
zh/docs/dev_doc/protocols/XMOS_EQ_UART_Protocol.md Normal file
View File

@@ -0,0 +1,225 @@
---
title: XMOS EQ UART 控制协议与命令集
description: EQ 参数配置与控制的 UART 串口通信协议规范，涵盖帧格式、命令集与字段说明，适用于 XU316 等相关产品。
keywords: EQ, UART, 串口协议, 通信协议, 命令集, XU316,免开发固件, Phaten Audio
---
# XMOS EQ UART 控制协议与命令集
--8<-- "common/phaten_xmos_support_img.md"
## 1. 协议基础规范
### 1.1 底层通信协议
基于 UART (Universal Asynchronous Receiver/Transmitter) 协议。
| 参数 | 值 |
| :--- | :--- |
| 波特率 | 115200 bps |
| 数据位 | 8 |
| 奇偶校验 | 无 |
| 停止位 | 1 |
| 数据流控 | 无 |
### 1.2 帧格式与数据传输
**通用帧格式**
所有命令和响应均遵循以下帧格式：
| 字段 | 字节数 | 说明 |
| :--- | :--- | :--- |
| 帧头 | 2 | 固定为 `0x55 0xAA` |
| 版本 | 1 | 协议版本号 (通常为 `0x00`) |
| 命令字 | 1 | 指示帧的功能 (如 `0x30`) |
| 数据长度 | 1 | 后续数据的长度 N |
| 数据 | N | 具体的数据内容 |
| 校验和 | 1 | 从帧头开始按字节求和，结果对 256 求余 (Sum % 256) |
**数据传输说明**
* **字节序**：所有大于1个字节的数据均采用 **小端模式 (Little Endian)** 传输（注：与XU316标准协议的大端序不同，请以本协议为准）。
* **浮点数**：遵循 IEEE 754 float 格式。
---
## 2. 协议命令集
### 2.1 命令分类概览
| 命令字 | 命令描述 | 发送方向 | 功能说明 |
| :--- | :--- | :--- | :--- |
| **0x30** | SET_EQ_MODE | 主机→设备 | 切换当前的 EQ 模式 |
| **0x31** | GET_EQ_MODE | 主机→设备 | 获取当前 EQ 模式信息 (模式号、增益、名称) |
| **0x32** | SET_MODE_GAIN_AND_NAME | 主机→设备 | 设置指定模式的整体增益和名称 |
| **0x33** | SET_EQ_PARAMS | 主机→设备 | 发送单个滤波器的参数 (Freq, Q, Gain 等) |
| **0x34** | GET_EQ_PARAMS | 主机→设备 | 读取单个滤波器的参数 |
| **0x35** | RESET_EQ_PARAMS | 主机→设备 | 复位 EQ 参数 (恢复预设) |
---
## 3. 基础功能命令详解
### 3.1 切换 EQ 模式 (0x30)
**主机发送**
| 字节位置 | 长度 | 内容 | 说明 |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | 固定帧头 |
| Version | 1 | `0x00` | 协议版本 |
| Command | 1 | `0x30` | 命令字 |
| Length | 1 | `0x01` | 数据长度 |
| Data | 1 | `Mode` | 模式值<br>0-5: 预设模式<br>6-8: 用户模式<br>9: Bypass |
| Checksum | 1 | `Sum` | 校验和 |
**设备端处理**
* 直接设置当前运行的 EQ 模式。
* 不涉及参数传输或计算。
---
### 3.2 获取当前 EQ 模式信息 (0x31)
**主机发送**
| 字节位置 | 长度 | 内容 | 说明 |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | 固定帧头 |
| Version | 1 | `0x00` | 协议版本 |
| Command | 1 | `0x31` | 命令字 |
| Length | 1 | `0x00` | 无数据 |
| Checksum | 1 | `Sum` | 校验和 |
**设备返回 (响应)**
| 字节位置 | 长度 | 内容 | 说明 |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | 固定帧头 |
| Version | 1 | `0x00` | 协议版本 |
| Command | 1 | `0x31` | 命令字 |
| Length | 1 | `0x15` | 数据长度 (21字节) |
| Data | 1 | `Mode` | 当前模式值 |
| | 4 | `Gain` | 整体增益 (int32, 小端序, 范围 0~-50dB) |
| | 16 | `Name` | 模式名称 (UTF-8 字符串) |
| Checksum | 1 | `Sum` | 校验和 |
---
### 3.3 设置模式整体增益和名称 (0x32)
**主机发送**
| 字节位置 | 长度 | 内容 | 说明 |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | 固定帧头 |
| Version | 1 | `0x00` | 协议版本 |
| Command | 1 | `0x32` | 命令字 |
| Length | 1 | `0x15` | 数据长度 (21字节) |
| Data | 1 | `Mode` | 目标模式值 (0-9) |
| | 4 | `Gain` | 整体增益 (int32, 小端序) |
| | 16 | `Name` | 模式名称 (UTF-8 字符串) |
| Checksum | 1 | `Sum` | 校验和 |
**设备端处理**
* 设置指定模式的增益和名称，自动应用到所有采样率。
---
### 3.4 发送 EQ 参数 (0x33)
**主机发送**
| 字节位置 | 长度 | 内容 | 说明 |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | 固定帧头 |
| Version | 1 | `0x00` | 协议版本 |
| Command | 1 | `0x33` | 命令字 |
| Length | 1 | `0x15` | 数据长度 (21字节) |
| Data | 1 | `Mode` | 模式值 (0-9) |
| | 1 | `Band` | 滤波器索引 (0-7) |
| | 1 | `Type` | 滤波器类型 (见下表) |
| | 4 | `Freq` | 中心频率 Hz (float, 小端序) |
| | 4 | `Q` | Q值 (float, 小端序) |
| | 4 | `BW` | 带宽 Hz (float, 小端序) |
| | 4 | `Gain` | 增益 dB (float, 小端序) |
| Checksum | 1 | `Sum` | 校验和 |
**滤波器类型码**
| 代码 | 类型 | 代码 | 类型 |
| :--- | :--- | :--- | :--- |
| 0x00 | Bypass | 0x06 | 带阻 (Band Reject) |
| 0x01 | 全通 (All Pass) | 0x07 | 陷波 (Notch) |
| 0x02 | 峰值 (Peak) | 0x08 | 恒定Q (Constant Q) |
| 0x03 | 低通 (Low Pass) | 0x09 | 低架 (Low Shelf) |
| 0x04 | 高通 (High Pass) | 0x0A | 高架 (High Shelf) |
| 0x05 | 带通 (Band Pass) | | |
---
### 3.5 读取 EQ 参数 (0x34)
**主机发送**
| 字节位置 | 长度 | 内容 | 说明 |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | 固定帧头 |
| Version | 1 | `0x00` | 协议版本 |
| Command | 1 | `0x34` | 命令字 |
| Length | 1 | `0x02` | 数据长度 |
| Data | 1 | `Mode` | 模式值 (0-9) |
| | 1 | `Band` | 滤波器索引 (0-7) |
| Checksum | 1 | `Sum` | 校验和 |
**设备返回 (响应)**
| 字节位置 | 长度 | 内容 | 说明 |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | 固定帧头 |
| Version | 1 | `0x00` | 协议版本 |
| Command | 1 | `0x34` | 命令字 |
| Length | 1 | `0x15` | 数据长度 (21字节) |
| Data | 1 | `Mode` | 模式值 |
| | 1 | `Band` | 滤波器索引 |
| | 1 | `Type` | 滤波器类型 |
| | 4 | `Freq` | 中心频率 (float, 小端序) |
| | 4 | `Q` | Q值 (float, 小端序) |
| | 4 | `BW` | 带宽 (float, 小端序) |
| | 4 | `Gain` | 增益 (float, 小端序) |
| Checksum | 1 | `Sum` | 校验和 |
---
### 3.6 复位 EQ 参数 (0x35)
**主机发送**
| 字节位置 | 长度 | 内容 | 说明 |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | 固定帧头 |
| Version | 1 | `0x00` | 协议版本 |
| Command | 1 | `0x35` | 命令字 |
| Length | 1 | `0x01` | 数据长度 |
| Data | 1 | `Mode` | 模式号 (0-9)<br>`0xFF` 表示复位所有模式 |
| Checksum | 1 | `Sum` | 校验和 |
**设备返回 (响应)**
| 字节位置 | 长度 | 内容 | 说明 |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | 固定帧头 |
| Version | 1 | `0x00` | 协议版本 |
| Command | 1 | `0x35` | 命令字 |
| Length | 1 | `0x01` | 数据长度 |
| Data | 1 | `Status` | 状态码 (0x00=成功, 0x01=失败) |
| Checksum | 1 | `Sum` | 校验和 |
## 咨询反馈
<details>
<summary>点击展开咨询反馈表单</summary>
--8<-- "common/customer_form.md"
</details>

4
zh/docs/dev_doc/protocols/xu316_zerocode_protocol.md
View File

@@ -754,7 +754,7 @@ sequenceDiagram
版本: 1字节 - 0x03
命令字: 1字节 - 0xF1
数据长度: 1字节 - 2
数据: 2字节 -
数据: 0字节 -
校验和: 1字节 - 从帧头开始按字节求和，结果对256求余
```
@@ -764,7 +764,7 @@ sequenceDiagram
版本: 1字节 - 0x00
命令字: 1字节 - 0xF1
数据长度: 1字节 - 0
数据: 0字节
数据: 3字节
校验和: 1字节 - 从帧头开始按字节求和，结果对256求余
```