diff --git a/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md b/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md new file mode 100644 index 0000000..9f98be4 --- /dev/null +++ b/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md @@ -0,0 +1,339 @@ +--- +title: XMOS EQ HID 通信协议规范 +status: new +description: XMOS EQ HID 通信协议规范文档 +authors: + - admin +tags: + - 协议 + - XMOS + - EQ + - HID +search: + boost: 2 +--- + +# XMOS EQ HID 通信协议规范 + +--8<-- "common/phaten_xmos_support_img.md" + +## 协议概述 :material-file-document-outline: + +!!! abstract "功能定位与范围" + 本文档详细描述了XMOS EQ HID设备与PC端GUI软件之间的通信协议。该协议提供了EQ模式控制、参数设置和设备信息获取的完整功能集。 + +## 一、协议基础规范 :material-connection: + +### 1.1 底层通信协议 + +**基于USB HID (Human Interface Device) 协议** + +| 参数 | 值 | +|:---------------:|:--------------------:| +| 传输方式 | USB HID | +| 数据包大小 | 64字节(包含1字节Report ID 0x01) | +| 有效数据 | 63字节 | +| 字节序 | 小端序(Little Endian) | +| 同步头 | 0x77 (固定第一个字节) | + +### 1.2 HID设备识别 + +| 参数 | 值 | 说明 | +|:----------:|:--------:|:-----------------------------------------:| +| Usage Page | 0xff82 或 0xff83 | HID设备类型标识 | +| Report ID | 0x01 | 发送时作为第一个字节 | +| 传输模式 | 非阻塞模式 | 避免GUI卡顿 | + +### 1.3 通信机制 + +!!! warning "数据传输说明" + - 所有数据均采用小端序(Little Endian)传输 + - 同步头0x77必须作为每个数据包的第一个字节 + - 建议命令间隔5ms以上,避免设备处理不及时 + +## 二、协议命令集 :material-code-tags: + +### 2.1 命令分类概览 + +!!! note "命令使用说明" + 1. 所有命令必须包含同步头0x77作为第一个字节 + 2. 数据包总长度固定为63字节(不含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 ↔ 设备 | + +### 2.2 详细命令格式 + +#### 2.2.1 读取EQ模式(0x8B) + +**功能说明**: 读取当前设备EQ模式值 + +**请求格式(63字节)**: + +| 偏移 | 长度 | 字段名 | 描述 | +|:----:|:----:|:------:|:----:| +| 0 | 1 | sync_header | 同步头: 0x77 | +| 1 | 1 | cmd_header | 命令头: 0x8B | +| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) | +| 6 | 1 | mode | 查询的模式值 | +| 7-62 | 56 | reserved | 保留字段(填充0) | + +#### 2.2.2 设置EQ模式(0x8C) + +**功能说明**: 正式的模式设置命令 + +**数据包格式(63字节)**: + +| 偏移 | 长度 | 字段名 | 描述 | +|:----:|:----:|:------:|:----:| +| 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) | + +#### 2.2.3 设置EQ参数(0x8D) + +**功能说明**: 发送单个滤波器的完整参数和系数 + +**数据包格式(63字节)**: + +| 偏移 | 长度 | 字段名 | 描述 | +|:----:|:----:|:------:|:----:| +| 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) | + +**滤波器类型码定义**: + +| 类型码 | 滤波器类型 | 英文名称 | +|:------:|:----------:|:--------:| +| 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 | + +**数值格式定义**: + +!!! info "Q15.15格式说明" + - **Q15.15格式**: 16位整数部分 + 16位小数部分 + - 例如: Q值1.414 → 0x00016A09 + +#### 2.2.4 读取EQ参数(0x8E) + +**功能说明**: 读取指定滤波器的参数 + +**请求格式(63字节)**: + +| 偏移 | 长度 | 字段名 | 描述 | +|:----:|:----:|:------:|:----:| +| 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) | + +**响应格式(63字节)**: + +| 偏移 | 长度 | 字段名 | 描述 | +|:----:|:----:|:------:|:----:| +| 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) | + +#### 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) + +**功能说明**: 获取设备的基本标识信息 + +**请求格式(63字节)**: + +| 偏移 | 长度 | 字段名 | 描述 | +|:----:|:----:|:------:|:----:| +| 0 | 1 | sync_header | 同步头: 0x77 | +| 1 | 1 | cmd_header | 命令头: 0x92 | +| 2 | 4 | sample_rate | 采样率 (Hz, 32位小端) | +| 6-62 | 57 | reserved | 保留字段(填充0) | + +**响应格式(63字节)**: + +| 偏移 | 长度 | 字段名 | 描述 | +|:----:|:----:|:------:|:----:| +| 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) | + +## 三、数据流程和时序 :material-timeline-clock: + +### 3.1 典型操作流程 + +#### 3.1.1 模式切换流程 +1. GUI发送SET_EQ_MODE命令 (0x8C) +2. 设备更新内部模式状态 +3. GUI发送READ_EQ_MODE命令 (0x8B) 确认 +4. 设备响应当前模式状态 + +#### 3.1.2 参数设置流程 +1. GUI发送SET_EQ_MODE命令切换到相应模式 (0x8C) +2. 逐个发送8个滤波器的命令 (0x8D) +3. 设备接收并更新内部参数缓存 +4. 可选: 发送READ_EQ_PARAMS命令验证参数 + +#### 3.1.3 参数读取流程 +1. GUI发送SET_EQ_MODE命令切换到相应模式 (0x8C) +2. GUI发送READ_EQ_PARAMS请求 (0x8E) +3. 设备准备响应数据 +4. GUI读取响应 + +### 3.2 时序要求与约束 + +!!! warning "时序要求" + - **命令间隔**: 建议5ms以上 + - **读取延时**: 发送读取请求后等待100ms + - **模式切换**: 完成后等待设备内部状态稳定 + +!!! danger "协议限制和约束" + **硬件限制** + + - **滤波器数量**: 固定8个滤波器(MAX_EQ_BANDS = 8) + - **模式数量**: 支持8个EQ模式(0-5为预设模式,6-7为用户模式)+ 1个禁用模式(8) + - **采样率支持**: 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位有符号整数 | + +## 四、预设模式定义 :material-equalizer: + +### 4.1 模式分类 + +| 模式索引 | 模式名称 | 用途描述 | 类型 | +|:--------:|:--------:|:--------:|:----:| +| 0 | Flat/Linear | 平坦响应,无EQ处理 | 预设模式 | +| 1 | Pop/Rock | 流行摇滚音乐优化 | 预设模式 | +| 2 | Classical | 古典音乐优化 | 预设模式 | +| 3 | Jazz | 爵士音乐优化 | 预设模式 | +| 4 | Vocal | 人声增强 | 预设模式 | +| 5 | Bass Boost | 低音增强 | 预设模式 | +| 6 | User 1 | 用户自定义模式1 | 用户模式 | +| 7 | User 2 | 用户自定义模式2 | 用户模式 | +| 8 | Disabled | EQ功能禁用 | 特殊模式 | + +!!! info "模式特性说明" + - **预设模式**: 出厂预设,不可修改,针对特定音乐类型优化 + - **用户模式**: 支持用户自定义参数,可保存和重置 + - **禁用模式**: 完全关闭EQ处理,音频信号直通 + +--- + +## 咨询反馈 + +
+点击展开咨询反馈表单 + +--8<-- "common/customer_form.md" + +
+ diff --git a/zh/mkdocs.yml b/zh/mkdocs.yml index 1b72800..ef336a1 100644 --- a/zh/mkdocs.yml +++ b/zh/mkdocs.yml @@ -272,6 +272,7 @@ nav: - 通信协议: - dev_doc/protocols/index.md - XU316 USB HiFi解码器免开发产品配置协议: dev_doc/protocols/xu316_zerocode_protocol.md + - XMOS EQ HID 通信协议规范: dev_doc/protocols/XMOS_EQ_HID_Protocol.md - 开发SDK与示例: - dev_doc/sdk_examples/index.md - A316免开发固件MCU开发指南: