update hid

2026-03-27 11:18:00 +08:00
parent e469ee0144
commit b745a7636c
2 changed files with 179 additions and 22 deletions
--- a/en/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
+++ b/en/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
@@ -51,6 +51,15 @@ search:
    - Sync header 0x77 is fixed at byte 1 (byte 0 is Report ID = 0x01)
    - Recommend minimum 5ms interval between commands to avoid device processing delays

+### 1.4 Data Packet Structure
+
+!!! note "64-Byte Packet Convention"
+    - Both PC requests and device responses use fixed-length 64-byte packets
+    - Byte 0 is fixed as `report_id = 0x01`
+    - Byte 1 is fixed as `sync_header = 0x77`
+    - Byte 2 is `cmd_header` (command header)
+    - All unused bytes must be padded with 0
+
 ## 2. Protocol Command Set :material-code-tags:

 ### 2.1 Command Classification Overview
@@ -90,12 +99,14 @@ search:
 | 0xA1 | GET_GAIN_MODE | Get gain mode | PC ↔ Device |
 | 0xA2 | SET_FILTER_MODE | Set filter mode | PC → Device |
 | 0xA3 | GET_FILTER_MODE | Get filter mode | PC ↔ Device |
-| 0xA4 | SET_GAME_MODE | Set game mode | PC ↔ Device |
+| 0xA4 | SET_GAME_MODE | Set game mode | PC → Device |
 | 0xA5 | GET_GAME_MODE | Get game mode | PC ↔ Device |
 | 0xA6 | GET_FIRMWARE_VERSION | Get firmware version | PC ↔ Device |
+| 0xA7 | SET_EQ_BAND_COUNT | Set EQ band count | PC → Device |
+| 0xA8 | GET_EQ_BAND_COUNT | Get EQ band count | PC ↔ Device |
 | 0xB0 | SET_EX3D_CMD | Set EX3D command | PC ↔ Device |
 | 0xB1 | GET_EX3D_CMD | Get EX3D command | PC ↔ Device |
-| 0x80 | SET_UPSAMPLE | Set sampling rate upsampling | PC ↔ Device |
+| 0x80 | SET_UPSAMPLE | Set sampling rate upsampling | PC → Device |
 | 0x81 | GET_UPSAMPLE | Get sampling rate upsampling status | PC ↔ Device |

 ### 2.2 Detailed Command Formats
@@ -111,7 +122,7 @@ search:
 | 0 | 1 | report_id | Fixed value: 0x01 |
 | 1 | 1 | sync_header | Sync header: 0x77 |
 | 2 | 1 | cmd_header | Command header: 0x8A |
-| 3 | 1 | mode | Mode value (0-6: presets, 7-9: user, 9: Bypass) |
+| 3 | 1 | mode | Mode value (0-6: preset modes, 7-9: user modes) |
 | 4-63 | 60 | reserved | Reserved fields (fill with 0) |

 #### 2.2.2 Get Current EQ Mode Information (0x8B)
@@ -125,7 +136,8 @@ search:
 | 0 | 1 | report_id | Fixed value: 0x01 |
 | 1 | 1 | sync_header | Sync header: 0x77 |
 | 2 | 1 | cmd_header | Command header: 0x8B |
-| 3-63 | 61 | reserved | Reserved fields (fill with 0) |
+| 3 | 1 | mode | Mode value (0-9: specified mode; 0xFF: get current mode info) |
+| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

 **Response Format (64 bytes)**:

@@ -139,6 +151,11 @@ search:
 | 8-23 | 16 | name | Mode name (UTF-8 string) |
 | 24-63 | 40 | reserved | Reserved fields (fill with 0) |

+**Usage Notes**:
+
+- Send `mode = 0xFF` to return the currently active EQ mode information
+- Send `mode = 0-9` to return the specified mode gain and name (does not switch the current mode)
+
 #### 2.2.3 Set Mode Overall Gain and Name (0x8C)

 **Function**: Set overall gain and name for target mode
@@ -782,7 +799,60 @@ search:
 - Version uses BCD (Binary Coded Decimal) format
 - Example: `0x01 0x00 0x0C` represents version `1.0.12`

