phaten-audio/en/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md

---
title: XMOS EQ HID Communication Protocol Specification
description: EQ HID control protocol for zero-code firmware series devices, including message structure, command set, and field descriptions for mode switching, parameter read/write, and device information retrieval.
keywords: EQ, HID, Control Protocol, Command Set, USB HID, XU316, Zero-Code Firmware, Phaten Audio
authors:
  - admin
tags:
  - Protocol
  - XMOS
  - EQ
  - HID
search:
  boost: 2
---

# XMOS EQ HID Communication Protocol Specification

--8<-- "common/phaten_xmos_support_img.md"

## Protocol Overview :material-file-document-outline:

!!! abstract "Functional Scope and Purpose"
    This document provides detailed specifications for the communication protocol between XMOS EQ HID devices and PC-based GUI software. The protocol offers a complete feature set for EQ mode control, parameter configuration, device information retrieval, and firmware upgrade.

## 1. Protocol Foundation Specification :material-connection:

### 1.1 Underlying Communication Protocol

**Based on USB HID (Human Interface Device) Protocol**

| Parameter | Value |
|:---------------:|:--------------------:|
| Transmission Method | USB HID |
| Data Packet Size | 64 bytes (including 1-byte Report ID 0x01) |
| Effective Data | 63 bytes |
| Byte Order | Little Endian |
| Sync Header | 0x77 (fixed at byte 1, Report ID at byte 0) |

### 1.2 HID Device Identification

| Parameter | Value | Description |
|:----------:|:--------:|:-----------------------------------------:|
| Usage Page | 0xff82 or 0xff83 | HID device type identifier |
| Report ID | 0x01 | First byte (byte 0) when sending |
| Transmission Mode | Non-blocking mode | Prevents GUI freezing |

### 1.3 Communication Mechanism

!!! warning "Data Transmission Notes"
    - All data is transmitted in Little Endian byte order
    - 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

!!! note "Command Usage Instructions"
    1. All commands must include Report ID 0x01 (byte 0) and sync header 0x77 (byte 1)
    2. Total packet length is fixed at 64 bytes (including Report ID)
    3. Unused bytes must be padded with 0

#### 2.1.1 Command Header Definitions

| Command Header | Command Name | Function Description | Direction |
|:------:|:--------:|:--------:|:----:|
| 0x8A | SET_EQ_MODE | Switch current EQ mode | PC → Device |
| 0x8B | GET_EQ_MODE | Get current EQ mode information (mode number, gain, name) | PC → Device |
| 0x8C | SET_MODE_GAIN_AND_NAME | Set overall gain and name for specified mode | PC → Device |
| 0x8D | SET_EQ_PARAMS | Send single filter parameters | PC → Device |
| 0x8E | GET_EQ_PARAMS | Read single filter parameters | PC ↔ Device |
| 0x8F | GET_DEVICE_INFO | Get basic device information (PID/VID/SN) | PC ↔ Device |
| 0x90 | RESET_EQ_PARAMS | Reset EQ parameters (restore presets) | PC ↔ Device |
| 0x91 | GET_EQ_MODE_COUNT | Get EQ mode count information | PC ↔ Device |
| 0x92 | SET_AND_SAVE_EQ_MODE | Set and save EQ mode | PC ↔ Device |
| 0x93 | SET_VOLUME | Set device volume level | PC → Device |
| 0x94 | GET_VOLUME | Get device volume level | PC ↔ Device |
| 0x95 | GET_LED_INFO | Get LED information (index and name) | PC ↔ Device |
| 0x96 | SET_LED_SWITCH | Set LED switch | PC ↔ Device |
| 0x97 | GET_LED_SWITCH | Get LED switch status | PC ↔ Device |
| 0x98 | GET_LED_STATUS | Get LED status (RGB/display status) | PC ↔ Device |
| 0x99 | GET_LED_COUNT | Get LED total count | PC ↔ Device |
| 0x9A | GET_UAC_MODE_INFO | Get UAC mode information (count and names) | PC ↔ Device |
| 0x9B | SET_UAC_MODE | Set UAC mode | PC → Device |
| 0x9C | GET_CURRENT_UAC_MODE | Get current UAC mode | PC ↔ Device |
| 0x9D | SET_EQ_ENABLE | Set EQ enable switch | PC ↔ Device |
| 0x9E | GET_EQ_ENABLE | Get EQ enable switch | PC ↔ Device |
| 0x9F | GET_SAMPLE_FORMAT | Get sample rate and format | PC ↔ Device |
| 0xA0 | SET_GAIN_MODE | Set gain mode | PC → Device |
| 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 |
| 0xA5 | GET_GAME_MODE | Get game mode | PC ↔ Device |
| 0xA6 | GET_FIRMWARE_VERSION | Get firmware version | PC ↔ Device |
| 0xA7 | FIRMWARE_UPGRADE_START | Start firmware upgrade | PC → Device |
| 0xA8 | FIRMWARE_UPGRADE_DATA | Transfer firmware data block | PC → Device |
| 0xA9 | FIRMWARE_UPGRADE_END | Finish firmware upgrade | PC → Device |
| 0xAA | FIRMWARE_UPGRADE_STATUS | Get upgrade status | PC ↔ Device |
| 0xAB | FIRMWARE_UPGRADE_ABORT | Abort firmware upgrade | PC → Device |
| 0xAC | FIRMWARE_UPGRADE_ERASE | Erase upgrade image | PC → Device |
| 0xAE | DEVICE_REBOOT | Reboot device | PC → Device |
| 0xB3 | SET_EQ_BAND_COUNT | Set EQ band count | PC → Device |
| 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

