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/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
+++ b/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
@@ -113,6 +113,8 @@ search:
 | 0xB4 | GET_EQ_BAND_COUNT | 获取 EQ 段数 | PC ↔ 设备 |
 | 0x80 | SET_UPSAMPLE | 设置采样率升频开关 | PC → 设备 |
 | 0x81 | GET_UPSAMPLE | 获取采样率升频状态 | PC ↔ 设备 |
+| 0xB0 | SET_EX3D_CMD | 发送 EX3D 设置命令 | PC → 设备 |
+| 0xB1 | GET_EX3D_CMD | 读取 EX3D 命令 | PC ↔ 设备 |

 ### 2.2 详细命令格式

@@ -1113,6 +1115,333 @@ search:
 | 3 | 1 | upsample | 当前升频状态（0=禁用, 1=使能） |
 | 4-63 | 60 | reserved | 保留字段（填充0） |

+#### 2.2.41 发送 EX3D 设置命令（0xB0）
+
+**功能说明**: 发送 EX3D 设置命令，封装所有 EX3D SET 命令，用于空间音频参数设置
+
+**适用设备**: VID 0x20B1, PID 0x80D3（V7.1空间音频专用设备）
+
+**请求格式（64 字节）**:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB0 |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码（SET 格式） |
+| 7-10 | 4 | param1 | int32 参数1（根据命令不同） |
+| 11-14 | 4 | param2 | int32 参数2（根据命令不同） |
+| 15-18 | 4 | param3 | int32 参数3（根据命令不同） |
+| 19-63 | 45 | reserved | 保留字段（填充0） |
+
+**支持的 EX3D SET 命令**:
+
+| EX3D 命令码 | 命令名称 | 功能描述 |
+|:-----------:|:--------:|:--------:|
+| 0x83 | CMD_ANGLE | 设置空间音频角度参数 |
+| 0x84 | CMD_SOUND_FIELD | 设置声场模式 |
+| 0x87 | CMD_LMT_THRESHOLD | 设置枪声阈值 |
+| 0x93 | CMD_EXPAND_GAIN | 设置脚步声增益 |
+
+**响应格式（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 | retval | 返回值（0xFFFFFFFF 表示参数错误） |
+| 12-63 | 52 | reserved | 保留字段（填充0） |
+
+#### 2.2.42 读取 EX3D 命令（0xB1）
+
+**功能说明**: 读取 EX3D 参数，封装所有 EX3D GET 命令，用于空间音频参数读取
+
+**适用设备**: VID 0x20B1, PID 0x80D3（V7.1空间音频专用设备）
+
+**请求格式（64 字节）**:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码（GET 格式） |
+| 7-10 | 4 | param1 | uint32 参数1（通道号、索引等） |
+| 11-63 | 53 | reserved | 保留字段（填充0） |
+
+**支持的 EX3D GET 命令**:
+
+| EX3D 命令码 | 命令名称 | 功能描述 |
+|:-----------:|:--------:|:--------:|
+| 0x183 | CMD_ANGLE | 获取空间音频角度参数 |
+| 0x184 | CMD_SOUND_FIELD | 获取声场模式 |
+| 0x187 | CMD_LMT_THRESHOLD | 获取枪声阈值 |
+| 0x18D | CMD_LEVEL | 获取电平 |
+| 0x193 | CMD_EXPAND_GAIN | 获取脚步声增益 |
+
+**响应格式（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 | retval1 | uint32 返回值1 |
+| 11-14 | 4 | retval2 | uint32 返回值2 |
+| 15-18 | 4 | retval3 | uint32 返回值3 |
+| 19-63 | 45 | reserved | 保留字段（填充0） |
+
+### 2.3 EX3D 子命令详细说明
+
+!!! note "EX3D 协议说明"
+    以下命令通过 0xB0/0xB1 封装发送，仅适用于 VID 0x20B1, PID 0x80D3 的 V7.1 空间音频设备。
+
+#### 2.3.1 EX3D 命令码格式说明
+
+- **SET 命令格式**: `基础命令码 & ~0x0100`（清除第9位）
+  - 例: 设置枪声阈值 = 0x87 & ~0x0100 = 0x87
+  - 例: 设置脚步声增益 = 0x93 & ~0x0100 = 0x93
+
+- **GET 命令格式**: `基础命令码 | 0x0100`（设置第9位）
+  - 例: 获取枪声阈值 = 0x87 | 0x0100 = 0x187
+  - 例: 获取脚步声增益 = 0x93 | 0x0100 = 0x193
+
+#### 2.3.2 声场模式控制（CMD_SOUND_FIELD = 0x84）
+
+**功能说明**: 设置或获取当前声场模式  
+**应用场景**: 切换 FPS Game/RPG Game/3A Game 三种声场效果
+
+**SET 请求格式（64 字节）**（0xB0 封装）:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB0 |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x84 = CMD_SET(CMD_SOUND_FIELD)) |
+| 7-10 | 4 | mode | uint32 用户模式值: 1=FPS Game, 2=RPG Game, 3=3A Game |
+| 11-63 | 53 | reserved | 保留字段（填充0） |
+
+**用户模式 → 内部 IR 算法映射**:
+
+| 用户值 | 含义 | `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 响应格式（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 命令码 (0x84，回显) |
+| 8-11 | 4 | retval | 返回值（0xFFFFFFFF=索引无效, 其他=成功） |
+| 12-63 | 52 | reserved | 保留字段（填充0） |
+
+**GET 请求格式（64 字节）**（0xB1 封装）:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x184 = CMD_GET(CMD_SOUND_FIELD)) |
+| 7-63 | 57 | reserved | 保留字段（填充0） |
+
+**GET 响应格式（64 字节）**:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB1（回显） |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x184，回显) |
+| 7-10 | 4 | mode | uint32 当前用户模式值 (1=FPS Game, 2=RPG Game, 3=3A Game) |
+| 11-63 | 53 | reserved | 保留字段（填充0） |
+
+#### 2.3.3 枪声阈值控制（CMD_LMT_THRESHOLD = 0x87）
+
+**功能说明**: 设置/获取枪声音效触发阈值  
+**应用场景**: FPS Game/3A Game 模式下检测枪声并触发相应音效处理
+
+**SET 请求格式（64 字节）**（0xB0 封装）:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB0 |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x87 = CMD_SET(CMD_LMT_THRESHOLD)) |
+| 7-10 | 4 | threshold | int32 阈值值 (范围: -96 ~ 0 dB) |
+| 11-63 | 53 | reserved | 保留字段（填充0） |
+
+**SET 响应格式（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 命令码 (0x87，回显) |
+| 8-11 | 4 | retval | 返回值（0xFFFFFFFF=索引无效, 其他=成功） |
+| 12-63 | 52 | reserved | 保留字段（填充0） |
+
+**GET 请求格式（64 字节）**（0xB1 封装）:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x187 = CMD_GET(CMD_LMT_THRESHOLD)) |
+| 7-63 | 57 | reserved | 保留字段（填充0） |
+
+**GET 响应格式（64 字节）**:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB1（回显） |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x187，回显) |
+| 7-10 | 4 | threshold | int32 当前阈值值 (范围: -96 ~ 0 dB) |
+| 11-63 | 53 | reserved | 保留字段（填充0） |
+
+#### 2.3.4 脚步声增益控制（CMD_EXPAND_GAIN = 0x93）
+
+**功能说明**: 设置/获取脚步声音效增益  
+**应用场景**: FPS Game/3A Game 模式下增强脚步声效果
+
+**SET 请求格式（64 字节）**（0xB0 封装）:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB0 |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x93 = CMD_SET(CMD_EXPAND_GAIN)) |
+| 7-10 | 4 | gain | int32 增益值 (范围: 0 ~ 24 dB) |
+| 11-63 | 53 | reserved | 保留字段（填充0） |
+
+**SET 响应格式（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 命令码 (0x93，回显) |
+| 8-11 | 4 | retval | 返回值（0xFFFFFFFF=索引无效, 其他=成功） |
+| 12-63 | 52 | reserved | 保留字段（填充0） |
+
+**GET 请求格式（64 字节）**（0xB1 封装）:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x193 = CMD_GET(CMD_EXPAND_GAIN)) |
+| 7-63 | 57 | reserved | 保留字段（填充0） |
+
+**GET 响应格式（64 字节）**:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB1（回显） |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x193，回显) |
+| 7-10 | 4 | gain | int32 当前增益值 (范围: 0 ~ 24 dB) |
+| 11-63 | 53 | reserved | 保留字段（填充0） |
+
+#### 2.3.5 角度控制（CMD_ANGLE = 0x83）
+
+**功能说明**: 设置/获取空间音频角度参数  
+**应用场景**: 调整虚拟环绕声的空间定位
+
+**SET 请求格式（64 字节）**（0xB0 封装）:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB0 |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x83 = CMD_SET(CMD_ANGLE)) |
+| 7-10 | 4 | angle | uint32 打包角度值 (低16位=水平角度, 高16位=垂直角度) |
+| 11-63 | 53 | reserved | 保留字段（填充0） |
+
+**SET 响应格式（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 命令码 (0x83，回显) |
+| 8-11 | 4 | retval | 返回值（0xFFFFFFFF=索引无效, 其他=成功） |
+| 12-63 | 52 | reserved | 保留字段（填充0） |
+
+**GET 请求格式（64 字节）**（0xB1 封装）:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x183 = CMD_GET(CMD_ANGLE)) |
+| 7-10 | 4 | channel | uint32 通道号 (0-7) |
+| 11-63 | 53 | reserved | 保留字段（填充0） |
+
+**GET 响应格式（64 字节）**:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB1（回显） |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x183，回显) |
+| 7-10 | 4 | angle | uint32 打包角度值 (低16位=水平角度, 高16位=垂直角度) |
+| 11-63 | 53 | reserved | 保留字段（填充0） |
+
+#### 2.3.6 电平获取（CMD_LEVEL = 0x8D）
+
+**功能说明**: 获取各通道电平数据  
+**应用场景**: 实时显示音频电平表
+
+**GET 请求格式（64 字节）**（0xB1 封装）:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB1 |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x18D = CMD_GET(CMD_LEVEL)) |
+| 7-10 | 4 | count | uint32 通道数量 (1-16) |
+| 11-63 | 53 | reserved | 保留字段（填充0） |
+
+**GET 响应格式（64 字节）**:
+
+| 偏移 | 长度 | 字段名 | 描述 |
+|:----:|:----:|:------:|:----:|
+| 0 | 1 | report_id | 固定为 0x01 |
+| 1 | 1 | sync_header | 同步头: 0x77 |
+| 2 | 1 | cmd_header | 命令头: 0xB1（回显） |
+| 3-6 | 4 | ex3d_cmd | EX3D 命令码 (0x18D，回显) |
+| 7开始 | N | levels | float32[] 各通道电平值数组 |
+| ... | ... | ... | 保留字段（填充0） |
+
 ## 三、数据流程和时序 :material-timeline-clock:

 ### 3.1 典型操作流程
@@ -1142,6 +1471,27 @@ search:
 4. 传输完成后发送 FIRMWARE_UPGRADE_END 命令 (0xA9) 结束升级
 5. 设备验证镜像完整性并返回状态

+#### 3.1.5 EX3D 声场模式读取流程
+**适用设备**: VID 0x20B1, PID 0x80D3（V7.1 空间音频专用设备）
+
+1. GUI发送 GET_EX3D_CMD 命令 (0xB1)，封装 CMD_SOUND_FIELD (0x184)
+2. 设备返回当前声场模式 (1=FPS Game, 2=RPG Game, 3=3A Game)
+3. GUI根据声场模式更新界面状态
+
+#### 3.1.6 EX3D 声场模式设置流程
+**适用设备**: VID 0x20B1, PID 0x80D3（V7.1 空间音频专用设备）
+
+1. GUI发送 SET_EX3D_CMD 命令 (0xB0)，封装 CMD_SOUND_FIELD (0x84) 和目标模式值
+2. 设备更新内部声场模式状态并返回响应
+3. 如从 RPG Game 切换到 FPS Game/3A Game，GUI需重新读取 FPS 控制参数
+
+#### 3.1.7 EX3D FPS 控制参数读取流程
+**适用设备**: VID 0x20B1, PID 0x80D3（V7.1 空间音频专用设备）
+
+1. GUI发送 GET_EX3D_CMD 命令 (0xB1)，封装 CMD_LMT_THRESHOLD (0x187) 读取枪声阈值
+2. GUI发送 GET_EX3D_CMD 命令 (0xB1)，封装 CMD_EXPAND_GAIN (0x193) 读取脚步声增益
+3. 设备分别返回当前阈值和增益值
+
 ### 3.2 时序要求与约束

 !!! warning "时序要求"