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

title, description, keywords, authors, tags, search

title	description	keywords	authors	tags	search
XMOS EQ HID 通信协议规范	适用于免开发固件系列设备的 EQ HID 控制协议，包含报文结构、命令集与字段说明，用于模式切换、参数读写与设备信息获取。	EQ, HID, 控制协议, 命令集, USB HID, XU316,免开发固件, Phaten Audio	admin	协议 XMOS EQ HID	boost 2

XMOS EQ HID 通信协议规范

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

协议概述 :material-file-document-outline:

!!! abstract "功能定位与范围" 本文档详细描述了XMOS EQ HID设备与PC端GUI软件之间的通信协议。该协议提供了EQ模式控制、参数设置和设备信息获取的完整功能集。

一、协议基础规范 :material-connection:

1.1 底层通信协议

基于USB HID (Human Interface Device) 协议

参数	值
传输方式	USB HID
数据包大小	64字节（包含1字节Report ID 0x01）
有效数据	63字节
字节序	小端序（Little Endian）
同步头	0x77（固定第1字节，Report ID 为第0字节）

1.2 HID设备识别

参数	值	说明
Usage Page	0xff82 或 0xff83	HID设备类型标识
Report ID	0x01	发送时作为第一个字节（第0字节）
传输模式	非阻塞模式	避免GUI卡顿

1.3 通信机制

!!! warning "数据传输说明" - 所有数据均采用小端序（Little Endian）传输 - 同步头 0x77 固定在第 1 字节（第 0 字节为 Report ID = 0x01） - 建议命令间隔5ms以上，避免设备处理不及时

1.4 数据包结构

!!! note "64字节数据包约定" - PC发送与设备响应均使用固定长度 64 字节 - 第0字节固定为 report_id = 0x01 - 第1字节固定为 sync_header = 0x77 - 第2字节为 cmd_header（命令头） - 其余未使用字节填充 0

二、协议命令集 :material-code-tags:

2.1 命令分类概览

!!! note "命令使用说明" 1. 所有命令必须包含 Report ID 0x01（第0字节）与同步头 0x77（第1字节） 2. 数据包总长度固定为 64 字节（含 Report ID） 3. 未使用的字节必须填充为0

2.1.1 命令头定义

命令头	命令名称	功能描述	方向
0x8A	SET_EQ_MODE	切换当前的 EQ 模式	PC → 设备
0x8B	GET_EQ_MODE	获取当前 EQ 模式信息（模式号、增益、名称）	PC → 设备
0x8C	SET_MODE_GAIN_AND_NAME	设置指定模式的整体增益和名称	PC → 设备
0x8D	SET_EQ_PARAMS	发送单个滤波器的参数	PC → 设备
0x8E	GET_EQ_PARAMS	读取单个滤波器的参数	PC ↔ 设备
0x8F	GET_DEVICE_INFO	获取设备基础信息（PID/VID/SN）	PC ↔ 设备
0x90	RESET_EQ_PARAMS	复位 EQ 参数（恢复预设）	PC ↔ 设备
0x91	GET_EQ_MODE_COUNT	获取 EQ 模式数量信息	PC ↔ 设备
0x92	SET_AND_SAVE_EQ_MODE	设置并保存 EQ 模式	PC ↔ 设备
0x93	SET_VOLUME	设置设备音量级别	PC → 设备
0x94	GET_VOLUME	获取设备音量级别	PC ↔ 设备
0x95	GET_LED_INFO	获取 LED 信息（索引与名称）	PC ↔ 设备
0x96	SET_LED_SWITCH	设置 LED 开关	PC ↔ 设备
0x97	GET_LED_SWITCH	获取 LED 开关状态	PC ↔ 设备
0x98	GET_LED_STATUS	获取 LED 状态（RGB/显示状态）	PC ↔ 设备
0x99	GET_LED_COUNT	获取 LED 总数	PC ↔ 设备
0x9A	GET_UAC_MODE_INFO	获取 UAC 模式信息（数量与名称）	PC ↔ 设备
0x9B	SET_UAC_MODE	设置 UAC 模式	PC → 设备
0x9C	GET_CURRENT_UAC_MODE	获取当前 UAC 模式	PC ↔ 设备
0x9D	SET_EQ_ENABLE	设置 EQ 使能开关	PC ↔ 设备
0x9E	GET_EQ_ENABLE	获取 EQ 使能开关	PC ↔ 设备
0x9F	GET_SAMPLE_FORMAT	获取采样率与格式	PC ↔ 设备
0xA0	SET_GAIN_MODE	设置增益模式	PC → 设备
0xA1	GET_GAIN_MODE	获取增益模式	PC ↔ 设备
0xA2	SET_FILTER_MODE	设置滤波器模式	PC → 设备
0xA3	GET_FILTER_MODE	获取滤波器模式	PC ↔ 设备
0xA4	SET_GAME_MODE	设置游戏模式	PC → 设备
0xA5	GET_GAME_MODE	获取游戏模式	PC ↔ 设备
0xA6	GET_FIRMWARE_VERSION	获取固件版本号	PC ↔ 设备
0xA7	SET_EQ_BAND_COUNT	设置 EQ 段数	PC → 设备
0xA8	GET_EQ_BAND_COUNT	获取 EQ 段数	PC ↔ 设备
0xB0	SET_EX3D_CMD	发送 EX3D 命令（封装所有 EX3D SET 命令）	PC ↔ 设备
0xB1	GET_EX3D_CMD	读取 EX3D 参数（封装所有 EX3D GET 命令）	PC ↔ 设备
0x80	SET_UPSAMPLE	设置采样率升频开关	PC → 设备
0x81	GET_UPSAMPLE	获取采样率升频状态	PC ↔ 设备