#### 2.2.1 Switch EQ Mode (0x8A)

**Function**: Switch current EQ mode

**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: 0x8A |
| 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)

**Function**: Get current mode value, overall gain, and mode name

**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: 0x8B |
| 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)**:

| 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: 0x8B (echo) |
| 3 | 1 | mode | Current mode value |
| 4-7 | 4 | gain | Overall gain (int32, little endian, range -50dB ~ 0dB) |
| 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

**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: 0x8C |
| 3 | 1 | mode | Target mode value (0-9) |
| 4-7 | 4 | gain | Overall gain (int32, little endian) |
| 8-23 | 16 | name | Mode name (UTF-8 string) |
| 24-63 | 40 | reserved | Reserved fields (fill with 0) |

#### 2.2.4 Set EQ Parameters (0x8D)

**Function**: Send single filter parameters

**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: 0x8D |
| 3 | 1 | mode | Mode value (0-9) |
| 4 | 1 | band | Filter index (0-7) |
| 5 | 1 | type | Filter type code |
| 6-9 | 4 | freq | Center frequency Hz (float, little endian) |
| 10-13 | 4 | q | Q value (float, little endian) |
| 14-17 | 4 | bw | Bandwidth Hz (float, little endian) |
| 18-21 | 4 | gain | Gain dB (float, little endian) |
| 22-63 | 42 | reserved | Reserved fields (fill with 0) |

**Filter Type Codes**:

| Code | Type | Code | Type |
|:----:|:----:|:----:|:----:|
| 0x00 | Bypass | 0x06 | Band Reject |
| 0x01 | All Pass | 0x07 | Notch |
| 0x02 | Peak | 0x08 | Constant Q |
| 0x03 | Low Pass | 0x09 | Low Shelf |
| 0x04 | High Pass | 0x0A | High Shelf |
| 0x05 | Band Pass |  |  |

**Data Format Notes**:

!!! info "Floating Point and Byte Order"
    - All floating-point numbers follow IEEE 754 float standard with little endian byte order
    - All multi-byte integers use Little Endian byte order

#### 2.2.5 Read EQ Parameters (0x8E)

**Function**: Read parameters of specified filter

**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: 0x8E |
| 3 | 1 | mode | Mode value (0-9) |
| 4 | 1 | band | Filter index (0-7) |
| 5-63 | 59 | 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: 0x8E (echo) |
| 3 | 1 | mode | Mode value |
| 4 | 1 | band | Filter index |
| 5 | 1 | type | Filter type code |
| 6-9 | 4 | freq | Center frequency Hz (float, little endian) |
| 10-13 | 4 | q | Q value (float, little endian) |
| 14-17 | 4 | bw | Bandwidth Hz (float, little endian) |
| 18-21 | 4 | gain | Gain dB (float, little endian) |
| 22-63 | 41 | reserved | Reserved fields (fill with 0) |

