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以上，避免设备处理不及时

### 1.4 数据包结构

!!! note "64字节数据包约定"
    - PC发送与设备响应均使用固定长度 64 字节
    - 第0字节固定为 `report_id = 0x01`
    - 第1字节固定为 `sync_header = 0x77`
    - 第2字节为 `cmd_header`（命令头）
    - 其余未使用字节填充 0

## 二、协议命令集 :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 ↔ 设备 |
| 0x91 | GET_EQ_MODE_COUNT | 获取 EQ 模式数量信息 | PC ↔ 设备 |
| 0x92 | SET_AND_SAVE_EQ_MODE | 设置并保存 EQ 模式 | PC ↔ 设备 |
| 0x93 | SET_VOLUME | 设置设备音量级别 | PC → 设备 |
| 0x94 | GET_VOLUME | 获取设备音量级别 | PC ↔ 设备 |
| 0x95 | GET_LED_INFO | 获取 LED 信息（索引与名称） | PC ↔ 设备 |
| 0x96 | SET_LED_SWITCH | 设置 LED 开关 | PC ↔ 设备 |
| 0x97 | GET_LED_SWITCH | 获取 LED 开关状态 | PC ↔ 设备 |
| 0x98 | GET_LED_STATUS | 获取 LED 状态（RGB/显示状态） | PC ↔ 设备 |
| 0x99 | GET_LED_COUNT | 获取 LED 总数 | PC ↔ 设备 |
| 0x9A | GET_UAC_MODE_INFO | 获取 UAC 模式信息（数量与名称） | PC ↔ 设备 |
| 0x9B | SET_UAC_MODE | 设置 UAC 模式 | PC → 设备 |
| 0x9C | GET_CURRENT_UAC_MODE | 获取当前 UAC 模式 | PC ↔ 设备 |
| 0x9D | SET_EQ_ENABLE | 设置 EQ 使能开关 | PC ↔ 设备 |
| 0x9E | GET_EQ_ENABLE | 获取 EQ 使能开关 | PC ↔ 设备 |
| 0x9F | GET_SAMPLE_FORMAT | 获取采样率与格式 | PC ↔ 设备 |
| 0xA0 | SET_GAIN_MODE | 设置增益模式 | PC → 设备 |
| 0xA1 | GET_GAIN_MODE | 获取增益模式 | PC ↔ 设备 |
| 0xA2 | SET_FILTER_MODE | 设置滤波器模式 | PC → 设备 |
| 0xA3 | GET_FILTER_MODE | 获取滤波器模式 | PC ↔ 设备 |
| 0xA4 | SET_GAME_MODE | 设置游戏模式 | PC → 设备 |
| 0xA5 | GET_GAME_MODE | 获取游戏模式 | PC ↔ 设备 |
| 0xA6 | GET_FIRMWARE_VERSION | 获取固件版本号 | PC ↔ 设备 |
| 0xA7 | SET_EQ_BAND_COUNT | 设置 EQ 段数 | PC → 设备 |
| 0xA8 | GET_EQ_BAND_COUNT | 获取 EQ 段数 | PC ↔ 设备 |
| 0xB0 | SET_EX3D_CMD | 发送 EX3D 命令（封装所有 EX3D SET 命令） | PC ↔ 设备 |
| 0xB1 | GET_EX3D_CMD | 读取 EX3D 参数（封装所有 EX3D GET 命令） | PC ↔ 设备 |
| 0x80 | SET_UPSAMPLE | 设置采样率升频开关 | PC → 设备 |
| 0x81 | GET_UPSAMPLE | 获取采样率升频状态 | 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-6 为预设模式，7-9 为用户模式） |
| 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 | 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 | 命令头: 0x8B（回显） |
| 3 | 1 | mode | 当前模式值 |
| 4-7 | 4 | gain | 整体增益（int32, 小端序，范围 -50dB ~ 0dB） |
| 8-23 | 16 | name | 模式名称（UTF-8 字符串） |
| 24-63 | 40 | reserved | 保留字段（填充0） |

