ftyyda/phaten-audio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source 
update
This commit is contained in:
PhatenIoT-yan
2025-12-31 18:12:27 +08:00
parent 00f42eab80
commit 78b9a5eae4
237 changed files with 10825 additions and 3401 deletions
Download Patch File Download Diff File Expand all files Collapse all files

365
en/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md
View File

@@ -1,7 +1,7 @@
---
title: XMOS EQ HID Communication Protocol Specification
status: new
description: XMOS EQ HID Communication Protocol Specification Document
description: EQ HID control protocol for zero-code firmware series devices, including message structure, command set, and field descriptions for mode switching, parameter read/write, and device information retrieval.
keywords: EQ, HID, Control Protocol, Command Set, USB HID, XU316, Zero-Code Firmware, Phaten Audio
authors:
- admin
tags:
@@ -19,10 +19,10 @@ search:
## Protocol Overview :material-file-document-outline:
!!! abstract "Functional Positioning and Scope"
This document provides a detailed description of the communication protocol between XMOS EQ HID devices and PC-side GUI software. The protocol offers a complete feature set for EQ mode control, parameter configuration, and device information retrieval.
!!! 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.
## I. Protocol Basic Specifications :material-connection:
## 1. Protocol Foundation Specification :material-connection:
### 1.1 Underlying Communication Protocol
@@ -31,300 +31,292 @@ search:
| Parameter | Value |
|:---------------:|:--------------------:|
| Transmission Method | USB HID |
| Packet Size | 64 bytes (including 1-byte Report ID 0x01) |
| Data Packet Size | 64 bytes (including 1-byte Report ID 0x01) |
| Effective Data | 63 bytes |
| Byte Order | Little Endian |
| Sync Header | 0x77 (fixed first byte) |
| 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 when sending |
| Transmission Mode | Non-blocking mode | Prevent GUI freezing |
| Report ID | 0x01 | First byte (byte 0) when sending |
| Transmission Mode | Non-blocking mode | Prevents GUI freezing |
### 1.3 Communication Mechanism
!!! warning "Data Transmission Instructions"
- All data is transmitted in Little Endian format
- Sync header 0x77 must be the first byte of each data packet
- Recommend command intervals of 5ms or more to avoid device processing delays
!!! 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
## II. Protocol Command Set :material-code-tags:
## 2. Protocol Command Set :material-code-tags:
### 2.1 Command Classification Overview
!!! note "Command Usage Instructions"
1. All commands must include sync header 0x77 as the first byte
2. Total packet length is fixed at 63 bytes (excluding Report ID)
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 Definition
#### 2.1.1 Command Header Definitions
| Command Header | Command Name | Function Description | Direction |
|:------:|:--------:|:--------:|:----:|
| 0x8B | READ_EQ_MODE | Read EQ mode status | PC → Device |
| 0x8C | SET_EQ_MODE | Set EQ mode | PC → Device |
| 0x8D | SET_EQ_PARAMS | Set EQ parameters | PC → Device |
| 0x8E | READ_EQ_PARAMS | Read EQ parameters | PC ↔ Device |
| 0x8F | SAVE_USER_MODE | Save user mode | PC → Device |
| 0x90 | READ_ALL_MODES | Read all mode information | PC ↔ Device |
| 0x91 | RESET_USER_MODE | Reset user mode | PC → Device |
| 0x92 | GET_DEVICE_INFO | Get device information | PC ↔ Device |
| 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 |
### 2.2 Detailed Command Format
### 2.2 Detailed Command Formats
#### 2.2.1 Read EQ Mode (0x8B)
#### 2.2.1 Switch EQ Mode (0x8A)
**Function Description**: Read current device EQ mode value
**Function**: Switch current EQ mode
**Request Format (63 bytes)**:
**Request Format (64 bytes)**:
| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0x8B |
| 2 | 4 | sample_rate | Sample rate (Hz, 32-bit little endian) |
| 6 | 1 | mode | Query mode value |
| 7-62 | 56 | reserved | Reserved field (padded with 0) |
| 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-5: presets, 6-8: user, 9: Bypass) |
| 4-63 | 60 | reserved | Reserved fields (fill with 0) |
#### 2.2.2 Set EQ Mode (0x8C)
#### 2.2.2 Get Current EQ Mode Information (0x8B)
**Function Description**: Formal mode setting command
**Function**: Get current mode value, overall gain, and mode name
**Packet Format (63 bytes)**:
**Request Format (64 bytes)**:
| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0x8C |
| 2 | 4 | sample_rate | Sample rate (Hz, 32-bit little endian) |
| 6 | 1 | mode | Mode value (0-5: Preset modes, 6-7: User modes, 8: Disable EQ) |
| 7-62 | 56 | reserved | Reserved field (padded with 0) |
| 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) |
#### 2.2.3 Set EQ Parameters (0x8D)
**Function Description**: Send complete parameters and coefficients for a single filter
**Packet Format (63 bytes)**:
**Response Format (64 bytes)**:
| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0x8D |
| 2 | 4 | sample_rate | Sample rate (Hz, 32-bit little endian) |
| 6 | 1 | total_gain_db | Total gain compensation (dB, 8-bit signed integer) |
| 7 | 1 | filter_index | Filter index (0-7) |
| 8 | 1 | filter_type | Filter type code |
| 9 | 4 | fc | Center frequency (Hz, 32-bit unsigned integer) |
| 13 | 4 | q_value | Q value (Q15.15 format, 32-bit signed integer) |
| 17 | 4 | bandwidth | Bandwidth (Hz, 32-bit unsigned integer) |
| 21 | 4 | gain | Gain (Q15.15 format, 32-bit signed integer) |
| 25 | 38 | reserved | Reserved field (padded with 0) |
| 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) |
**Filter Type Code Definition**:
#### 2.2.3 Set Mode Overall Gain and Name (0x8C)
| Type Code | Filter Type | English Name |
|:------:|:----------:|:--------:|
| 0x00 | Bypass Filter | Bypass Filter |
| 0x01 | All-pass Filter | All-pass Filter |
| 0x02 | Peaking Filter | Peaking Filter |
| 0x03 | Low-pass Filter | Low-pass Filter |
| 0x04 | High-pass Filter | High-pass Filter |
| 0x05 | Band-pass Filter | Band-pass Filter |
| 0x06 | Band-stop Filter | Band-stop Filter |
| 0x07 | Notch Filter | Notch Filter |
| 0x08 | Constant-Q Filter | Constant-Q Filter |
| 0x09 | Low-shelf Filter | Low-shelf Filter |
| 0x0A | High-shelf Filter | High-shelf Filter |
**Function**: Set overall gain and name for target mode
**Numerical Format Definition**:
!!! info "Q15.15 Format Description"
- **Q15.15 Format**: 16-bit integer part + 16-bit fractional part
- Example: Q value 1.414 → 0x00016A09
#### 2.2.4 Read EQ Parameters (0x8E)
**Function Description**: Read parameters of specified filter
**Request Format (63 bytes)**:
**Request Format (64 bytes)**:
| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0x8E |
| 2 | 4 | sample_rate | Sample rate (Hz, 32-bit little endian) |
| 6 | 1 | eq_index | EQ index to read (0-7) |
| 7-62 | 56 | reserved | Reserved field (padded with 0) |
| 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) |
**Response Format (63 bytes)**:
#### 2.2.4 Set EQ Parameters (0x8D)
**Function**: Send single filter parameters
**Request Format (64 bytes)**:
| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0x8E (echo) |
| 2 | 4 | sample_rate | Sample rate (Hz, 32-bit little endian) |
| 6 | 1 | total_gain_db | Total gain compensation (dB, 8-bit signed integer) |
| 7 | 1 | eq_index | EQ index (0-7) |
| 8 | 1 | filter_type | Filter type code |
| 9 | 4 | fc | Center frequency (Hz, 32-bit unsigned integer) |
| 13 | 4 | q_value | Q value (Q15.15 format, 32-bit signed integer) |
| 17 | 4 | bandwidth | Bandwidth (Hz, 32-bit unsigned integer) |
| 21 | 4 | gain | Gain (Q15.15 format, 32-bit signed integer) |
| 25 | 38 | reserved | Reserved field (padded with 0) |
| 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) |
#### 2.2.5 Save User Mode (0x8F)
**Filter Type Codes**:
**Function Description**: Save current EQ parameters to specified user mode
| 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 | | |
**Request Format (63 bytes)**:
**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 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0x8F |
| 2 | 4 | sample_rate | Sample rate (Hz, 32-bit little endian) |
| 6 | 1 | user_mode | User mode index (6-7) |
| 7 | 1 | source_mode | Source mode index (current active mode, for copying parameters) |
| 8-62 | 55 | reserved | Reserved field (padded with 0) |
| 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) |
#### 2.2.6 Read All Mode Information (0x90)
**Function Description**: Get basic information and status of all modes
**Request Format (63 bytes)**:
**Response Format (64 bytes)**:
| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0x90 |
| 2 | 4 | sample_rate | Sample rate (Hz, 32-bit little endian) |
| 6-62 | 57 | reserved | Reserved field (padded with 0) |
| 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) |
**Response Format (63 bytes)**:
#### 2.2.6 Get Device Information (0x8F)
**Function**: Get basic device identification information
**Request Format (64 bytes)**:
| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0x90 (echo) |
| 2 | 4 | sample_rate | Sample rate (Hz, 32-bit little endian) |
| 6 | 1 | current_mode | Current active mode |
| 7 | 1 | eq_enabled | EQ master switch status (0: Off, 1: On) |
| 8 | 8 | mode_status | Mode status array (each byte corresponds to one mode: 0=Default, 1=Modified, 2=Saved) |
| 16 | 8 | mode_names | Mode name index (name identifier for preset modes) |
| 24 | 39 | reserved | Reserved field (padded with 0) |
| 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) |
#### 2.2.7 Reset User Mode (0x91)
**Function Description**: Reset user mode to default state
**Request Format (63 bytes)**:
**Response Format (64 bytes)**:
| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0x91 |
| 2 | 4 | sample_rate | Sample rate (Hz, 32-bit little endian) |
| 6 | 1 | user_mode | User mode index to reset (6-7, 0xFF means reset all user modes) |
| 7-62 | 56 | reserved | Reserved field (padded with 0) |
| 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.8 Get Device Information (0x92)
#### 2.2.7 Reset EQ Parameters (0x90)
**Function Description**: Get basic device identification information
**Function**: Reset EQ parameters for specified mode or all modes
**Request Format (63 bytes)**:
**Request Format (64 bytes)**:
| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0x92 |
| 2 | 4 | sample_rate | Sample rate (Hz, 32-bit little endian) |
| 6-62 | 57 | reserved | Reserved field (padded with 0) |
| 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 (63 bytes)**:
**Response Format (64 bytes)**:
| Offset | Length | Field Name | Description |
|:----:|:----:|:------:|:----:|
| 0 | 1 | sync_header | Sync header: 0x77 |
| 1 | 1 | cmd_header | Command header: 0x92 (echo) |
| 2 | 4 | sample_rate | Sample rate (Hz, 32-bit little endian) |
| 6 | 2 | vendor_id | Vendor ID (VID, 16-bit little endian) |
| 8 | 2 | product_id | Product ID (PID, 16-bit little endian) |
| 10 | 2 | device_version | Device version number (BCD format) |
| 12 | 32 | device_name | Device name (UTF-8 encoded, null-terminated) |
| 44 | 4 | serial_number | Serial number (32-bit unsigned integer) |
| 48 | 2 | protocol_ver | Protocol version (major.minor, 1 byte each) |
| 50 | 1 | eq_band_count | Number of supported EQ bands |
| 51 | 1 | mode_count | Number of supported modes |
| 52 | 11 | reserved | Reserved field (padded with 0) |
| 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) |
## III. Data Flow and Timing :material-timeline-clock:
### 3.1 Typical Operation Flow
## 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 (0x8C)
1. GUI sends SET_EQ_MODE command (0x8A)
2. Device updates internal mode state
3. GUI sends READ_EQ_MODE command (0x8B) for confirmation
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 corresponding mode (0x8C)
2. Send commands for 8 filters sequentially (0x8D)
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 READ_EQ_PARAMS command to verify parameters
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 corresponding mode (0x8C)
2. GUI sends READ_EQ_PARAMS request (0x8E)
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**: Recommend 5ms or more
- **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 8 filters (MAX_EQ_BANDS = 8)
- **Mode Count**: Support 8 EQ modes (0-5 for preset modes, 6-7 for user modes) + 1 disable mode (8)
- **Sample Rate Support**: 44.1kHz, 48kHz, 88.2kHz, 96kHz, 176.4kHz, 192kHz
- **Filter Count**: Fixed at 8 filters (MAX_EQ_BANDS = 8)
- **Mode Count**: 0-5 are preset modes, 6-8 are user modes, 9 is Bypass mode
- **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 (fc) | 20Hz - 20kHz | 32-bit unsigned integer |
| Q Value | 0.1 - 30.0 | Q15.15 format |
| Gain | -24dB - +24dB | Q15.15 format |
| Total Gain | -24dB - 0dB | 8-bit signed integer |
| 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) |
## IV. Preset Mode Definition :material-equalizer:
## 4. Preset Mode Definitions :material-equalizer:
### 4.1 Mode Classification
| Mode Index | Mode Name | Usage Description | Type |
| Mode Index | Mode Name | Description | Type |
|:--------:|:--------:|:--------:|:----:|
| 0 | Flat/Linear | Flat response, no EQ processing | Preset Mode |
| 1 | Pop/Rock | Pop rock music optimization | Preset Mode |
| 2 | Classical | Classical music optimization | Preset Mode |
| 3 | Jazz | Jazz music optimization | 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 | User 1 | User-defined mode 1 | User Mode |
| 7 | User 2 | User-defined mode 2 | User Mode |
| 8 | Disabled | EQ function disabled | Special Mode |
| 8 | User 3 | User-defined mode 3 | User Mode |
| 9 | Bypass | EQ function bypass | Special Mode |
!!! info "Mode Characteristics Description"
- **Preset Modes**: Factory presets, non-modifiable, optimized for specific music types
!!! 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
- **Disabled Mode**: Completely turn off EQ processing, audio signal pass-through
- **Bypass Mode**: Completely disables EQ processing, audio signal passes through (Bypass)
---
@@ -336,4 +328,3 @@ search:
--8<-- "common/customer_form.md"
</details>