2.2 详细命令格式

2.2.1 切换 EQ 模式（0x8A）

功能说明: 切换当前的 EQ 模式

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x8A
3	1	mode	模式值（0-6 为预设模式，7-9 为用户模式）
4-63	60	reserved	保留字段（填充0）

2.2.2 获取当前 EQ 模式信息（0x8B）

功能说明: 获取当前模式值、整体增益与模式名称

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x8B
3	1	mode	模式值（0-9: 指定模式；0xFF: 获取当前模式信息）
4-63	60	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x8B（回显）
3	1	mode	当前模式值
4-7	4	gain	整体增益（int32, 小端序，范围 -50dB ~ 0dB）
8-23	16	name	模式名称（UTF-8 字符串）
24-63	40	reserved	保留字段（填充0）

使用说明:

• 发送 mode = 0xFF 时，返回当前激活的 EQ 模式信息
• 发送 mode = 0-9 时，返回指定模式的增益与名称（不切换当前模式）

2.2.3 设置模式整体增益和名称（0x8C）

功能说明: 设置目标模式的整体增益和名称

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x8C
3	1	mode	目标模式值（0-9）
4-7	4	gain	整体增益（int32, 小端序）
8-23	16	name	模式名称（UTF-8 字符串）
24-63	40	reserved	保留字段（填充0）

2.2.4 设置 EQ 参数（0x8D）

功能说明: 发送单个滤波器的参数

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x8D
3	1	mode	模式值（0-9）
4	1	band	滤波器索引（0-7）
5	1	type	滤波器类型码
6-9	4	freq	中心频率 Hz（float, 小端序）
10-13	4	q	Q 值（float, 小端序）
14-17	4	bw	带宽 Hz（float, 小端序）
18-21	4	gain	增益 dB（float, 小端序）
22-63	42	reserved	保留字段（填充0）

滤波器类型码:

代码	类型	代码	类型
0x00	Bypass	0x06	带阻（Band Reject）
0x01	全通（All Pass）	0x07	陷波（Notch）
0x02	峰值（Peak）	0x08	恒定Q（Constant Q）
0x03	低通（Low Pass）	0x09	低架（Low Shelf）
0x04	高通（High Pass）	0x0A	高架（High Shelf）
0x05	带通（Band Pass）

数值格式说明:

!!! info "浮点数与字节序" - 所有浮点数遵循 IEEE 754 float，采用小端序 - 所有多字节整数均采用小端序（Little Endian）