**使用说明**:

- 发送 `mode = 0xFF` 时，返回当前激活的 EQ 模式信息
- 发送 `mode = 0-9` 时，返回指定模式的增益与名称（不切换当前模式）

#### 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） |

#### 2.2.8 获取 EQ 模式数量信息（0x91）

**功能说明**: 获取 EQ 模式总数与预定义模式数量（不包含禁用模式）

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x91（回显） |
| 3 | 1 | total | 模式总数（示例：包含 0-9 共 10 个模式） |
| 4 | 1 | preset_total | 预定义模式数量（示例：包含 0-6 共 7 个预设模式） |
| 5-63 | 59 | reserved | 保留字段（填充0） |

#### 2.2.9 设置并保存 EQ 模式（0x92）

**功能说明**: 设置当前 EQ 模式并保存到 Flash，开机时自动恢复

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x92 |
| 3 | 1 | mode | 模式值（文档示例：0-9；0-6预设，7-9用户） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x92（回显） |
| 3 | 1 | status | 状态码（0x00=成功, 0x01=失败） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

#### 2.2.10 设置音量级别（0x93）

**功能说明**: 设置设备输出音量级别

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x93 |
| 3 | 1 | volume | 音量级别（0-60） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

**参数说明**:

- 音量级别范围：0-60（共61级）
- 0：最小音量（约 -127.5dB）
- 60：最大音量（0dB）

#### 2.2.11 获取音量级别（0x94）

**功能说明**: 读取设备当前音量级别

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x94（回显） |
| 3 | 1 | volume | 当前音量级别（0-60） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

#### 2.2.12 获取 LED 信息（0x95）

**功能说明**: 读取 LED 索引与 LED 名称

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x95 |
| 3 | 1 | led_index | LED 索引（0-7） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x95（回显） |
| 3 | 1 | led_index | LED 索引（0-7） |
| 4-19 | 16 | led_name | LED 名称（UTF-8 字符串） |
| 20-63 | 44 | reserved | 保留字段（填充0） |

#### 2.2.13 设置 LED 开关（0x96）

**功能说明**: 设置 LED 开关状态

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x96 |
| 3 | 1 | led_index | LED 索引（0-7） |
| 4 | 1 | onoff | LED 开关（0=OFF, 1=ON） |
| 5-63 | 59 | reserved | 保留字段（填充0） |

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x96（回显） |
| 3 | 1 | status | 状态码（0x00=成功, 0x01=失败） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

#### 2.2.14 获取 LED 开关状态（0x97）

**功能说明**: 读取 LED 开关状态

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x97 |
| 3 | 1 | led_index | LED 索引（0-7） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x97（回显） |
| 3 | 1 | led_index | LED 索引（0-7） |
| 4 | 1 | onoff | LED 开关（0=OFF, 1=ON） |
| 5-63 | 59 | reserved | 保留字段（填充0） |

#### 2.2.15 获取 LED 状态（0x98）

**功能说明**: 读取 LED 的 RGB 颜色与显示状态

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x98 |
| 3 | 1 | led_index | LED 索引（0-7） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x98（回显） |
| 3 | 1 | led_index | LED 索引（0-7） |
| 4 | 1 | r | R 颜色值（0-255） |
| 5 | 1 | g | G 颜色值（0-255） |
| 6 | 1 | b | B 颜色值（0-255） |
| 7 | 1 | led_status | LED 状态（0=熄灭, 1=常亮, 2=慢闪, 3=快闪, 4=呼吸） |
| 8-63 | 56 | reserved | 保留字段（填充0） |

#### 2.2.16 获取 LED 总数（0x99）

**功能说明**: 读取设备支持的 LED 总数

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x99（回显） |
| 3 | 1 | led_total | LED 总数 |
| 4-63 | 60 | reserved | 保留字段（填充0） |

