ftyyda/phaten-audio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
00f42eab809221a823bf6f706229938e1fcbc687
phaten-audio/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
PhatenIoT-yan 00f42eab80 update
2025-12-25 14:21:26 +08:00

12 KiB
Raw Blame History

title, description, keywords, authors, tags, search
title description keywords authors tags search
XMOS EQ HID 通信协议规范 适用于免开发固件系列设备的 EQ HID 控制协议，包含报文结构、命令集与字段说明，用于模式切换、参数读写与设备信息获取。 EQ, HID, 控制协议, 命令集, USB HID, XU316,免开发固件, Phaten Audio
admin
协议
XMOS
EQ
HID
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字节，Report ID 为第0字节）

1.2 HID设备识别

参数 值 说明
Usage Page 0xff82 或 0xff83 HID设备类型标识
Report ID 0x01 发送时作为第一个字节（第0字节）
传输模式 非阻塞模式 避免GUI卡顿

1.3 通信机制

!!! warning "数据传输说明" - 所有数据均采用小端序（Little Endian）传输 - 同步头 0x77 固定在第 1 字节（第 0 字节为 Report ID = 0x01） - 建议命令间隔5ms以上，避免设备处理不及时

二、协议命令集 :material-code-tags:

2.1 命令分类概览

!!! note "命令使用说明" 1. 所有命令必须包含 Report ID 0x01（第0字节）与同步头 0x77（第1字节） 2. 数据包总长度固定为 64 字节（含 Report ID） 3. 未使用的字节必须填充为0

2.1.1 命令头定义

命令头 命令名称 功能描述 方向
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 模式（0x8A）

功能说明: 切换当前的 EQ 模式

请求格式（64 字节）:

偏移 长度 字段名 描述
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 模式信息（0x8B）

功能说明: 获取当前模式值、整体增益与模式名称

请求格式（64 字节）:

偏移 长度 字段名 描述
0 1 report_id 固定为 0x01
1 1 sync_header 同步头: 0x77
2 1 cmd_header 命令头: 0x8B
3-63 61 reserved 保留字段（填充0）

响应格式（64 字节）:

偏移 长度 字段名 描述
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）

功能说明: 设置目标模式的整体增益和名称

请求格式（64 字节）:

偏移 长度 字段名 描述
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 参数（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）

功能说明: 读取指定滤波器的参数

请求格式（64 字节）:

偏移 长度 字段名 描述
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）

响应格式（64 字节）:

偏移 长度 字段名 描述
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.6 获取设备信息（0x8F）

功能说明: 获取设备的基本标识信息

请求格式（64 字节）:

偏移 长度 字段名 描述
0 1 report_id 固定为 0x01
1 1 sync_header 同步头: 0x77
2 1 cmd_header 命令头: 0x8F
3-63 61 reserved 保留字段（填充0）

响应格式（64 字节）:

偏移 长度 字段名 描述
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命令 (0x8A)
  2. 设备更新内部模式状态
  3. GUI发送GET_EQ_MODE命令 (0x8B) 确认
  4. 设备响应当前模式状态

3.1.2 参数设置流程

  1. GUI发送SET_EQ_MODE命令切换到相应模式 (0x8A)
  2. 逐个发送8个滤波器的命令 (0x8D)
  3. 设备接收并更新内部参数缓存
  4. 可选: 发送GET_EQ_PARAMS命令验证参数 (0x8E)

3.1.3 参数读取流程

  1. GUI发送SET_EQ_MODE命令切换到相应模式 (0x8A)
  2. GUI发送GET_EQ_PARAMS请求 (0x8E)
  3. 设备准备响应数据
  4. GUI读取响应

3.2 时序要求与约束

!!! warning "时序要求" - 命令间隔: 建议5ms以上 - 读取延时: 发送读取请求后等待100ms - 模式切换: 完成后等待设备内部状态稳定

!!! danger "协议限制和约束" 硬件限制

- **滤波器数量**: 固定 8 个滤波器（MAX_EQ_BANDS = 8）
- **模式数量**: 0-5 为预设模式，6-8 为用户模式，9 为 Bypass 模式
- **采样率支持**: 44.1kHz, 48kHz, 88.2kHz, 96kHz, 176.4kHz, 192kHz（设备能力，与协议字段独立）

**参数范围**

| 参数 | 范围 | 格式 |
|:----:|:----:|:----:|
| 中心频率 (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:

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 User 3 用户自定义模式3 用户模式
9 Bypass EQ 功能旁路 特殊模式

!!! info "模式特性说明" - 预设模式: 出厂预设，不可修改，针对特定音乐类型优化 - 用户模式: 支持用户自定义参数，可保存和重置 - 旁路模式: 完全关闭 EQ 处理，音频信号直通（Bypass）

咨询反馈

点击展开咨询反馈表单

--8<-- "common/customer_form.md"

Reference in New Issue View Git Blame Copy Permalink