225
en/docs/dev_doc/protocols/XMOS_EQ_UART_Protocol.md Normal file
View File

@@ -0,0 +1,225 @@
---
title: XMOS EQ UART Control Protocol and Command Set
description: UART serial communication protocol specification for EQ parameter configuration and control, covering frame format, command set, and field descriptions, applicable to XU316 and related products.
keywords: EQ, UART, Serial Protocol, Communication Protocol, Command Set, XU316, Zero-Code Firmware, Phaten Audio
---
# XMOS EQ UART Control Protocol and Command Set
--8<-- "common/phaten_xmos_support_img.md"
## 1. Protocol Foundation Specification
### 1.1 Underlying Communication Protocol
Based on UART (Universal Asynchronous Receiver/Transmitter) protocol.
| Parameter | Value |
| :--- | :--- |
| Baud Rate | 115200 bps |
| Data Bits | 8 |
| Parity | None |
| Stop Bits | 1 |
| Flow Control | None |
### 1.2 Frame Format and Data Transmission
**General Frame Format**
All commands and responses follow this frame format:
| Field | Byte Count | Description |
| :--- | :--- | :--- |
| Frame Header | 2 | Fixed as `0x55 0xAA` |
| Version | 1 | Protocol version number (typically `0x00`) |
| Command | 1 | Indicates frame function (e.g., `0x30`) |
| Data Length | 1 | Length N of subsequent data |
| Data | N | Specific data content |
| Checksum | 1 | Sum of all bytes from frame header, modulo 256 (Sum % 256) |
**Data Transmission Notes**
* **Byte Order**: All multi-byte data is transmitted in **Little Endian** mode (Note: Different from XU316 standard protocol's big endian, please refer to this protocol).
* **Floating Point**: Follows IEEE 754 float format.
---
## 2. Protocol Command Set
### 2.1 Command Classification Overview
| Command | Command Description | Direction | Function |
| :--- | :--- | :--- | :--- |
| **0x30** | SET_EQ_MODE | Host→Device | Switch current EQ mode |
| **0x31** | GET_EQ_MODE | Host→Device | Get current EQ mode information (mode number, gain, name) |
| **0x32** | SET_MODE_GAIN_AND_NAME | Host→Device | Set overall gain and name for specified mode |
| **0x33** | SET_EQ_PARAMS | Host→Device | Send single filter parameters (Freq, Q, Gain, etc.) |
| **0x34** | GET_EQ_PARAMS | Host→Device | Read single filter parameters |
| **0x35** | RESET_EQ_PARAMS | Host→Device | Reset EQ parameters (restore presets) |
---
## 3. Basic Function Command Details
### 3.1 Switch EQ Mode (0x30)
**Host Sends**
| Byte Position | Length | Content | Description |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | Fixed frame header |
| Version | 1 | `0x00` | Protocol version |
| Command | 1 | `0x30` | Command code |
| Length | 1 | `0x01` | Data length |
| Data | 1 | `Mode` | Mode value<br>0-5: Preset modes<br>6-8: User modes<br>9: Bypass |
| Checksum | 1 | `Sum` | Checksum |
**Device Processing**
* Directly sets the currently running EQ mode.
* Does not involve parameter transmission or calculation.
---
### 3.2 Get Current EQ Mode Information (0x31)
**Host Sends**
| Byte Position | Length | Content | Description |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | Fixed frame header |
| Version | 1 | `0x00` | Protocol version |
| Command | 1 | `0x31` | Command code |
| Length | 1 | `0x00` | No data |
| Checksum | 1 | `Sum` | Checksum |
**Device Returns (Response)**
| Byte Position | Length | Content | Description |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | Fixed frame header |
| Version | 1 | `0x00` | Protocol version |
| Command | 1 | `0x31` | Command code |
| Length | 1 | `0x15` | Data length (21 bytes) |
| Data | 1 | `Mode` | Current mode value |
| | 4 | `Gain` | Overall gain (int32, little endian, range 0~-50dB) |
| | 16 | `Name` | Mode name (UTF-8 string) |
| Checksum | 1 | `Sum` | Checksum |
---
### 3.3 Set Mode Overall Gain and Name (0x32)
**Host Sends**
| Byte Position | Length | Content | Description |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | Fixed frame header |
| Version | 1 | `0x00` | Protocol version |
| Command | 1 | `0x32` | Command code |
| Length | 1 | `0x15` | Data length (21 bytes) |
| Data | 1 | `Mode` | Target mode value (0-9) |
| | 4 | `Gain` | Overall gain (int32, little endian) |
| | 16 | `Name` | Mode name (UTF-8 string) |
| Checksum | 1 | `Sum` | Checksum |
**Device Processing**
* Sets gain and name for specified mode, automatically applied to all sample rates.
---
### 3.4 Send EQ Parameters (0x33)
**Host Sends**
| Byte Position | Length | Content | Description |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | Fixed frame header |
| Version | 1 | `0x00` | Protocol version |
| Command | 1 | `0x33` | Command code |
| Length | 1 | `0x15` | Data length (21 bytes) |
| Data | 1 | `Mode` | Mode value (0-9) |
| | 1 | `Band` | Filter index (0-7) |
| | 1 | `Type` | Filter type (see table below) |
| | 4 | `Freq` | Center frequency Hz (float, little endian) |
| | 4 | `Q` | Q value (float, little endian) |
| | 4 | `BW` | Bandwidth Hz (float, little endian) |
| | 4 | `Gain` | Gain dB (float, little endian) |
| Checksum | 1 | `Sum` | Checksum |
**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 | | |
---
### 3.5 Read EQ Parameters (0x34)
**Host Sends**
| Byte Position | Length | Content | Description |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | Fixed frame header |
| Version | 1 | `0x00` | Protocol version |
| Command | 1 | `0x34` | Command code |
| Length | 1 | `0x02` | Data length |
| Data | 1 | `Mode` | Mode value (0-9) |
| | 1 | `Band` | Filter index (0-7) |
| Checksum | 1 | `Sum` | Checksum |
**Device Returns (Response)**
| Byte Position | Length | Content | Description |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | Fixed frame header |
| Version | 1 | `0x00` | Protocol version |
| Command | 1 | `0x34` | Command code |
| Length | 1 | `0x15` | Data length (21 bytes) |
| Data | 1 | `Mode` | Mode value |
| | 1 | `Band` | Filter index |
| | 1 | `Type` | Filter type |
| | 4 | `Freq` | Center frequency (float, little endian) |
| | 4 | `Q` | Q value (float, little endian) |
| | 4 | `BW` | Bandwidth (float, little endian) |
| | 4 | `Gain` | Gain (float, little endian) |
| Checksum | 1 | `Sum` | Checksum |
---
### 3.6 Reset EQ Parameters (0x35)
**Host Sends**
| Byte Position | Length | Content | Description |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | Fixed frame header |
| Version | 1 | `0x00` | Protocol version |
| Command | 1 | `0x35` | Command code |
| Length | 1 | `0x01` | Data length |
| Data | 1 | `Mode` | Mode number (0-9)<br>`0xFF` indicates reset all modes |
| Checksum | 1 | `Sum` | Checksum |
**Device Returns (Response)**
| Byte Position | Length | Content | Description |
| :--- | :--- | :--- | :--- |
| Frame Header | 2 | `0x55 0xAA` | Fixed frame header |
| Version | 1 | `0x00` | Protocol version |
| Command | 1 | `0x35` | Command code |
| Length | 1 | `0x01` | Data length |
| Data | 1 | `Status` | Status code (0x00=success, 0x01=failure) |
| Checksum | 1 | `Sum` | Checksum |
## Consultation and Feedback
<details>
<summary>Click to expand consultation and feedback form</summary>
--8<-- "common/customer_form.md"
</details>

2
en/docs/dev_doc/protocols/index.md
View File

@@ -1,5 +1,5 @@
---
title: XMOS AI Communication Protocol
title: XMOS AI Communication Protocols
hide:
-toc
---

796
en/docs/dev_doc/protocols/xu316_zerocode_protocol.md
View File

File diff suppressed because it is too large Load Diff