2.2.5 读取 EQ 参数（0x8E）

功能说明: 读取指定滤波器的参数

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x8E
3	1	mode	模式值（0-9）
4	1	band	滤波器索引（0-7）
5-63	59	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x8E（回显）
3	1	mode	模式值
4	1	band	滤波器索引
5	1	type	滤波器类型码
6-9	4	freq	中心频率 Hz（float, 小端序）
10-13	4	q	Q 值（float, 小端序）
14-17	4	bw	带宽 Hz（float, 小端序）
18-21	4	gain	增益 dB（float, 小端序）
22-63	41	reserved	保留字段（填充0）

2.2.6 获取设备信息（0x8F）

功能说明: 获取设备的基本标识信息

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x8F
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x8F（回显）
3-4	2	pid	产品ID（uint16, 小端序）
5-6	2	vid	厂商ID（uint16, 小端序）
7-22	16	product	产品字符串（UTF-8）
23-38	16	vendor	厂商字符串（UTF-8）
39-54	16	sn	序列号字符串（UTF-8）
55-63	9	reserved	保留字段（填充0）

2.2.7 复位 EQ 参数（0x90）

功能说明: 复位指定模式或全部模式的 EQ 参数

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x90
3	1	mode	模式号（0-9，0xFF 表示复位所有模式）
4-63	60	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x90（回显）
3	1	status	状态码（0x00=成功, 0x01=失败）
4-63	60	reserved	保留字段（填充0）

2.2.8 获取 EQ 模式数量信息（0x91）

功能说明: 获取 EQ 模式总数与预定义模式数量（不包含禁用模式）

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x91
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x91（回显）
3	1	total	模式总数（示例：包含 0-9 共 10 个模式）
4	1	preset_total	预定义模式数量（示例：包含 0-6 共 7 个预设模式）
5-63	59	reserved	保留字段（填充0）

2.2.9 设置并保存 EQ 模式（0x92）

功能说明: 设置当前 EQ 模式并保存到 Flash，开机时自动恢复

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x92
3	1	mode	模式值（文档示例：0-9；0-6预设，7-9用户）
4-63	60	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x92（回显）
3	1	status	状态码（0x00=成功, 0x01=失败）
4-63	60	reserved	保留字段（填充0）

2.2.10 设置音量级别（0x93）

功能说明: 设置设备输出音量级别

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x93
3	1	volume	音量级别（0-60）
4-63	60	reserved	保留字段（填充0）

参数说明:

• 音量级别范围：0-60（共61级）
• 0：最小音量（约 -127.5dB）
• 60：最大音量（0dB）

2.2.11 获取音量级别（0x94）

功能说明: 读取设备当前音量级别

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x94
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x94（回显）
3	1	volume	当前音量级别（0-60）
4-63	60	reserved	保留字段（填充0）

2.2.12 获取 LED 信息（0x95）

功能说明: 读取 LED 索引与 LED 名称

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x95
3	1	led_index	LED 索引（0-7）
4-63	60	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x95（回显）
3	1	led_index	LED 索引（0-7）
4-19	16	led_name	LED 名称（UTF-8 字符串）
20-63	44	reserved	保留字段（填充0）

2.2.13 设置 LED 开关（0x96）

功能说明: 设置 LED 开关状态

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x96
3	1	led_index	LED 索引（0-7）
4	1	onoff	LED 开关（0=OFF, 1=ON）
5-63	59	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x96（回显）
3	1	status	状态码（0x00=成功, 0x01=失败）
4-63	60	reserved	保留字段（填充0）

2.2.14 获取 LED 开关状态（0x97）

功能说明: 读取 LED 开关状态

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x97
3	1	led_index	LED 索引（0-7）
4-63	60	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x97（回显）
3	1	led_index	LED 索引（0-7）
4	1	onoff	LED 开关（0=OFF, 1=ON）
5-63	59	reserved	保留字段（填充0）

2.2.15 获取 LED 状态（0x98）

