ftyyda/phaten-audio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e469ee014416cf85517daca255173822b1c92b09
phaten-audio/en/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
PhatenIoT-yan e469ee0144 update
2026-03-09 16:50:37 +08:00

38 KiB
Raw Blame History

title, description, keywords, authors, tags, search
title description keywords authors tags search
XMOS EQ HID Communication Protocol Specification 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. EQ, HID, Control Protocol, Command Set, USB HID, XU316, Zero-Code Firmware, Phaten Audio
admin
Protocol
XMOS
EQ
HID
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, and device information retrieval.

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

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
0xB0 SET_EX3D_CMD Set EX3D command PC ↔ Device
0xB1 GET_EX3D_CMD Get EX3D command PC ↔ Device
0x80 SET_UPSAMPLE Set sampling rate upsampling PC ↔ Device
0x81 GET_UPSAMPLE Get sampling rate upsampling status 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: presets, 7-9: user, 9: Bypass)
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-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: 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)

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)

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)

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 uac_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 Current EQ enable status (0=OFF, 1=ON)
4-63 60 reserved Reserved fields (fill with 0)

2.2.22 Get Sampling Format (0x9F)

Function: Read current audio sampling rate and 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: 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 samp_rate Sampling rate (uint32, little endian, e.g., 48000)
7-10 4 samp_format Sample format (uint32, little endian)
11-63 53 reserved Reserved fields (fill with 0)

2.2.23 Set Gain Mode (0xA0)

Function: Set gain adjustment mode (input gain/output gain)

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=Input Gain, 1=Output Gain)
4-63 60 reserved Reserved fields (fill with 0)

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=Input Gain, 1=Output Gain)
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

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

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_bcd Major version (BCD, e.g. 0x01 means 1)
4 1 minor_bcd Minor version (BCD, e.g. 0x00 means 0)
5 1 patch_bcd Patch version (BCD, e.g. 0x0C means 12)
6-63 58 reserved Reserved fields (fill with 0)

Version Format Description:

  • Version uses BCD (Binary Coded Decimal) format
  • Example: 0x01 0x00 0x0C represents version 1.0.12

2.2.30 Set EX3D Command (0xB0)

Function: Send EX3D set command, encapsulating all EX3D SET commands

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 (includes SET flag, refer to ex3d_protocol.md)
7-10 4 param1 Parameter 1 (depends on EX3D command)
11-14 4 param2 Parameter 2 (depends on EX3D command)
15-18 4 param3 Parameter 3 (depends on EX3D command)
19-63 45 reserved Reserved or extended parameters

EX3D Command Code Description:

  • Base command range: 0x80-0x94
  • SET command format: Base Command & ~0x0100 (clear 9th bit)
  • Supported SET commands:
    • 0x81: CMD_OPEN (Open EX3D)
    • 0x82: CMD_ONOFF (Set EX3D Switch)
    • 0x83: CMD_ANGLE (Set Angle)
    • 0x84: CMD_SOUND_FIELD (Set Sound Field)
    • 0x85: CMD_MUTE (Set Mute)
    • 0x86: CMD_ON_GAIN (Set On Gain)
    • 0x87: CMD_LMT_THRESHOLD (Set Limiter Threshold)
    • 0x88: CMD_UPMIX (Set Upmix)
    • 0x89: CMD_LFE (Set LFE Gain)
    • 0x8A: CMD_OFF_GAIN (Set Off Gain)
    • 0x8E: CMD_LMT_ATTACKK_TIME (Set Limiter Attack Time)
    • 0x8F: CMD_LMT_RELEASE_TIME (Set Limiter Release Time)
    • 0x90: CMD_TEST_CANCEL (Cancel Test)
    • 0x91: CMD_TEST_STEP (Test Step)
    • 0x92: CMD_TEST_ROTATE (Test Rotate)
    • 0x93: CMD_EXPAND_GAIN (Set Expand Gain)
    • 0x94: CMD_REDUCE_GAIN (Set Reduce Gain)

Device Processing:

  • Parses EX3D command code, extracts base command and parameters
  • Calls corresponding EX3D handler (hid_receive_task_in_c)
  • Executes setting operation based on command type

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 result Return value (some commands return 0xFFFFFFFF for parameter error)
12-63 52 reserved Reserved fields