#### 2.2.17 获取 UAC 模式信息（0x9A）

**功能说明**: 读取 UAC 模式数量与名称列表

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x9A（回显） |
| 3 | 1 | count | UAC 模式总数（示例：2） |
| 4-11 | 8 | name0 | 模式0名称（UTF-8，最大8字节） |
| 12-19 | 8 | name1 | 模式1名称（UTF-8，最大8字节） |
| 20-63 | 44 | reserved | 保留字段（填充0） |

#### 2.2.18 设置 UAC 模式（0x9B）

**功能说明**: 设置 UAC 模式（UAC1.0/UAC2.0）

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x9B |
| 3 | 1 | uac_mode | UAC 模式值（0=UAC2.0, 1=UAC1.0） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

**设备端处理**:

- 注意：设备重启后不会返回响应

#### 2.2.19 获取当前 UAC 模式（0x9C）

**功能说明**: 读取当前 UAC 模式与名称

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x9C（回显） |
| 3 | 1 | uac_mode | 当前 UAC 模式值（0=UAC2.0, 1=UAC1.0） |
| 4-11 | 8 | uac_name | 当前 UAC 模式名称（UTF-8，最大8字节） |
| 12-63 | 52 | reserved | 保留字段（填充0） |

#### 2.2.20 设置 EQ 使能开关（0x9D）

**功能说明**: 设置 EQ 使能开关（启用/禁用）

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x9D |
| 3 | 1 | enable | EQ使能（0=OFF, 1=ON） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x9D（回显） |
| 3 | 1 | status | 状态码（0x00=成功, 0x01=失败） |
| 4 | 1 | enable | 当前 EQ 使能状态（0=OFF, 1=ON） |
| 5-63 | 59 | reserved | 保留字段（填充0） |

#### 2.2.21 获取 EQ 使能开关（0x9E）

**功能说明**: 读取 EQ 使能开关状态

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x9E（回显） |
| 3 | 1 | enable | EQ使能（0=OFF, 1=ON） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

#### 2.2.22 获取采样率与格式（0x9F）

**功能说明**: 读取当前采样率与 DSD 模式

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x9F（回显） |
| 3-6 | 4 | sam_freq | 采样率（uint32，小端序，单位 Hz） |
| 7 | 1 | dsd_mode | DSD模式（0=PCM, 1=DOP, 2=Native DSD） |
| 8-63 | 56 | reserved | 保留字段（填充0） |

**自动上报机制**:

- 设备在采样率或 DSD 模式发生变化时，可自动上报对应的 `0x9F` 响应数据包

#### 2.2.23 设置增益模式（0xA0）

**功能说明**: 设置增益模式

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xA0 |
| 3 | 1 | gain_mode | 增益模式（0=低阻, 1=高阻） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

#### 2.2.24 获取增益模式（0xA1）

**功能说明**: 读取设备当前增益模式

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xA1（回显） |
| 3 | 1 | gain_mode | 当前增益模式（0=低阻, 1=高阻） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

#### 2.2.25 设置滤波器模式（0xA2）

**功能说明**: 设置滤波器模式（0-7，共8种）

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xA2 |
| 3 | 1 | filter_mode | 滤波器模式值（0-7） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

**滤波器模式值定义**:

- 0: Minimum Phase filter (default)
- 1: Linear Phase Apodizing Fast Roll-off filter
- 2: Linear phase fast roll-off filter
- 3: Linear Phase Fast Roll-off low-ripple filter
- 4: Linear phase slow roll-off filter
- 5: Minimum phase fast roll-off filter
- 6: Minimum phase slow roll-off filter
- 7: Minimum Phase Fast Roll-Off Low Dispersion

#### 2.2.26 获取滤波器模式（0xA3）

**功能说明**: 读取设备当前滤波器模式

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xA3（回显） |
| 3 | 1 | filter_mode | 当前滤波器模式（0-7） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