功能说明: 读取 LED 的 RGB 颜色与显示状态

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x98
3	1	led_index	LED 索引（0-7）
4-63	60	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x98（回显）
3	1	led_index	LED 索引（0-7）
4	1	r	R 颜色值（0-255）
5	1	g	G 颜色值（0-255）
6	1	b	B 颜色值（0-255）
7	1	led_status	LED 状态（0=熄灭, 1=常亮, 2=慢闪, 3=快闪, 4=呼吸）
8-63	56	reserved	保留字段（填充0）

2.2.16 获取 LED 总数（0x99）

功能说明: 读取设备支持的 LED 总数

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x99
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x99（回显）
3	1	led_total	LED 总数
4-63	60	reserved	保留字段（填充0）

2.2.17 获取 UAC 模式信息（0x9A）

功能说明: 读取 UAC 模式数量与名称列表

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x9A
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x9A（回显）
3	1	count	UAC 模式总数（示例：2）
4-11	8	name0	模式0名称（UTF-8，最大8字节）
12-19	8	name1	模式1名称（UTF-8，最大8字节）
20-63	44	reserved	保留字段（填充0）

2.2.18 设置 UAC 模式（0x9B）

功能说明: 设置 UAC 模式（UAC1.0/UAC2.0）

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x9B
3	1	uac_mode	UAC 模式值（0=UAC2.0, 1=UAC1.0）
4-63	60	reserved	保留字段（填充0）

设备端处理:

• 注意：设备重启后不会返回响应

2.2.19 获取当前 UAC 模式（0x9C）

功能说明: 读取当前 UAC 模式与名称

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x9C
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x9C（回显）
3	1	uac_mode	当前 UAC 模式值（0=UAC2.0, 1=UAC1.0）
4-11	8	uac_name	当前 UAC 模式名称（UTF-8，最大8字节）
12-63	52	reserved	保留字段（填充0）

2.2.20 设置 EQ 使能开关（0x9D）

功能说明: 设置 EQ 使能开关（启用/禁用）

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x9D
3	1	enable	EQ使能（0=OFF, 1=ON）
4-63	60	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x9D（回显）
3	1	status	状态码（0x00=成功, 0x01=失败）
4	1	enable	当前 EQ 使能状态（0=OFF, 1=ON）
5-63	59	reserved	保留字段（填充0）

2.2.21 获取 EQ 使能开关（0x9E）

功能说明: 读取 EQ 使能开关状态

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x9E
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x9E（回显）
3	1	enable	EQ使能（0=OFF, 1=ON）
4-63	60	reserved	保留字段（填充0）

2.2.22 获取采样率与格式（0x9F）

功能说明: 读取当前采样率与 DSD 模式

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x9F
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x9F（回显）
3-6	4	sam_freq	采样率（uint32，小端序，单位 Hz）
7	1	dsd_mode	DSD模式（0=PCM, 1=DOP, 2=Native DSD）
8-63	56	reserved	保留字段（填充0）

自动上报机制:

• 设备在采样率或 DSD 模式发生变化时，可自动上报对应的 0x9F 响应数据包

2.2.23 设置增益模式（0xA0）

功能说明: 设置增益模式

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA0
3	1	gain_mode	增益模式（0=低阻, 1=高阻）
4-63	60	reserved	保留字段（填充0）

2.2.24 获取增益模式（0xA1）

功能说明: 读取设备当前增益模式

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA1
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA1（回显）
3	1	gain_mode	当前增益模式（0=低阻, 1=高阻）
4-63	60	reserved	保留字段（填充0）

2.2.25 设置滤波器模式（0xA2）

功能说明: 设置滤波器模式（0-7，共8种）

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA2
3	1	filter_mode	滤波器模式值（0-7）
4-63	60	reserved	保留字段（填充0）

滤波器模式值定义:

• 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 获取滤波器模式（0xA3）

功能说明: 读取设备当前滤波器模式

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA3
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA3（回显）
3	1	filter_mode	当前滤波器模式（0-7）
4-63	60	reserved	保留字段（填充0）

2.2.27 设置游戏模式（0xA4）

功能说明: 设置游戏模式

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA4
3	1	game_mode	游戏模式（0=无音效, 1=FPS, 2=虚拟7.1）
4-63	60	reserved	保留字段（填充0）

