update

zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md

@@ -102,6 +102,10 @@ search:
 | 0xA4 | SET_GAME_MODE | 设置游戏模式 | PC → 设备 |
 | 0xA5 | GET_GAME_MODE | 获取游戏模式 | PC ↔ 设备 |
 | 0xA6 | GET_FIRMWARE_VERSION | 获取固件版本号 | 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 详细命令格式
 
@@ -797,6 +801,186 @@ search:
 - 版本号采用 BCD（Binary Coded Decimal）格式
 - 例如：`0x01 0x00 0x0C` 表示版本 `1.0.12`
 
+#### 2.2.30 发送 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.31 读取 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.32 设置采样率升频（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.33 获取采样率升频（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 典型操作流程