#### 2.2.6 Get Device Information (0x8F)

**Function**: Get basic device identification information

**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: 0x8F |
| 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: 0x8F (echo) |
| 3-4 | 2 | pid | Product ID (uint16, little endian) |
| 5-6 | 2 | vid | Vendor ID (uint16, little endian) |
| 7-22 | 16 | product | Product string (UTF-8) |
| 23-38 | 16 | vendor | Vendor string (UTF-8) |
| 39-54 | 16 | sn | Serial number string (UTF-8) |
| 55-63 | 9 | reserved | Reserved fields (fill with 0) |

#### 2.2.7 Reset EQ Parameters (0x90)

**Function**: Reset EQ parameters for specified mode or all modes

**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: 0x90 |
| 3 | 1 | mode | Mode number (0-9, 0xFF = reset all modes) |
| 4-63 | 60 | 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: 0x90 (echo) |
| 3 | 1 | status | Status code (0x00=success, 0x01=failure) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

#### 2.2.8 Get EQ Mode Count (0x91)

**Function**: Get total EQ modes and preset mode count (excluding disabled modes)

**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: 0x91 |
| 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: 0x91 (echo) |
| 3 | 1 | total | Total modes (e.g., 0-9 means 10 modes) |
| 4 | 1 | preset_total | Preset mode count (e.g., 0-6 means 7 presets) |
| 5-63 | 59 | reserved | Reserved fields (fill with 0) |

#### 2.2.9 Set and Save EQ Mode (0x92)

**Function**: Set current EQ mode and save to Flash, automatically restored on power up

**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: 0x92 |
| 3 | 1 | mode | Mode value (e.g., 0-9; 0-6 presets, 7-9 user) |
| 4-63 | 60 | 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: 0x92 (echo) |
| 3 | 1 | status | Status code (0x00=success, 0x01=failure) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

#### 2.2.10 Set Volume Level (0x93)

**Function**: Set device output volume level

**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: 0x93 |
| 3 | 1 | volume | Volume level (0-60) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

**Parameter Description**:

- Volume level range: 0-60 (total 61 levels)
- 0: Minimum volume (approx -127.5dB)
- 60: Maximum volume (0dB)
- Approximate attenuation change of 2dB per step

**Device Processing**:

- Parameter is automatically saved to Flash through the existing timed save mechanism
- If the value is out of range (`>60`), firmware rejects the setting and returns false

**Return Value**:

No direct return value. To confirm whether the volume was set successfully, use GET_VOLUME (0x94).

#### 2.2.11 Get Volume Level (0x94)

**Function**: Read current device volume level

**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: 0x94 |
| 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: 0x94 (echo) |
| 3 | 1 | volume | Current volume level (0-60) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

#### 2.2.12 Get LED Information (0x95)

**Function**: Read LED index and LED name

**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: 0x95 |
| 3 | 1 | led_index | LED index (0-7) |
| 4-63 | 60 | 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: 0x95 (echo) |
| 3 | 1 | led_index | LED index (0-7) |
| 4-19 | 16 | led_name | LED name (UTF-8 string) |
| 20-63 | 44 | reserved | Reserved fields (fill with 0) |

#### 2.2.13 Set LED Switch (0x96)

**Function**: Set LED switch status

**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: 0x96 |
| 3 | 1 | led_index | LED index (0-7) |
| 4 | 1 | onoff | LED switch (0=OFF, 1=ON) |
| 5-63 | 59 | 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: 0x96 (echo) |
| 3 | 1 | status | Status code (0x00=success, 0x01=failure) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

#### 2.2.14 Get LED Switch Status (0x97)

**Function**: Read LED switch status

