diff --git a/en/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md b/en/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md index b520e97..be94cca 100644 --- 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 --- diff --git a/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md b/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md index cb273d7..10f04f3 100644 --- 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) **功能说明**: 读取设备当前采样率升频状态