ftyyda/phaten-audio

Fork 0

Files

PhatenIoT-yan b745a7636c update hid

2026-03-27 11:18:00 +08:00

41 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, 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

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	SET_EQ_BAND_COUNT	Set EQ band count	PC → Device
0xA8	GET_EQ_BAND_COUNT	Get EQ band count	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: 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)

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 EQ Band Count (0xA7)

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: 0xA7
3	1	band_count	EQ band count (8=Core0 only, 16=Core0+Core1, 24=Core0+Core1+Core2, 32=all 4 cores)
4-63	60	reserved	Reserved fields (fill with 0)

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

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: 0xA7 (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.31 Get EQ Band Count (0xA8)

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

2.2.32 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.33 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.34 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.35 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

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.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	ClASIC	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"

41 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 Set EQ Band Count (0xA7)

2.2.31 Get EQ Band Count (0xA8)

2.2.32 Set EX3D Command (0xB0)

2.2.33 Get EX3D Command (0xB1)

2.2.34 Set Sampling Rate Upsampling (0x80)

2.2.35 Get Sampling Rate Upsampling (0x81)

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

41 KiB

Raw Blame History