**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: 0x97 |
| 3 | 1 | led_index | LED index (0-7) |
| 4-63 | 60 | 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: 0x97 (echo) |
| 3 | 1 | led_index | LED index (0-7) |
| 4 | 1 | onoff | LED switch (0=OFF, 1=ON) |
| 5-63 | 59 | reserved | Reserved fields (fill with 0) |

#### 2.2.15 Get LED Status (0x98)

**Function**: Read LED RGB color and display status

**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: 0x98 |
| 3 | 1 | led_index | LED index (0-7) |
| 4-63 | 60 | 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: 0x98 (echo) |
| 3 | 1 | led_index | LED index (0-7) |
| 4 | 1 | r | R color value (0-255) |
| 5 | 1 | g | G color value (0-255) |
| 6 | 1 | b | B color value (0-255) |
| 7 | 1 | led_status | LED status (0=Off, 1=Solid, 2=Slow Flash, 3=Fast Flash, 4=Breathing) |
| 8-63 | 56 | reserved | Reserved fields (fill with 0) |

**LED Status Enumeration**:

- 0: `LED_STATUS_OFF` (Off)
- 1: `LED_STATUS_SOLID` (Solid)
- 2: `LED_STATUS_SLOW_BLINK` (Slow Blink)
- 3: `LED_STATUS_FAST_BLINK` (Fast Blink)
- 4: `LED_STATUS_BREATHE` (Breathing)

!!! note
    - RGB values are converted from the current LED color definition (active low)
    - LED status is determined from the current display mode (solid/blinking)

#### 2.2.16 Get LED Total Count (0x99)

**Function**: Read total number of LEDs supported by 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: 0x99 |
| 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: 0x99 (echo) |
| 3 | 1 | led_total | Total LEDs |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

#### 2.2.17 Get UAC Mode Information (0x9A)

**Function**: Read UAC mode count and name list

**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: 0x9A |
| 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: 0x9A (echo) |
| 3 | 1 | count | Total UAC modes (e.g., 2) |
| 4-11 | 8 | name0 | Mode 0 name (UTF-8, max 8 bytes) |
| 12-19 | 8 | name1 | Mode 1 name (UTF-8, max 8 bytes) |
| 20-63 | 44 | reserved | Reserved fields (fill with 0) |

#### 2.2.18 Set UAC Mode (0x9B)

**Function**: Set UAC mode (UAC1.0/UAC2.0)

**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: 0x9B |
| 3 | 1 | uac_mode | UAC mode value (0=UAC2.0, 1=UAC1.0) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

**Device Processing**:

- Note: Device will not send response after reboot

#### 2.2.19 Get Current UAC Mode (0x9C)

**Function**: Read current UAC mode and name

**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: 0x9C |
| 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: 0x9C (echo) |
| 3 | 1 | uac_mode | Current UAC mode value (0=UAC2.0, 1=UAC1.0) |
| 4-11 | 8 | name | Current UAC mode name (UTF-8, max 8 bytes) |
| 12-63 | 52 | reserved | Reserved fields (fill with 0) |

#### 2.2.20 Set EQ Enable Switch (0x9D)

**Function**: Set EQ enable switch (Enable/Disable)

**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: 0x9D |
| 3 | 1 | enable | EQ Enable (0=OFF, 1=ON) |
| 4-63 | 60 | 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: 0x9D (echo) |
| 3 | 1 | status | Status code (0x00=success, 0x01=failure) |
| 4 | 1 | enable | Current EQ enable status (0=OFF, 1=ON) |
| 5-63 | 59 | reserved | Reserved fields (fill with 0) |

#### 2.2.21 Get EQ Enable Status (0x9E)

**Function**: Read current EQ enable status

**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: 0x9E |
| 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: 0x9E (echo) |
| 3 | 1 | enable | EQ enable switch status (0=OFF, 1=ON) |
| 4 | 1 | saved_mode | Saved mode value (0-9, 0xFF means not saved) |
| 5-63 | 59 | reserved | Reserved fields (fill with 0) |

#### 2.2.22 Get Sampling Format (0x9F)

**Function**: Read current sample rate, DSD mode, and DAC sampling resolution