#### 2.2.27 设置游戏模式（0xA4）

**功能说明**: 设置游戏模式

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xA4 |
| 3 | 1 | game_mode | 游戏模式（0=无音效, 1=FPS, 2=虚拟7.1） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

#### 2.2.28 获取游戏模式（0xA5）

**功能说明**: 读取设备当前游戏模式

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xA5（回显） |
| 3 | 1 | game_mode | 当前游戏模式（0=无音效, 1=FPS, 2=虚拟7.1） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

#### 2.2.29 获取固件版本号（0xA6）

**功能说明**: 读取设备固件版本号（BCD 格式）

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xA6（回显） |
| 3 | 1 | major_bcd | 主版本号（BCD，例如 0x01 表示 1） |
| 4 | 1 | minor_bcd | 次版本号（BCD，例如 0x00 表示 0） |
| 5 | 1 | patch_bcd | 修订版本号（BCD，例如 0x0C 表示 12） |
| 6-63 | 58 | reserved | 保留字段（填充0） |

**版本号格式说明**:

- 版本号采用 BCD（Binary Coded Decimal）格式
- 例如：`0x01 0x00 0x0C` 表示版本 `1.0.12`

#### 2.2.30 设置 EQ 段数（0xA7）

**功能说明**: 设置 EQ 段数，支持 8/16/24/32 段动态切换，控制参与处理的 DSP 核数

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xA7 |
| 3 | 1 | band_count | EQ 段数（8=仅 Core0, 16=Core0+Core1, 24=Core0+Core1+Core2, 32=全部 4 核） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

**设备端处理**:

- 仅接受 8、16、24、32 四个有效值，其他值拒绝
- 设置后保存到 Flash（独立文件 eq_band_cnt），开机时自动恢复

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xA7（回显） |
| 3 | 1 | status | 状态码（0x00=成功, 0x01=失败） |
| 4 | 1 | band_count | 当前 EQ 段数（8/16/24/32） |
| 5-63 | 59 | reserved | 保留字段（填充0） |

#### 2.2.31 获取 EQ 段数（0xA8）

**功能说明**: 读取当前 EQ 段数

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xA8（回显） |
| 3 | 1 | band_count | 当前 EQ 段数（8/16/24/32） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

#### 2.2.32 发送 EX3D 命令（0xB0）

**功能说明**: 发送 EX3D 设置命令，封装所有 EX3D SET 命令

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xB0 |
| 3-6 | 4 | ex3d_cmd | EX3D 命令码（包含 SET 标志，参考 ex3d_protocol.md） |
| 7-10 | 4 | param1 | 参数1（根据 EX3D 命令不同而不同） |
| 11-14 | 4 | param2 | 参数2（根据 EX3D 命令不同而不同） |
| 15-18 | 4 | param3 | 参数3（根据 EX3D 命令不同而不同） |
| 19-63 | 45 | reserved | 保留字段或扩展参数 |

**EX3D 命令码说明**:

- 基础命令码范围: 0x80-0x94
- SET 命令格式: `基础命令码 & ~0x0100`（清除第 9 位）
- 支持的 SET 命令：
  - 0x81: CMD_OPEN（打开 EX3D）
  - 0x82: CMD_ONOFF（设置 EX3D 开关）
  - 0x83: CMD_ANGLE（设置角度）
  - 0x84: CMD_SOUND_FIELD（设置声场模式）
  - 0x85: CMD_MUTE（设置静音）
  - 0x86: CMD_ON_GAIN（设置开启增益）
  - 0x87: CMD_LMT_THRESHOLD（设置限制器阈值）
  - 0x88: CMD_UPMIX（设置上混）
  - 0x89: CMD_LFE（设置 LFE 增益）
  - 0x8A: CMD_OFF_GAIN（设置关闭增益）
  - 0x8E: CMD_LMT_ATTACKK_TIME（设置限制器攻击时间）
  - 0x8F: CMD_LMT_RELEASE_TIME（设置限制器释放时间）
  - 0x90: CMD_TEST_CANCEL（取消测试）
  - 0x91: CMD_TEST_STEP（测试步骤）
  - 0x92: CMD_TEST_ROTATE（测试旋转）
  - 0x93: CMD_EXPAND_GAIN（设置扩展增益）
  - 0x94: CMD_REDUCE_GAIN（设置减少增益）

