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

update

Browse Source
This commit is contained in:
PhatenIoT-yan
2025-09-03 14:18:23 +08:00
parent c3120e8174
commit c95b83d952
29 changed files with 380 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

339
en/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md Normal file
View File

@@ -0,0 +1,339 @@
---
title: XMOS EQ HID Communication Protocol Specification
status: new
description: XMOS EQ HID Communication Protocol Specification Document
authors:
- admin
tags:
- Protocol
- XMOS
- EQ
- HID
search:
boost: 2
---
# XMOS EQ HID Communication Protocol Specification
--8<-- "common/phaten_xmos_support_img.md"
## Protocol Overview :material-file-document-outline:
!!! abstract "Functional 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.
## I. Protocol Basic Specifications :material-connection:
### 1.1 Underlying Communication Protocol
**Based on USB HID (Human Interface Device) Protocol**
| Parameter | Value |
|:---------------:|:--------------------:|
| Transmission Method | USB HID |
| Packet Size | 64 bytes (including 1-byte Report ID 0x01) |
| Effective Data | 63 bytes |
| Byte Order | Little Endian |
| Sync Header | 0x77 (fixed first byte) |
### 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 |
### 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
## II. 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)
3. Unused bytes must be padded with 0
#### 2.1.1 Command Header Definition
| 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 |
### 2.2 Detailed Command Format
#### 2.2.1 Read EQ Mode (0x8B)
**Function Description**: Read current device EQ mode value
**Request Format (63 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) |
#### 2.2.2 Set EQ Mode (0x8C)
**Function Description**: Formal mode setting command
**Packet Format (63 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) |
#### 2.2.3 Set EQ Parameters (0x8D)
**Function Description**: Send complete parameters and coefficients for a single filter
**Packet Format (63 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) |
**Filter Type Code Definition**:
| 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 |
**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)**:
| 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) |
**Response Format (63 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) |
#### 2.2.5 Save User Mode (0x8F)
**Function Description**: Save current EQ parameters to specified user mode
**Request Format (63 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) |
#### 2.2.6 Read All Mode Information (0x90)
**Function Description**: Get basic information and status of all modes
**Request Format (63 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) |
**Response Format (63 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) |
#### 2.2.7 Reset User Mode (0x91)
**Function Description**: Reset user mode to default state
**Request Format (63 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) |
#### 2.2.8 Get Device Information (0x92)
**Function Description**: Get basic device identification information
**Request Format (63 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) |
**Response Format (63 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) |
## III. Data Flow and Timing :material-timeline-clock:
### 3.1 Typical Operation Flow
#### 3.1.1 Mode Switching Flow
1. GUI sends SET_EQ_MODE command (0x8C)
2. Device updates internal mode state
3. GUI sends READ_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)
3. Device receives and updates internal parameter cache
4. Optional: Send READ_EQ_PARAMS command to verify parameters
#### 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)
3. Device prepares response data
4. GUI reads response
### 3.2 Timing Requirements and Constraints
!!! warning "Timing Requirements"
- **Command Interval**: Recommend 5ms or more
- **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
**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 |
## IV. Preset Mode Definition :material-equalizer:
### 4.1 Mode Classification
| Mode Index | Mode Name | Usage 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 |
| 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 |
!!! info "Mode Characteristics Description"
- **Preset Modes**: Factory presets, non-modifiable, optimized for specific music types
- **User Modes**: Support user-defined parameters, can be saved and reset
- **Disabled Mode**: Completely turn off EQ processing, audio signal pass-through
---
## 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/xu316_zerocode_protocol.md
View File

@@ -935,7 +935,7 @@ sequenceDiagram
| 0x07 | AUDIO_PCM_384000 | 384kHz PCM |
| 0x08 | AUDIO_PCM_705600 | 705.6kHz PCM |
| 0x09 | AUDIO_PCM_768000 | 768kHz PCM |
| 0x0A | AUDIO_PCM_1441200 | 1.4112MHz PCM |
| 0x0A | AUDIO_PCM_1411200 | 1.4112MHz PCM |
| 0x0B | AUDIO_PCM_1536000 | 1.536MHz PCM |
| 0x0C | AUDIO_PCM_32000 | 32kHz PCM |
| 0x0D | AUDIO_PCM_64000 | 64kHz PCM |