**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: 0x9F |
| 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: 0x9F (echo) |
| 3-6 | 4 | sample_rate | Sampling rate (uint32, little endian, unit: Hz) |
| 7 | 1 | dsd_mode | DSD mode (0=PCM, 1=DOP, 2=Native DSD) |
| 8-62 | 55 | reserved | Reserved fields (fill with 0) |

**Automatic Report Mechanism**:

- The device monitors sample rate and DSD mode changes internally
- When those values change, the device automatically builds a `0x9F` response packet and reports it through the HID status report
- The host can receive these automatic status changes through HID `GET_REPORT`

#### 2.2.23 Set Gain Mode (0xA0)

**Function**: Set gain mode (low impedance/high impedance)

**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: 0xA0 |
| 3 | 1 | gain_mode | Gain mode (0=Low impedance, 1=High impedance) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

**Parameter Description**:

- 0: Low impedance mode (suitable for high-sensitivity headphones)
- 1: High impedance mode (suitable for high-impedance headphones)

**Return Value**:

No direct return value. To confirm whether the gain mode was set successfully, use GET_GAIN_MODE (0xA1).

#### 2.2.24 Get Gain Mode (0xA1)

**Function**: Read current gain adjustment mode

**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: 0xA1 |
| 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: 0xA1 (echo) |
| 3 | 1 | gain_mode | Current gain mode (0=Low impedance, 1=High impedance) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

#### 2.2.25 Set Filter Mode (0xA2)

**Function**: Set DAC filter mode

**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: 0xA2 |
| 3 | 1 | filter_mode | Filter mode value (0-7) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

**Filter Mode Definitions**:

- 0: Minimum Phase filter (default)
- 1: Linear Phase Apodizing Fast Roll-off filter
- 2: Linear phase fast roll-off filter
- 3: Linear Phase Fast Roll-off low-ripple filter
- 4: Linear phase slow roll-off filter
- 5: Minimum phase fast roll-off filter
- 6: Minimum phase slow roll-off filter
- 7: Minimum Phase Fast Roll-Off Low Dispersion

**Return Value**:

No direct return value. To confirm whether the filter mode was set successfully, use GET_FILTER_MODE (0xA3).

#### 2.2.26 Get Filter Mode (0xA3)

**Function**: Read current DAC filter mode

**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: 0xA3 |
| 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: 0xA3 (echo) |
| 3 | 1 | filter_mode | Current filter mode (0-7) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

#### 2.2.27 Set Game Mode (0xA4)

**Function**: Set game sound effect mode

**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: 0xA4 |
| 3 | 1 | game_mode | Game mode (0=No effect, 1=FPS, 2=Virtual 7.1) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

**Game Mode Definitions**:

- 0: No effect (standard stereo)
- 1: FPS mode (enhanced positional awareness)
- 2: Virtual 7.1 (surround sound effect)

**Return Value**:

No direct return value. To confirm whether the game mode was set successfully, use GET_GAME_MODE (0xA5).

#### 2.2.28 Get Game Mode (0xA5)

**Function**: Read current game mode

**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: 0xA5 |
| 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: 0xA5 (echo) |
| 3 | 1 | game_mode | Current game mode (0=No effect, 1=FPS, 2=Virtual 7.1) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

#### 2.2.29 Get Firmware Version (0xA6)

**Function**: Read device firmware version (BCD format)

**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: 0xA6 |
| 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: 0xA6 (echo) |
| 3 | 1 | major | Major version (BCD format) |
| 4 | 1 | minor | Minor version (BCD format) |
| 5 | 1 | patch | Patch version (BCD format) |
| 6-63 | 58 | reserved | Reserved fields (fill with 0) |

**Version Format Description**:

- Version uses BCD (Binary Coded Decimal) format
- 3 bytes represent: major version, minor version, patch version
- Example: `0x01 0x00 0x0C` represents version `1.0.12`

#### 2.2.30 Start Firmware Upgrade (0xA7)

**Function**: Start the firmware upgrade process, send firmware size, and get upgrade parameters

**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-6 | 4 | fw_size | Firmware size (bytes, uint32, little endian) |
| 7-63 | 57 | reserved | Reserved fields (fill with 0) |

