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

update hid

Browse Source
This commit is contained in:
PhatenIoT-yan
2026-03-27 11:18:00 +08:00
parent e469ee0144
commit b745a7636c
2 changed files with 179 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -51,6 +51,15 @@ search:
- 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
@@ -90,12 +99,14 @@ search:
| 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 |
| 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 |
| 0x80 | SET_UPSAMPLE | Set sampling rate upsampling | PC → Device |
| 0x81 | GET_UPSAMPLE | Get sampling rate upsampling status | PC ↔ Device |
### 2.2 Detailed Command Formats
@@ -111,7 +122,7 @@ search:
| 0 | 1 | report_id | Fixed value: 0x01 |
| 1 | 1 | sync_header | Sync header: 0x77 |
| 2 | 1 | cmd_header | Command header: 0x8A |
| 3 | 1 | mode | Mode value (0-6: presets, 7-9: user, 9: Bypass) |
| 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)
@@ -125,7 +136,8 @@ search:
| 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) |
| 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)**:
@@ -139,6 +151,11 @@ search:
| 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
@@ -782,7 +799,60 @@ search:
- Version uses BCD (Binary Coded Decimal) format
- Example: `0x01 0x00 0x0C` represents version `1.0.12`
#### 2.2.30 Set EX3D Command (0xB0)
#### 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
@@ -846,7 +916,7 @@ search:
- Parameter format consistent with original EX3D protocol
- For detailed EX3D command descriptions, refer to ex3d_protocol.md
#### 2.2.31 Get EX3D Command (0xB1)
#### 2.2.33 Get EX3D Command (0xB1)
**Function**: Read EX3D parameters, encapsulating all EX3D GET commands
@@ -917,7 +987,7 @@ search:
- Parameter format consistent with original EX3D protocol
- For detailed EX3D command descriptions, refer to ex3d_protocol.md
#### 2.2.32 Set Sampling Rate Upsampling (0x80)
#### 2.2.34 Set Sampling Rate Upsampling (0x80)
**Function**: Set device sampling rate upsampling switch
@@ -939,7 +1009,7 @@ search:
No direct return value. To confirm upsampling status, use GET_UPSAMPLE (0x81).
#### 2.2.33 Get Sampling Rate Upsampling (0x81)
#### 2.2.35 Get Sampling Rate Upsampling (0x81)
**Function**: Read device current sampling rate upsampling status
@@ -995,7 +1065,7 @@ No direct return value. To confirm upsampling status, use GET_UPSAMPLE (0x81).
**Hardware Limitations**
- **Filter Count**: Fixed at 8 filters (MAX_EQ_BANDS = 8)
- **Mode Count**: 0-6 are preset modes, 7-9 are user modes, 9 is Bypass mode (Note: Mode 9 is typically Bypass, check specific device config)
- **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**
@@ -1014,22 +1084,54 @@ No direct return value. To confirm upsampling status, use GET_UPSAMPLE (0x81).
| Mode Index | Mode Name | Description | Type |
|:--------:|:--------:|:--------:|:----:|
| 0 | Flat/Linear | Flat response, no EQ processing | Preset Mode |
| 1 | Pop/Rock | Optimized for pop/rock music | Preset Mode |
| 2 | Classical | Optimized for classical music | Preset Mode |
| 3 | Jazz | Optimized for jazz music | Preset Mode |
| 4 | Vocal | Vocal enhancement | Preset Mode |
| 5 | Bass Boost | Bass enhancement | Preset Mode |
| 6 | 3D Game | Optimized for gaming spatial audio | Preset Mode |
| 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 |
| 10 | Bypass | EQ function bypass | Special Mode |
!!! info "Mode Characteristics"
- **Preset Modes**: Factory presets, non-modifiable, optimized for specific music genres
- **User Modes**: Support user-defined parameters, can be saved and reset
- **Bypass Mode**: Completely disables EQ processing, audio signal passes through (Bypass)
---
## 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:
1. **Timing Requirements**: After sending parameters, wait for device processing before sending the next command
2. **Data Completeness**: All 8 filters’ parameters should be sent, even if some filters are unused
3. **Mode Synchronization**: After setting a mode, call the read-mode command to ensure synchronization
4. **Error Recovery**: If communication fails, reconnect and retry
5. **Parameter Validation**: Device validates parameter ranges; out-of-range values are clamped or rejected
---