2.2.28 获取游戏模式（0xA5）

功能说明: 读取设备当前游戏模式

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA5
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA5（回显）
3	1	game_mode	当前游戏模式（0=无音效, 1=FPS, 2=虚拟7.1）
4-63	60	reserved	保留字段（填充0）

2.2.29 获取固件版本号（0xA6）

功能说明: 读取设备固件版本号（BCD 格式）

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA6
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA6（回显）
3	1	major_bcd	主版本号（BCD，例如 0x01 表示 1）
4	1	minor_bcd	次版本号（BCD，例如 0x00 表示 0）
5	1	patch_bcd	修订版本号（BCD，例如 0x0C 表示 12）
6-63	58	reserved	保留字段（填充0）

版本号格式说明:

• 版本号采用 BCD（Binary Coded Decimal）格式
• 例如：0x01 0x00 0x0C 表示版本 1.0.12

2.2.30 设置 EQ 段数（0xA7）

功能说明: 设置 EQ 段数，支持 8/16/24/32 段动态切换，控制参与处理的 DSP 核数

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA7
3	1	band_count	EQ 段数（8=仅 Core0, 16=Core0+Core1, 24=Core0+Core1+Core2, 32=全部 4 核）
4-63	60	reserved	保留字段（填充0）

设备端处理:

• 仅接受 8、16、24、32 四个有效值，其他值拒绝
• 设置后保存到 Flash（独立文件 eq_band_cnt），开机时自动恢复

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA7（回显）
3	1	status	状态码（0x00=成功, 0x01=失败）
4	1	band_count	当前 EQ 段数（8/16/24/32）
5-63	59	reserved	保留字段（填充0）

2.2.31 获取 EQ 段数（0xA8）

功能说明: 读取当前 EQ 段数

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA8
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA8（回显）
3	1	band_count	当前 EQ 段数（8/16/24/32）
4-63	60	reserved	保留字段（填充0）

2.2.32 发送 EX3D 命令（0xB0）

功能说明: 发送 EX3D 设置命令，封装所有 EX3D SET 命令

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xB0
3-6	4	ex3d_cmd	EX3D 命令码（包含 SET 标志，参考 ex3d_protocol.md）
7-10	4	param1	参数1（根据 EX3D 命令不同而不同）
11-14	4	param2	参数2（根据 EX3D 命令不同而不同）
15-18	4	param3	参数3（根据 EX3D 命令不同而不同）
19-63	45	reserved	保留字段或扩展参数

EX3D 命令码说明:

• 基础命令码范围: 0x80-0x94
• SET 命令格式: 基础命令码 & ~0x0100（清除第 9 位）
• 支持的 SET 命令：
  • 0x81: CMD_OPEN（打开 EX3D）
  • 0x82: CMD_ONOFF（设置 EX3D 开关）
  • 0x83: CMD_ANGLE（设置角度）
  • 0x84: CMD_SOUND_FIELD（设置声场模式）
  • 0x85: CMD_MUTE（设置静音）
  • 0x86: CMD_ON_GAIN（设置开启增益）
  • 0x87: CMD_LMT_THRESHOLD（设置限制器阈值）
  • 0x88: CMD_UPMIX（设置上混）
  • 0x89: CMD_LFE（设置 LFE 增益）
  • 0x8A: CMD_OFF_GAIN（设置关闭增益）
  • 0x8E: CMD_LMT_ATTACKK_TIME（设置限制器攻击时间）
  • 0x8F: CMD_LMT_RELEASE_TIME（设置限制器释放时间）
  • 0x90: CMD_TEST_CANCEL（取消测试）
  • 0x91: CMD_TEST_STEP（测试步骤）
  • 0x92: CMD_TEST_ROTATE（测试旋转）
  • 0x93: CMD_EXPAND_GAIN（设置扩展增益）
  • 0x94: CMD_REDUCE_GAIN（设置减少增益）

设备端处理:

• 解析 EX3D 命令码，提取基础命令码和参数
• 调用相应的 EX3D 处理函数（hid_receive_task_in_c）
• 根据命令类型执行相应的设置操作

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xB0（回显）
3	1	status	状态码（0x00=成功, 0x01=失败）
4-7	4	ex3d_cmd	EX3D 命令码（回显）
8-11	4	result	返回值（某些命令返回 0xFFFFFFFF 表示参数错误）
12-63	52	reserved	保留字段

使用说明:

• 该命令用于统一封装所有 EX3D 设置命令
• 参数格式与原始 EX3D 协议保持一致
• 详细的 EX3D 命令说明请参考 ex3d_protocol.md 文档

2.2.33 读取 EX3D 命令（0xB1）

功能说明: 读取 EX3D 参数，封装所有 EX3D GET 命令

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xB1
3-6	4	ex3d_cmd	EX3D 命令码（包含 GET 标志，参考 ex3d_protocol.md）
7-10	4	param1	参数1（根据 EX3D 命令不同而不同，如通道号、索引等）
11-63	53	reserved	保留字段或扩展参数

EX3D 命令码说明:

• 基础命令码范围: 0x80-0x94
• GET 命令格式: 基础命令码 | 0x0100（设置第 9 位）
• 支持的 GET 命令：
  • 0x180: CMD_CH_NUM（获取通道数量）
  • 0x182: CMD_ONOFF（获取 EX3D 开关）
  • 0x183: CMD_ANGLE（获取角度）
  • 0x184: CMD_SOUND_FIELD（获取声场模式）
  • 0x185: CMD_MUTE（获取静音）
  • 0x186: CMD_ON_GAIN（获取开启增益）
  • 0x187: CMD_LMT_THRESHOLD（获取限制器阈值）
  • 0x188: CMD_UPMIX（获取上混）
  • 0x189: CMD_LFE（获取 LFE 增益）
  • 0x18A: CMD_OFF_GAIN（获取关闭增益）
  • 0x18B: CMD_SOUND_FIELD_NUM（获取声场模式数量）
  • 0x18C: CMD_SOUND_FIELD_NAME（获取声场模式名称）
  • 0x18D: CMD_LEVEL（获取电平）
  • 0x18E: CMD_LMT_ATTACKK_TIME（获取限制器攻击时间）
  • 0x18F: CMD_LMT_RELEASE_TIME（获取限制器释放时间）
  • 0x193: CMD_EXPAND_GAIN（获取扩展增益）
  • 0x194: CMD_REDUCE_GAIN（获取减少增益）

设备端处理:

• 解析 EX3D 命令码，提取基础命令码和参数
• 调用相应的 EX3D 处理函数（hid_receive_task_in_c）
• 返回当前参数值

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xB1（回显）
3-6	4	ex3d_cmd	EX3D 命令码（回显）
7-10	4	result1	返回值1（根据命令不同而不同）
11-14	4	result2	返回值2（某些命令需要多个返回值，如角度、多通道数据等）
15-18	4	result3	返回值3（扩展返回值，如多通道数据）
19-63	45	reserved	其他返回值或填充（最多可返回 14 个 uint32 值，总长度不超过 63 字节）

返回值说明:

• 返回值数量和格式取决于具体的 EX3D 命令
• 单值命令：返回 1 个 uint32 值
• 多值命令（如角度、多通道数据）：返回多个 uint32 值
• 字符串命令（如声场名称）：先返回长度（uint32），然后返回字符串数据
• 详细的返回值格式请参考 ex3d_protocol.md 文档

使用说明:

• 该命令用于统一封装所有 EX3D 读取命令
• 参数格式与原始 EX3D 协议保持一致
• 详细的 EX3D 命令说明请参考 ex3d_protocol.md 文档

2.2.34 设置采样率升频（0x80）

功能说明: 设置设备采样率升频开关

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x80
3	1	upsample	升频状态（0=禁用升频, 1=使能升频）
4-63	60	reserved	保留字段（填充0）

参数说明:

• 升频状态：0=禁用升频，1=使能升频

返回值:

无直接返回值。如需确认升频状态，请使用 GET_UPSAMPLE (0x81) 命令读取。

2.2.35 获取采样率升频（0x81）