**Response Format (64 bytes, unsolicited report)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xA7 |
| 2 | 1 | status | Status code (0x00=success, 0x01=failure, 0x03=invalid size) |
| 3-6 | 4 | aligned_size | Actual page-aligned size (uint32, little endian) |
| 7-8 | 2 | total_blocks | Total block count (uint16, little endian) |
| 9-63 | 55 | reserved | Reserved fields (fill with 0) |

#### 2.2.31 Transfer Firmware Data Block (0xA8)

**Function**: Transfer one firmware data block. Each block is fixed at 57 bytes.

**Request Format (64 bytes)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xA8 |
| 2-3 | 2 | block_num | Block index (starts from 0, uint16, little endian) |
| 4 | 1 | data_len | Data length (fixed at 57) |
| 5-61 | 57 | data | Firmware data (57 bytes) |
| 62 | 1 | checksum | Checksum (sum of bytes 0-61 mod 256) |

**Response Format (64 bytes, unsolicited report)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xA8 |
| 2 | 1 | status | Status code (0x00=success, 0x04=invalid block number, 0x05=checksum error) |
| 3-4 | 2 | ack_block | Acknowledged block index (uint16, little endian) |
| 5-63 | 59 | reserved | Reserved fields (fill with 0) |

#### 2.2.32 Finish Firmware Upgrade (0xA9)

**Function**: Complete firmware transfer and verify image integrity

**Request Format (64 bytes)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xA9 |
| 2-5 | 4 | fw_size | Total firmware size for verification (uint32, little endian) |
| 6-63 | 58 | reserved | Reserved fields (fill with 0) |

**Response Format (64 bytes, unsolicited report)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xA9 |
| 2 | 1 | status | Status code (0x00=success, 0x01=failure) |
| 3-63 | 61 | reserved | Reserved fields (fill with 0) |

#### 2.2.33 Get Upgrade Status (0xAA)

**Function**: Query upgrade state, progress, and received block count

**Request Format (64 bytes)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xAA |
| 2-63 | 62 | reserved | Reserved fields (fill with 0) |

**Response Format (64 bytes, unsolicited report)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xAA |
| 2 | 1 | status | Upgrade state (0=idle, 1=preparing, 2=transferring, 3=finalizing, 4=completed, 5=error, 6=aborted) |
| 3-4 | 2 | received_blocks | Received block count (uint16, little endian) |
| 5-6 | 2 | total_blocks | Total block count (uint16, little endian) |
| 7-8 | 2 | written_pages | Written page count (uint16, little endian) |
| 9-10 | 2 | total_pages | Total page count (uint16, little endian) |
| 11-14 | 4 | received_bytes | Received byte count (uint32, little endian) |
| 15-18 | 4 | total_bytes | Total byte count (uint32, little endian) |
| 19 | 1 | error_code | Error code |
| 20-63 | 44 | reserved | Reserved fields (fill with 0) |

**Upgrade State Enumeration**:

- 0: `IDLE`
- 1: `PREPARING`
- 2: `TRANSFERRING`
- 3: `FINALIZING`
- 4: `COMPLETED`
- 5: `ERROR`
- 6: `ABORTED`

#### 2.2.34 Abort Firmware Upgrade (0xAB)

**Function**: Abort the current upgrade process and optionally erase transferred data

**Request Format (64 bytes)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xAB |
| 2 | 1 | erase_flag | Cleanup flag (0x00=keep data, 0x01=erase data) |
| 3-63 | 61 | reserved | Reserved fields (fill with 0) |

**Response Format (64 bytes, unsolicited report)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xAB |
| 2 | 1 | status | Status code (0x00=success) |
| 3-63 | 61 | reserved | Reserved fields (fill with 0) |

#### 2.2.35 Erase Upgrade Image (0xAC)

**Function**: Erase the existing upgrade image stored in Flash

**Request Format (64 bytes)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xAC |
| 2-63 | 62 | reserved | Reserved fields (fill with 0) |

**Response Format (64 bytes, unsolicited report)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xAC |
| 2 | 1 | status | Status code (0x00=success) |
| 3-63 | 61 | reserved | Reserved fields (fill with 0) |