-#### 2.2.30 Set EX3D Command (0xB0)
+#### 2.2.30 Set EQ Band Count (0xA7)
+
+**Function**: Set EQ band count. Supports dynamic switching among 8/16/24/32 bands to control how many DSP cores participate in processing.
+
+**Request Format (64 bytes)**:
+
+| Offset | Length | Field Name | Description |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | Fixed value: 0x01 |
+| 1 | 1 | sync_header | Sync header: 0x77 |
+| 2 | 1 | cmd_header | Command header: 0xA7 |
+| 3 | 1 | band_count | EQ band count (8=Core0 only, 16=Core0+Core1, 24=Core0+Core1+Core2, 32=all 4 cores) |
+| 4-63 | 60 | reserved | Reserved fields (fill with 0) |
+
+**Device Processing**:
+
+- Only accepts 8, 16, 24, 32; other values are rejected
+- Saved to Flash (independent file `eq_band_cnt`) and restored on power-up
+
+**Response Format (64 bytes)**:
+
+| Offset | Length | Field Name | Description |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | Fixed value: 0x01 |
+| 1 | 1 | sync_header | Sync header: 0x77 |
+| 2 | 1 | cmd_header | Command header: 0xA7 (echo) |
+| 3 | 1 | status | Status code (0x00=success, 0x01=failure) |
+| 4 | 1 | band_count | Current EQ band count (8/16/24/32) |
+| 5-63 | 59 | reserved | Reserved fields (fill with 0) |
+
+#### 2.2.31 Get EQ Band Count (0xA8)
+
+**Function**: Read current EQ band count
+
+**Request Format (64 bytes)**:
+
+| Offset | Length | Field Name | Description |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | Fixed value: 0x01 |
+| 1 | 1 | sync_header | Sync header: 0x77 |
+| 2 | 1 | cmd_header | Command header: 0xA8 |
+| 3-63 | 61 | reserved | Reserved fields (fill with 0) |
+
+**Response Format (64 bytes)**:
+
+| Offset | Length | Field Name | Description |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | Fixed value: 0x01 |
+| 1 | 1 | sync_header | Sync header: 0x77 |
+| 2 | 1 | cmd_header | Command header: 0xA8 (echo) |
+| 3 | 1 | band_count | Current EQ band count (8/16/24/32) |
+| 4-63 | 60 | reserved | Reserved fields (fill with 0) |
+
+#### 2.2.32 Set EX3D Command (0xB0)

 **Function**: Send EX3D set command, encapsulating all EX3D SET commands

@@ -846,7 +916,7 @@ search:
 - Parameter format consistent with original EX3D protocol
 - For detailed EX3D command descriptions, refer to ex3d_protocol.md

-#### 2.2.31 Get EX3D Command (0xB1)
+#### 2.2.33 Get EX3D Command (0xB1)

 **Function**: Read EX3D parameters, encapsulating all EX3D GET commands

@@ -917,7 +987,7 @@ search:
 - Parameter format consistent with original EX3D protocol
 - For detailed EX3D command descriptions, refer to ex3d_protocol.md

-#### 2.2.32 Set Sampling Rate Upsampling (0x80)
+#### 2.2.34 Set Sampling Rate Upsampling (0x80)

 **Function**: Set device sampling rate upsampling switch

@@ -939,7 +1009,7 @@ search:

 No direct return value. To confirm upsampling status, use GET_UPSAMPLE (0x81).

-#### 2.2.33 Get Sampling Rate Upsampling (0x81)
+#### 2.2.35 Get Sampling Rate Upsampling (0x81)

 **Function**: Read device current sampling rate upsampling status

@@ -995,7 +1065,7 @@ No direct return value. To confirm upsampling status, use GET_UPSAMPLE (0x81).
    **Hardware Limitations**

    - **Filter Count**: Fixed at 8 filters (MAX_EQ_BANDS = 8)
-    - **Mode Count**: 0-6 are preset modes, 7-9 are user modes, 9 is Bypass mode (Note: Mode 9 is typically Bypass, check specific device config)
+    - **Mode Count**: Supports 10 modes (0-9). Mode meanings are defined by firmware.
    - **Sample Rate Support**: 44.1kHz, 48kHz, 88.2kHz, 96kHz, 176.4kHz, 192kHz (device capability, independent of protocol fields)

    **Parameter Ranges**
