docs: 新增 XMOS EQ HID 协议文档并完善免开发固件页说明

- 修正文件名 XMOS_EQ_HID_Protoco.md -> XMOS_EQ_HID_Protocol.md - 新增 XMOS EQ HID 协议文档（中/英） - 精简免开发固件页「待发布」占位说明措辞 - mkdocs 预留（注释）数字调音台导航项 - gitignore 忽略未纳入版本库的 digital_mixer 目录 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-16 14:01:43 +08:00
parent 8ee0372c93
commit 74e5ceaf4d
5 changed files with 725 additions and 20 deletions
--- a/en/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
+++ b/en/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
@@ -113,6 +113,8 @@ search:
 | 0xB4 | GET_EQ_BAND_COUNT | Get EQ band count | PC ↔ Device |
 | 0x80 | SET_UPSAMPLE | Set sampling rate upsampling | PC → Device |
 | 0x81 | GET_UPSAMPLE | Get sampling rate upsampling status | PC ↔ Device |
+| 0xB0 | SET_EX3D_CMD | Send EX3D setting command | PC → Device |
+| 0xB1 | GET_EX3D_CMD | Read EX3D command | PC ↔ Device |

 ### 2.2 Detailed Command Formats

@@ -1130,6 +1132,333 @@ No direct return value. To confirm upsampling status, use GET_UPSAMPLE (0x81).
 | 3 | 1 | upsample | Current upsample status (0=Disabled, 1=Enabled) |
 | 4-63 | 60 | reserved | Reserved fields (fill with 0) |