**设备端处理**:

- 解析 EX3D 命令码，提取基础命令码和参数
- 调用相应的 EX3D 处理函数（hid_receive_task_in_c）
- 根据命令类型执行相应的设置操作

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xB0（回显） |
| 3 | 1 | status | 状态码（0x00=成功, 0x01=失败） |
| 4-7 | 4 | ex3d_cmd | EX3D 命令码（回显） |
| 8-11 | 4 | result | 返回值（某些命令返回 0xFFFFFFFF 表示参数错误） |
| 12-63 | 52 | reserved | 保留字段 |

**使用说明**:

- 该命令用于统一封装所有 EX3D 设置命令
- 参数格式与原始 EX3D 协议保持一致
- 详细的 EX3D 命令说明请参考 ex3d_protocol.md 文档

#### 2.2.33 读取 EX3D 命令（0xB1）

**功能说明**: 读取 EX3D 参数，封装所有 EX3D GET 命令

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xB1 |
| 3-6 | 4 | ex3d_cmd | EX3D 命令码（包含 GET 标志，参考 ex3d_protocol.md） |
| 7-10 | 4 | param1 | 参数1（根据 EX3D 命令不同而不同，如通道号、索引等） |
| 11-63 | 53 | reserved | 保留字段或扩展参数 |

**EX3D 命令码说明**:

- 基础命令码范围: 0x80-0x94
- GET 命令格式: `基础命令码 | 0x0100`（设置第 9 位）
- 支持的 GET 命令：
  - 0x180: CMD_CH_NUM（获取通道数量）
  - 0x182: CMD_ONOFF（获取 EX3D 开关）
  - 0x183: CMD_ANGLE（获取角度）
  - 0x184: CMD_SOUND_FIELD（获取声场模式）
  - 0x185: CMD_MUTE（获取静音）
  - 0x186: CMD_ON_GAIN（获取开启增益）
  - 0x187: CMD_LMT_THRESHOLD（获取限制器阈值）
  - 0x188: CMD_UPMIX（获取上混）
  - 0x189: CMD_LFE（获取 LFE 增益）
  - 0x18A: CMD_OFF_GAIN（获取关闭增益）
  - 0x18B: CMD_SOUND_FIELD_NUM（获取声场模式数量）
  - 0x18C: CMD_SOUND_FIELD_NAME（获取声场模式名称）
  - 0x18D: CMD_LEVEL（获取电平）
  - 0x18E: CMD_LMT_ATTACKK_TIME（获取限制器攻击时间）
  - 0x18F: CMD_LMT_RELEASE_TIME（获取限制器释放时间）
  - 0x193: CMD_EXPAND_GAIN（获取扩展增益）
  - 0x194: CMD_REDUCE_GAIN（获取减少增益）

**设备端处理**:

- 解析 EX3D 命令码，提取基础命令码和参数
- 调用相应的 EX3D 处理函数（hid_receive_task_in_c）
- 返回当前参数值

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0xB1（回显） |
| 3-6 | 4 | ex3d_cmd | EX3D 命令码（回显） |
| 7-10 | 4 | result1 | 返回值1（根据命令不同而不同） |
| 11-14 | 4 | result2 | 返回值2（某些命令需要多个返回值，如角度、多通道数据等） |
| 15-18 | 4 | result3 | 返回值3（扩展返回值，如多通道数据） |
| 19-63 | 45 | reserved | 其他返回值或填充（最多可返回 14 个 uint32 值，总长度不超过 63 字节） |

