phaten-audio/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md

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

---

## 咨询反馈

<details>
<summary>点击展开咨询反馈表单</summary>

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

</details>