+#### 2.2.41 Send EX3D Setting Command (0xB0)
+
+**Function**: Send EX3D setting command, encapsulating all EX3D SET commands for spatial audio parameter configuration
+
+**Applicable Device**: VID 0x20B1, PID 0x80D3 (V7.1 spatial audio dedicated device)
+
+**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: 0xB0 |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (SET format) |
+| 7-10 | 4 | param1 | int32 parameter 1 (varies by command) |
+| 11-14 | 4 | param2 | int32 parameter 2 (varies by command) |
+| 15-18 | 4 | param3 | int32 parameter 3 (varies by command) |
+| 19-63 | 45 | reserved | Reserved fields (fill with 0) |
+
+**Supported EX3D SET Commands**:
+
+| Command Code | Command Name | Description |
+|:-----------:|:--------:|:--------:|
+| 0x83 | CMD_ANGLE | Set spatial audio angle parameters |
+| 0x84 | CMD_SOUND_FIELD | Set sound field mode |
+| 0x87 | CMD_LMT_THRESHOLD | Set gunshot threshold |
+| 0x93 | CMD_EXPAND_GAIN | Set footstep gain |
+
+**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: 0xB0 (echo) |
+| 3 | 1 | status | Status code (0x00=Success, 0x01=Failure) |
+| 4-7 | 4 | ex3d_cmd | EX3D command code (echo) |
+| 8-11 | 4 | retval | Return value (0xFFFFFFFF indicates parameter error) |
+| 12-63 | 52 | reserved | Reserved fields (fill with 0) |
+
+#### 2.2.42 Read EX3D Command (0xB1)
+
+**Function**: Read EX3D parameters, encapsulating all EX3D GET commands for spatial audio parameter reading
+
+**Applicable Device**: VID 0x20B1, PID 0x80D3 (V7.1 spatial audio dedicated device)
+
+**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: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (GET format) |
+| 7-10 | 4 | param1 | uint32 parameter 1 (channel number, index, etc.) |
+| 11-63 | 53 | reserved | Reserved fields (fill with 0) |
+
+**Supported EX3D GET Commands**:
+
+| Command Code | Command Name | Description |
+|:-----------:|:--------:|:--------:|
+| 0x183 | CMD_ANGLE | Get spatial audio angle parameters |
+| 0x184 | CMD_SOUND_FIELD | Get sound field mode |
+| 0x187 | CMD_LMT_THRESHOLD | Get gunshot threshold |
+| 0x18D | CMD_LEVEL | Get level |
+| 0x193 | CMD_EXPAND_GAIN | Get footstep gain |
+
+**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: 0xB1 (echo) |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (echo) |
+| 7-10 | 4 | retval1 | uint32 return value 1 |
+| 11-14 | 4 | retval2 | uint32 return value 2 |
+| 15-18 | 4 | retval3 | uint32 return value 3 |
+| 19-63 | 45 | reserved | Reserved fields (fill with 0) |
+
+### 2.3 EX3D Subcommand Details
+
+!!! note "EX3D Protocol Notes"
+    The following commands are sent encapsulated via 0xB0/0xB1 and apply only to V7.1 spatial audio devices with VID 0x20B1, PID 0x80D3.
+
+#### 2.3.1 EX3D Command Code Format
+
+- **SET command format**: `base command code & ~0x0100` (clear bit 9)
+  - Example: Set gunshot threshold = 0x87 & ~0x0100 = 0x87
+  - Example: Set footstep gain = 0x93 & ~0x0100 = 0x93
+
+- **GET command format**: `base command code | 0x0100` (set bit 9)
+  - Example: Get gunshot threshold = 0x87 | 0x0100 = 0x187
+  - Example: Get footstep gain = 0x93 | 0x0100 = 0x193
+
+#### 2.3.2 Sound Field Mode Control (CMD_SOUND_FIELD = 0x84)
+
+**Function**: Set or get the current sound field mode
+**Application Scenario**: Switch between FPS Game/RPG Game/3A Game sound field effects
+
+**SET Request Format (64 bytes)** (0xB0 encapsulated):
+
+| 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: 0xB0 |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x84 = CMD_SET(CMD_SOUND_FIELD)) |
+| 7-10 | 4 | mode | uint32 user mode value: 1=FPS Game, 2=RPG Game, 3=3A Game |
+| 11-63 | 53 | reserved | Reserved fields (fill with 0) |
+
+**User Mode → Internal IR Algorithm Mapping**:
+
+| User Value | Meaning | `STEREO_EN=1` (IR) | `V71_AUDIO_MODE=1` (IR) |
+|:------:|:----:|:------------------:|:-----------------------:|
+| 1 | FPS Game | IR_GAME (1) | IR_7_1_GAME (4) |
+| 2 | RPG Game | IR_MUSIC (2) | IR_7_1_MUSIC (5) |
+| 3 | 3A Game | IR_MOVIE (3) | IR_7_1_MOVIE (6) |
+
+**SET 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: 0xB0 (echo) |
+| 3 | 1 | status | Status code (0x00=Success, 0x01=Failure) |
+| 4-7 | 4 | ex3d_cmd | EX3D command code (0x84, echo) |
+| 8-11 | 4 | retval | Return value (0xFFFFFFFF=invalid index, other=success) |
+| 12-63 | 52 | reserved | Reserved fields (fill with 0) |
+
+**GET Request Format (64 bytes)** (0xB1 encapsulated):
+
+| 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: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x184 = CMD_GET(CMD_SOUND_FIELD)) |
+| 7-63 | 57 | reserved | Reserved fields (fill with 0) |
+
+**GET 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: 0xB1 (echo) |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x184, echo) |
+| 7-10 | 4 | mode | uint32 current user mode value (1=FPS Game, 2=RPG Game, 3=3A Game) |
+| 11-63 | 53 | reserved | Reserved fields (fill with 0) |
+
+#### 2.3.3 Gunshot Threshold Control (CMD_LMT_THRESHOLD = 0x87)
+
+**Function**: Set/get gunshot sound effect trigger threshold
+**Application Scenario**: Detect gunshot sounds and trigger corresponding audio processing in FPS Game/3A Game modes
+
+**SET Request Format (64 bytes)** (0xB0 encapsulated):
+
+| 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: 0xB0 |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x87 = CMD_SET(CMD_LMT_THRESHOLD)) |
+| 7-10 | 4 | threshold | int32 threshold value (range: -96 ~ 0 dB) |
+| 11-63 | 53 | reserved | Reserved fields (fill with 0) |
+
+**SET 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: 0xB0 (echo) |
+| 3 | 1 | status | Status code (0x00=Success, 0x01=Failure) |
+| 4-7 | 4 | ex3d_cmd | EX3D command code (0x87, echo) |
+| 8-11 | 4 | retval | Return value (0xFFFFFFFF=invalid index, other=success) |
+| 12-63 | 52 | reserved | Reserved fields (fill with 0) |
+
+**GET Request Format (64 bytes)** (0xB1 encapsulated):
+
+| 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: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x187 = CMD_GET(CMD_LMT_THRESHOLD)) |
+| 7-63 | 57 | reserved | Reserved fields (fill with 0) |
+
+**GET 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: 0xB1 (echo) |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x187, echo) |
+| 7-10 | 4 | threshold | int32 current threshold value (range: -96 ~ 0 dB) |
+| 11-63 | 53 | reserved | Reserved fields (fill with 0) |
+
+#### 2.3.4 Footstep Gain Control (CMD_EXPAND_GAIN = 0x93)
+
+**Function**: Set/get footstep sound effect gain
+**Application Scenario**: Enhance footstep sound effects in FPS Game/3A Game modes
+
+**SET Request Format (64 bytes)** (0xB0 encapsulated):
+
+| 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: 0xB0 |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x93 = CMD_SET(CMD_EXPAND_GAIN)) |
+| 7-10 | 4 | gain | int32 gain value (range: 0 ~ 24 dB) |
+| 11-63 | 53 | reserved | Reserved fields (fill with 0) |
+
+**SET 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: 0xB0 (echo) |
+| 3 | 1 | status | Status code (0x00=Success, 0x01=Failure) |
+| 4-7 | 4 | ex3d_cmd | EX3D command code (0x93, echo) |
+| 8-11 | 4 | retval | Return value (0xFFFFFFFF=invalid index, other=success) |
+| 12-63 | 52 | reserved | Reserved fields (fill with 0) |
+
+**GET Request Format (64 bytes)** (0xB1 encapsulated):
+
+| 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: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x193 = CMD_GET(CMD_EXPAND_GAIN)) |
+| 7-63 | 57 | reserved | Reserved fields (fill with 0) |
+
+**GET 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: 0xB1 (echo) |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x193, echo) |
+| 7-10 | 4 | gain | int32 current gain value (range: 0 ~ 24 dB) |
+| 11-63 | 53 | reserved | Reserved fields (fill with 0) |
+
+#### 2.3.5 Angle Control (CMD_ANGLE = 0x83)
+
+**Function**: Set/get spatial audio angle parameters
+**Application Scenario**: Adjust the spatial positioning of virtual surround sound
+
+**SET Request Format (64 bytes)** (0xB0 encapsulated):
+
+| 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: 0xB0 |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x83 = CMD_SET(CMD_ANGLE)) |
+| 7-10 | 4 | angle | uint32 packed angle value (lower 16 bits=horizontal angle, upper 16 bits=vertical angle) |
+| 11-63 | 53 | reserved | Reserved fields (fill with 0) |
+
+**SET 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: 0xB0 (echo) |
+| 3 | 1 | status | Status code (0x00=Success, 0x01=Failure) |
+| 4-7 | 4 | ex3d_cmd | EX3D command code (0x83, echo) |
+| 8-11 | 4 | retval | Return value (0xFFFFFFFF=invalid index, other=success) |
+| 12-63 | 52 | reserved | Reserved fields (fill with 0) |
+
+**GET Request Format (64 bytes)** (0xB1 encapsulated):
+
+| 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: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x183 = CMD_GET(CMD_ANGLE)) |
+| 7-10 | 4 | channel | uint32 channel number (0-7) |
+| 11-63 | 53 | reserved | Reserved fields (fill with 0) |
+
+**GET 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: 0xB1 (echo) |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x183, echo) |
+| 7-10 | 4 | angle | uint32 packed angle value (lower 16 bits=horizontal angle, upper 16 bits=vertical angle) |
+| 11-63 | 53 | reserved | Reserved fields (fill with 0) |
+
+#### 2.3.6 Level Reading (CMD_LEVEL = 0x8D)
+
+**Function**: Get level data for each channel
+**Application Scenario**: Real-time audio level meter display
+
+**GET Request Format (64 bytes)** (0xB1 encapsulated):
+
+| 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: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x18D = CMD_GET(CMD_LEVEL)) |
+| 7-10 | 4 | count | uint32 channel count (1-16) |
+| 11-63 | 53 | reserved | Reserved fields (fill with 0) |
+
+**GET 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: 0xB1 (echo) |
+| 3-6 | 4 | ex3d_cmd | EX3D command code (0x18D, echo) |
+| from 7 | N | levels | float32[] array of per-channel level values |
+| ... | ... | ... | Reserved fields (fill with 0) |
+
 ## 3. Data Flow and Timing :material-timeline-clock:

 ### 3.1 Typical Operation Flows
