phaten-audio/en/docs/dev_doc/protocols/XMOS_EQ_HID_Protocol.md

---
title: XMOS EQ HID Communication Protocol Specification
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:
  - 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 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

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

### 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-5: presets, 6-8: user, 9: Bypass) |
| 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-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: 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) |

#### 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) |



## 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 (0x8A)
2. Device updates internal mode state
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 target mode (0x8A)
2. Send commands for all 8 filters sequentially (0x8D)
3. Device receives and updates internal parameter cache
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 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**: 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**: 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 (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 | 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 | User 1 | User-defined mode 1 | User Mode |
| 7 | User 2 | User-defined mode 2 | User Mode |
| 8 | User 3 | User-defined mode 3 | User Mode |
| 9 | 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)

---

## Consultation and Feedback

<details>
<summary>Click to expand consultation and feedback form</summary>

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

</details>