@@ -1014,22 +1084,54 @@ No direct return value. To confirm upsampling status, use GET_UPSAMPLE (0x81).

 | Mode Index | Mode Name | Description | Type |
 |:--------:|:--------:|:--------:|:----:|
-| 0 | Flat/Linear | Flat response, no EQ processing | Preset Mode |
-| 1 | Pop/Rock | Optimized for pop/rock music | Preset Mode |
-| 2 | Classical | Optimized for classical music | Preset Mode |
-| 3 | Jazz | Optimized for jazz music | Preset Mode |
-| 4 | Vocal | Vocal enhancement | Preset Mode |
-| 5 | Bass Boost | Bass enhancement | Preset Mode |
-| 6 | 3D Game | Optimized for gaming spatial audio | Preset Mode |
+| 0 | JAZZ | Jazz music optimization | Preset Mode |
+| 1 | POP | Pop music optimization | Preset Mode |
+| 2 | ROCK | Rock music optimization | Preset Mode |
+| 3 | ClASIC | Classical music optimization | Preset Mode |
+| 4 | R&B | Rhythm & blues optimization | Preset Mode |
+| 5 | 3A Game | AAA game audio optimization | Preset Mode |
+| 6 | FPS | FPS game audio optimization | Preset Mode |
 | 7 | User 1 | User-defined mode 1 | User Mode |
 | 8 | User 2 | User-defined mode 2 | User Mode |
 | 9 | User 3 | User-defined mode 3 | User Mode |
-| 10 | Bypass | EQ function bypass | Special Mode |

 !!! info "Mode Characteristics"
    - **Preset Modes**: Factory presets, non-modifiable, optimized for specific music genres
    - **User Modes**: Support user-defined parameters, can be saved and reset
-    - **Bypass Mode**: Completely disables EQ processing, audio signal passes through (Bypass)
+
+---
+
+## 5. Key Features :material-star:
+
+### 5.1 Device-Side Coefficient Calculation
+
+- The host only sends parameters (`freq`/`q`/`bw`/`gain`)
+- The device calculates filter coefficients in real time based on the parameters
+
+### 5.2 Parameter Formats
+
+- Floating-point parameters: `freq`, `q`, `bw`, `gain` use IEEE 754 `float` (Little Endian)
+- Overall gain: `int32` (Little Endian, range `-50dB ~ 0dB`)
+
+### 5.3 Error Handling
+
+- Packet length validation
+- Sync header validation
+- Parameter range validation
+- Filter index boundary validation
+
+### 5.4 Mode Management
+
+- Supports EQ mode switching and saving
+- After switching modes, it is recommended to read back state for synchronization
+
+## 6. Notes :material-alert:
+
+1. **Timing Requirements**: After sending parameters, wait for device processing before sending the next command
+2. **Data Completeness**: All 8 filters’ parameters should be sent, even if some filters are unused
+3. **Mode Synchronization**: After setting a mode, call the read-mode command to ensure synchronization
+4. **Error Recovery**: If communication fails, reconnect and retry
+5. **Parameter Validation**: Device validates parameter ranges; out-of-range values are clamped or rejected

 ---

--- a/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
+++ b/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
@@ -102,6 +102,8 @@ search:
 | 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 → 设备 |
@@ -801,7 +803,60 @@ search:
 - 版本号采用 BCD（Binary Coded Decimal）格式
 - 例如：`0x01 0x00 0x0C` 表示版本 `1.0.12`

-#### 2.2.30 发送 EX3D 命令（0xB0）
+#### 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 命令

@@ -865,7 +920,7 @@ search:
 - 参数格式与原始 EX3D 协议保持一致
 - 详细的 EX3D 命令说明请参考 ex3d_protocol.md 文档

-#### 2.2.31 读取 EX3D 命令（0xB1）
+#### 2.2.33 读取 EX3D 命令（0xB1）

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

@@ -936,7 +991,7 @@ search:
 - 参数格式与原始 EX3D 协议保持一致
 - 详细的 EX3D 命令说明请参考 ex3d_protocol.md 文档

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

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

@@ -958,7 +1013,7 @@ search:

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

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

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