@@ -1159,6 +1488,27 @@ No direct return value. To confirm upsampling status, use GET_UPSAMPLE (0x81).
 4. After transfer completes, GUI sends FIRMWARE_UPGRADE_END command (0xA9)
 5. Device verifies image integrity and returns status

+#### 3.1.5 EX3D Sound Field Mode Reading Flow
+**Applicable Device**: VID 0x20B1, PID 0x80D3 (V7.1 spatial audio dedicated device)
+
+1. GUI sends GET_EX3D_CMD command (0xB1), encapsulating CMD_SOUND_FIELD (0x184)
+2. Device returns the current sound field mode (1=FPS Game, 2=RPG Game, 3=3A Game)
+3. GUI updates the interface status according to the sound field mode
+
+#### 3.1.6 EX3D Sound Field Mode Setting Flow
+**Applicable Device**: VID 0x20B1, PID 0x80D3 (V7.1 spatial audio dedicated device)
+
+1. GUI sends SET_EX3D_CMD command (0xB0), encapsulating CMD_SOUND_FIELD (0x84) and the target mode value
+2. Device updates the internal sound field mode state and returns a response
+3. When switching from RPG Game to FPS Game/3A Game, the GUI must re-read the FPS control parameters
+
+#### 3.1.7 EX3D FPS Control Parameter Reading Flow
+**Applicable Device**: VID 0x20B1, PID 0x80D3 (V7.1 spatial audio dedicated device)
+
+1. GUI sends GET_EX3D_CMD command (0xB1), encapsulating CMD_LMT_THRESHOLD (0x187) to read the gunshot threshold
+2. GUI sends GET_EX3D_CMD command (0xB1), encapsulating CMD_EXPAND_GAIN (0x193) to read the footstep gain
+3. Device returns the current threshold and gain values respectively
+
 ### 3.2 Timing Requirements and Constraints

 !!! warning "Timing Requirements"