Usage Instructions:

  • This command unifies all EX3D setting commands
  • Parameter format consistent with original EX3D protocol
  • For detailed EX3D command descriptions, refer to ex3d_protocol.md

2.2.31 Get EX3D Command (0xB1)

Function: Read EX3D parameters, encapsulating all EX3D GET commands

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 (includes GET flag, refer to ex3d_protocol.md)
7-10 4 param1 Parameter 1 (depends on EX3D command, e.g., channel, index)
11-63 53 reserved Reserved or extended parameters

EX3D Command Code Description:

  • Base command range: 0x80-0x94
  • GET command format: Base Command | 0x0100 (set 9th bit)
  • Supported GET commands:
    • 0x180: CMD_CH_NUM (Get Channel Count)
    • 0x182: CMD_ONOFF (Get EX3D Switch)
    • 0x183: CMD_ANGLE (Get Angle)
    • 0x184: CMD_SOUND_FIELD (Get Sound Field)
    • 0x185: CMD_MUTE (Get Mute)
    • 0x186: CMD_ON_GAIN (Get On Gain)
    • 0x187: CMD_LMT_THRESHOLD (Get Limiter Threshold)
    • 0x188: CMD_UPMIX (Get Upmix)
    • 0x189: CMD_LFE (Get LFE Gain)
    • 0x18A: CMD_OFF_GAIN (Get Off Gain)
    • 0x18B: CMD_SOUND_FIELD_NUM (Get Sound Field Count)
    • 0x18C: CMD_SOUND_FIELD_NAME (Get Sound Field Name)
    • 0x18D: CMD_LEVEL (Get Level)
    • 0x18E: CMD_LMT_ATTACKK_TIME (Get Limiter Attack Time)
    • 0x18F: CMD_LMT_RELEASE_TIME (Get Limiter Release Time)
    • 0x193: CMD_EXPAND_GAIN (Get Expand Gain)
    • 0x194: CMD_REDUCE_GAIN (Get Reduce Gain)

Device Processing:

  • Parses EX3D command code, extracts base command and parameters
  • Calls corresponding EX3D handler (hid_receive_task_in_c)
  • Returns current parameter value

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 result1 Result 1 (depends on command)
11-14 4 result2 Result 2 (some commands need multiple results, e.g. angle, multi-channel data)
15-18 4 result3 Result 3 (extended result, e.g. multi-channel data)
19-63 45 reserved Other results or padding (max 14 uint32 values, total < 63 bytes)

Return Value Description:

  • Return value count and format depend on specific EX3D command
  • Single value command: returns 1 uint32
  • Multi-value command (e.g. angle): returns multiple uint32
  • String command (e.g. sound field name): first returns length (uint32), then string data
  • For detailed return formats, refer to ex3d_protocol.md

Usage Instructions:

  • This command unifies all EX3D reading commands
  • Parameter format consistent with original EX3D protocol
  • For detailed EX3D command descriptions, refer to ex3d_protocol.md

2.2.32 Set Sampling Rate Upsampling (0x80)

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.33 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)

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.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**: 0-6 are preset modes, 7-9 are user modes, 9 is Bypass mode (Note: Mode 9 is typically Bypass, check specific device config)
- **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 Flat/Linear Flat response, no EQ processing Preset Mode
1 Pop/Rock Optimized for pop/rock music Preset Mode
2 Classical Optimized for classical music Preset Mode
3 Jazz Optimized for jazz music Preset Mode
4 Vocal Vocal enhancement Preset Mode
5 Bass Boost Bass enhancement Preset Mode
6 3D Game Optimized for gaming spatial audio Preset Mode
7 User 1 User-defined mode 1 User Mode
8 User 2 User-defined mode 2 User Mode
9 User 3 User-defined mode 3 User Mode
10 Bypass EQ function bypass Special Mode

!!! info "Mode Characteristics" - Preset Modes: Factory presets, non-modifiable, optimized for specific music genres - User Modes: Support user-defined parameters, can be saved and reset - Bypass Mode: Completely disables EQ processing, audio signal passes through (Bypass)

Consultation and Feedback

Click to expand consultation and feedback form

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

Reference in New Issue View Git Blame Copy Permalink