Files

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

- 修正文件名 XMOS_EQ_HID_Protoco.md -> XMOS_EQ_HID_Protocol.md
- 新增 XMOS EQ HID 协议文档（中/英）
- 精简免开发固件页「待发布」占位说明措辞
- mkdocs 预留（注释）数字调音台导航项
- gitignore 忽略未纳入版本库的 digital_mixer 目录

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-16 14:01:43 +08:00

60 KiB

Raw Blame History

title, description, keywords, authors, tags, search

title

description

keywords

authors

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

GUI sends SET_EQ_MODE command (0x8A)
Device updates internal mode state
GUI sends GET_EQ_MODE command (0x8B) for confirmation
Device responds with current mode state

3.1.2 Parameter Setting Flow

GUI sends SET_EQ_MODE command to switch to target mode (0x8A)
Send commands for all 8 filters sequentially (0x8D)
Device receives and updates internal parameter cache
Optional: Send GET_EQ_PARAMS command to verify parameters (0x8E)

3.1.3 Parameter Reading Flow

GUI sends SET_EQ_MODE command to switch to target mode (0x8A)
GUI sends GET_EQ_PARAMS request (0x8E)
Device prepares response data
GUI reads response

3.1.4 Firmware Upgrade Flow

GUI sends FIRMWARE_UPGRADE_START command (0xA7) with firmware size
Device returns the page-aligned size and total block count
GUI loops on FIRMWARE_UPGRADE_DATA command (0xA8) to transfer firmware blocks
After transfer completes, GUI sends FIRMWARE_UPGRADE_END command (0xA9)
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)

GUI sends GET_EX3D_CMD command (0xB1), encapsulating CMD_SOUND_FIELD (0x184)
Device returns the current sound field mode (1=FPS Game, 2=RPG Game, 3=3A Game)
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)

GUI sends SET_EX3D_CMD command (0xB0), encapsulating CMD_SOUND_FIELD (0x84) and the target mode value
Device updates the internal sound field mode state and returns a response
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)

GUI sends GET_EX3D_CMD command (0xB1), encapsulating CMD_LMT_THRESHOLD (0x187) to read the gunshot threshold
GUI sends GET_EX3D_CMD command (0xB1), encapsulating CMD_EXPAND_GAIN (0x193) to read the footstep gain
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:

Timing Requirements: After sending parameters, wait for device processing before sending the next command
Data Completeness: All 8 filters’ parameters should be sent, even if some filters are unused
Mode Synchronization: After setting a mode, call the read-mode command to ensure synchronization
Error Recovery: If communication fails, reconnect and retry
Parameter Validation: Device validates parameter ranges; out-of-range values are clamped or rejected

Consultation and Feedback

Click to expand consultation and feedback form

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

60 KiB Raw Blame History Unescape Escape

XMOS EQ HID Communication Protocol Specification

Protocol Overview :material-file-document-outline:

1. Protocol Foundation Specification :material-connection:

1.1 Underlying Communication Protocol

1.2 HID Device Identification

1.3 Communication Mechanism

1.4 Data Packet Structure

2. Protocol Command Set :material-code-tags:

2.1 Command Classification Overview

2.1.1 Command Header Definitions

2.2 Detailed Command Formats

2.2.1 Switch EQ Mode (0x8A)

2.2.2 Get Current EQ Mode Information (0x8B)

2.2.3 Set Mode Overall Gain and Name (0x8C)

2.2.4 Set EQ Parameters (0x8D)

2.2.5 Read EQ Parameters (0x8E)

2.2.6 Get Device Information (0x8F)

2.2.7 Reset EQ Parameters (0x90)

2.2.8 Get EQ Mode Count (0x91)

2.2.9 Set and Save EQ Mode (0x92)

2.2.10 Set Volume Level (0x93)

2.2.11 Get Volume Level (0x94)

2.2.12 Get LED Information (0x95)

2.2.13 Set LED Switch (0x96)

2.2.14 Get LED Switch Status (0x97)

2.2.15 Get LED Status (0x98)

2.2.16 Get LED Total Count (0x99)

2.2.17 Get UAC Mode Information (0x9A)

2.2.18 Set UAC Mode (0x9B)

2.2.19 Get Current UAC Mode (0x9C)

2.2.20 Set EQ Enable Switch (0x9D)

2.2.21 Get EQ Enable Status (0x9E)

2.2.22 Get Sampling Format (0x9F)

2.2.23 Set Gain Mode (0xA0)

2.2.24 Get Gain Mode (0xA1)

2.2.25 Set Filter Mode (0xA2)

2.2.26 Get Filter Mode (0xA3)

2.2.27 Set Game Mode (0xA4)

2.2.28 Get Game Mode (0xA5)

2.2.29 Get Firmware Version (0xA6)

2.2.30 Start Firmware Upgrade (0xA7)

2.2.31 Transfer Firmware Data Block (0xA8)

2.2.32 Finish Firmware Upgrade (0xA9)

2.2.33 Get Upgrade Status (0xAA)

2.2.34 Abort Firmware Upgrade (0xAB)

2.2.35 Erase Upgrade Image (0xAC)

2.2.36 Device Reboot (0xAE)

2.2.37 Set EQ Band Count (0xB3)

2.2.38 Get EQ Band Count (0xB4)

2.2.39 Set Sampling Rate Upsampling (0x80)

2.2.40 Get Sampling Rate Upsampling (0x81)

2.2.41 Send EX3D Setting Command (0xB0)

2.2.42 Read EX3D Command (0xB1)

2.3 EX3D Subcommand Details

2.3.1 EX3D Command Code Format

2.3.2 Sound Field Mode Control (CMD_SOUND_FIELD = 0x84)

2.3.3 Gunshot Threshold Control (CMD_LMT_THRESHOLD = 0x87)

2.3.4 Footstep Gain Control (CMD_EXPAND_GAIN = 0x93)

2.3.5 Angle Control (CMD_ANGLE = 0x83)

2.3.6 Level Reading (CMD_LEVEL = 0x8D)

3. Data Flow and Timing :material-timeline-clock:

3.1 Typical Operation Flows

3.1.1 Mode Switching Flow

3.1.2 Parameter Setting Flow

3.1.3 Parameter Reading Flow

3.1.4 Firmware Upgrade Flow

3.1.5 EX3D Sound Field Mode Reading Flow

3.1.6 EX3D Sound Field Mode Setting Flow

3.1.7 EX3D FPS Control Parameter Reading Flow

3.2 Timing Requirements and Constraints

4. Preset Mode Definitions :material-equalizer:

4.1 Mode Classification

5. Key Features :material-star:

5.1 Device-Side Coefficient Calculation

5.2 Parameter Formats

5.3 Error Handling

5.4 Mode Management

6. Notes :material-alert:

Consultation and Feedback

60 KiB

Raw Blame History