**返回值说明**:

- 返回值数量和格式取决于具体的 EX3D 命令
- 单值命令：返回 1 个 uint32 值
- 多值命令（如角度、多通道数据）：返回多个 uint32 值
- 字符串命令（如声场名称）：先返回长度（uint32），然后返回字符串数据
- 详细的返回值格式请参考 ex3d_protocol.md 文档

**使用说明**:

- 该命令用于统一封装所有 EX3D 读取命令
- 参数格式与原始 EX3D 协议保持一致
- 详细的 EX3D 命令说明请参考 ex3d_protocol.md 文档

#### 2.2.34 设置采样率升频（0x80）

**功能说明**: 设置设备采样率升频开关

**请求格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x80 |
| 3 | 1 | upsample | 升频状态（0=禁用升频, 1=使能升频） |
| 4-63 | 60 | reserved | 保留字段（填充0） |

**参数说明**:

- 升频状态：0=禁用升频，1=使能升频

**返回值**:

无直接返回值。如需确认升频状态，请使用 GET_UPSAMPLE (0x81) 命令读取。

#### 2.2.35 获取采样率升频（0x81）

**功能说明**: 读取设备当前采样率升频状态

**请求格式（64 字节）**:

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

**响应格式（64 字节）**:

| 偏移 | 长度 | 字段名 | 描述 |
|:----:|:----:|:------:|:----:|
| 0 | 1 | report_id | 固定为 0x01 |
| 1 | 1 | sync_header | 同步头: 0x77 |
| 2 | 1 | cmd_header | 命令头: 0x81（回显） |
| 3 | 1 | upsample | 当前升频状态（0=禁用, 1=使能） |
| 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-9 共 10 个模式（模式含义以固件定义为准）
    - **采样率支持**: 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 | JAZZ | 爵士音乐优化 | 预设模式 |
| 1 | POP | 流行音乐优化 | 预设模式 |
| 2 | ROCK | 摇滚音乐优化 | 预设模式 |
| 3 | ClASIC | 古典音乐优化 | 预设模式 |
| 4 | R&B | 节奏音乐优化 | 预设模式 |
| 5 | 3A Game | 3A游戏音乐优化 | 预设模式 |
| 6 |   FPS    | FPS游戏音乐优化 | 预设模式 |
| 7 |  User 1  | 用户自定义模式1 | 用户模式 |
| 8 |  User 2  | 用户自定义模式2 | 用户模式 |
| 9 |  User 3  | 用户自定义模式3 | 用户模式 |

!!! info "模式特性说明"
    - **预设模式**: 出厂预设，不可修改，针对特定音乐类型优化
    - **用户模式**: 支持用户自定义参数，可保存和重置

## 五、关键特性 :material-star:

### 5.1 设备端系数计算

- 主机只发送参数（`freq`/`q`/`bw`/`gain`）
- 设备端根据参数实时计算滤波器系数

### 5.2 参数格式

- 浮点参数：`freq`、`q`、`bw`、`gain` 使用 IEEE 754 `float`（小端序）
- 整体增益：`int32`（小端序，范围 `-50dB ~ 0dB`）

### 5.3 错误处理

- 数据包长度检查
- 同步头验证
- 参数范围检查
- 滤波器索引边界检查

### 5.4 模式管理

- 支持 EQ 模式切换与保存
- 模式切换后建议通过读取命令进行状态同步

## 六、注意事项 :material-alert:

1. **时序要求**: 发送参数后需要等待设备处理完成再发送下一条命令
2. **数据完整性**: 所有8个滤波器的参数都需要发送，即使某些滤波器未使用
3. **模式同步**: 设置模式后建议调用读取模式确保数据同步
4. **错误恢复**: 通信失败时需要重新建立连接并重试
5. **参数验证**: 设备端会验证参数范围，超出范围的值会被限制或拒绝

---

## 咨询反馈

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

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

</details>