#### 2.2.36 Device Reboot (0xAE)

**Function**: Reboot the device immediately

**Request Format (64 bytes)**:

| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0xAE |
| 2-63 | 62 | reserved | Reserved fields (fill with 0) |

**Response**: No response. The device reboots immediately.

#### 2.2.37 Set EQ Band Count (0xB3)

**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: 0xB3 |
| 3 | 1 | band_count | EQ band count (8/16/24/32) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

**EQ Band Count Definitions**:

- 8: Only Core0 participates in processing
- 16: Core0 + Core1 participate in processing
- 24: Core0 + Core1 + Core2 participate in processing
- 32: All 4 cores participate in processing

**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
- After setting, parameters are synchronized to `tile1`; cores not participating in processing on `tile1` pass audio through in bypass mode

**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: 0xB3 (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.38 Get EQ Band Count (0xB4)

**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: 0xB4 |
| 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: 0xB4 (echo) |
| 3 | 1 | band_count | Current EQ band count (8/16/24/32) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

#### 2.2.39 Set Sampling Rate Upsampling (0x80)

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

**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: 0x80 |
| 3 | 1 | upsample | Upsample status (0=Disable, 1=Enable) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |

**Parameter Description**:

- Upsample status: 0=Disable upsampling, 1=Enable upsampling

**Return Value**:

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

#### 2.2.40 Get Sampling Rate Upsampling (0x81)

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

**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: 0x81 |
| 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: 0x81 (echo) |
| 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

#### 3.1.1 Mode Switching Flow
1. GUI sends SET_EQ_MODE command (0x8A)
2. Device updates internal mode state
3. GUI sends GET_EQ_MODE command (0x8B) for confirmation
4. Device responds with current mode state

#### 3.1.2 Parameter Setting Flow
1. GUI sends SET_EQ_MODE command to switch to target mode (0x8A)
2. Send commands for all 8 filters sequentially (0x8D)
3. Device receives and updates internal parameter cache
4. Optional: Send GET_EQ_PARAMS command to verify parameters (0x8E)

#### 3.1.3 Parameter Reading Flow
1. GUI sends SET_EQ_MODE command to switch to target mode (0x8A)
2. GUI sends GET_EQ_PARAMS request (0x8E)
3. Device prepares response data
4. GUI reads response

#### 3.1.4 Firmware Upgrade Flow
1. GUI sends FIRMWARE_UPGRADE_START command (0xA7) with firmware size
2. Device returns the page-aligned size and total block count
3. GUI loops on FIRMWARE_UPGRADE_DATA command (0xA8) to transfer firmware blocks
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"
    - **Command Interval**: Minimum 5ms recommended
    - **Read Delay**: Wait 100ms after sending read request
    - **Mode Switching**: Wait for device internal state to stabilize after completion

!!! danger "Protocol Limitations and Constraints"
    **Hardware Limitations**

    - **Filter Count**: Fixed at 8 filters (MAX_EQ_BANDS = 8)
    - **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**

    | Parameter | Range | Format |
    |:----:|:----:|:----:|
    | Center frequency (freq) | 20Hz - 20kHz | float (little endian) |
    | Q value (q) | 0.1 - 30.0 | float (little endian) |
    | Bandwidth (bw) | 1Hz - 20kHz | float (little endian) |
    | Gain (gain) | -24dB - +24dB | float (little endian) |
    | Overall gain (mode gain) | -50dB - 0dB | int32 (little endian) |

## 4. Preset Mode Definitions :material-equalizer:

### 4.1 Mode Classification

| Mode Index | Mode Name | Description | Type |
|:--------:|:--------:|:--------:|:----:|
| 0 | JAZZ | Jazz music optimization | Preset Mode |
| 1 | POP | Pop music optimization | Preset Mode |
| 2 | ROCK | Rock music optimization | Preset Mode |
| 3 | CLASSIC | 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 |

!!! 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

---

## 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

---

## Consultation and Feedback

<details>
<summary>Click to expand consultation and feedback form</summary>

--8<-- "common/customer_form.md"

</details>