功能说明: 读取设备当前采样率升频状态

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x81
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0x81（回显）
3	1	upsample	当前升频状态（0=禁用, 1=使能）
4-63	60	reserved	保留字段（填充0）

三、数据流程和时序 :material-timeline-clock:

3.1 典型操作流程

3.1.1 模式切换流程

1. GUI发送SET_EQ_MODE命令 (0x8A)
2. 设备更新内部模式状态
3. GUI发送GET_EQ_MODE命令 (0x8B) 确认
4. 设备响应当前模式状态

3.1.2 参数设置流程

1. GUI发送SET_EQ_MODE命令切换到相应模式 (0x8A)
2. 逐个发送8个滤波器的命令 (0x8D)
3. 设备接收并更新内部参数缓存
4. 可选: 发送GET_EQ_PARAMS命令验证参数 (0x8E)

3.1.3 参数读取流程

1. GUI发送SET_EQ_MODE命令切换到相应模式 (0x8A)
2. GUI发送GET_EQ_PARAMS请求 (0x8E)
3. 设备准备响应数据
4. GUI读取响应

3.2 时序要求与约束

!!! warning "时序要求" - 命令间隔: 建议5ms以上 - 读取延时: 发送读取请求后等待100ms - 模式切换: 完成后等待设备内部状态稳定

!!! danger "协议限制和约束" 硬件限制

- **滤波器数量**: 固定 8 个滤波器（MAX_EQ_BANDS = 8）
- **模式数量**: 支持 0-9 共 10 个模式（模式含义以固件定义为准）
- **采样率支持**: 44.1kHz, 48kHz, 88.2kHz, 96kHz, 176.4kHz, 192kHz（设备能力，与协议字段独立）

**参数范围**

| 参数 | 范围 | 格式 |
|:----:|:----:|:----:|
| 中心频率 (freq) | 20Hz - 20kHz | float（小端） |
| Q值 (q) | 0.1 - 30.0 | float（小端） |
| 带宽 (bw) | 1Hz - 20kHz | float（小端） |
| 增益 (gain) | -24dB - +24dB | float（小端） |
| 整体增益 (mode gain) | -50dB - 0dB | int32（小端） |

四、预设模式定义 :material-equalizer:

4.1 模式分类

模式索引	模式名称	用途描述	类型
0	JAZZ	爵士音乐优化	预设模式
1	POP	流行音乐优化	预设模式
2	ROCK	摇滚音乐优化	预设模式
3	ClASIC	古典音乐优化	预设模式
4	R&B	节奏音乐优化	预设模式
5	3A Game	3A游戏音乐优化	预设模式
6	FPS	FPS游戏音乐优化	预设模式
7	User 1	用户自定义模式1	用户模式
8	User 2	用户自定义模式2	用户模式
9	User 3	用户自定义模式3	用户模式

!!! info "模式特性说明" - 预设模式: 出厂预设，不可修改，针对特定音乐类型优化 - 用户模式: 支持用户自定义参数，可保存和重置

五、关键特性 :material-star:

5.1 设备端系数计算

• 主机只发送参数（freq/q/bw/gain）
• 设备端根据参数实时计算滤波器系数

5.2 参数格式

• 浮点参数：freq、q、bw、gain 使用 IEEE 754 float（小端序）
• 整体增益：int32（小端序，范围 -50dB ~ 0dB）

5.3 错误处理

• 数据包长度检查
• 同步头验证
• 参数范围检查
• 滤波器索引边界检查

5.4 模式管理

• 支持 EQ 模式切换与保存
• 模式切换后建议通过读取命令进行状态同步

六、注意事项 :material-alert:

1. 时序要求: 发送参数后需要等待设备处理完成再发送下一条命令
2. 数据完整性: 所有8个滤波器的参数都需要发送，即使某些滤波器未使用
3. 模式同步: 设置模式后建议调用读取模式确保数据同步
4. 错误恢复: 通信失败时需要重新建立连接并重试
5. 参数验证: 设备端会验证参数范围，超出范围的值会被限制或拒绝

---

咨询反馈

点击展开咨询反馈表单

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