phaten-audio/zh/docs/dev_doc/protocols/XMOS_EQ_HID_Protoco.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	FIRMWARE_UPGRADE_START	开始固件升级	PC → 设备
0xA8	FIRMWARE_UPGRADE_DATA	传输固件数据块	PC → 设备
0xA9	FIRMWARE_UPGRADE_END	结束固件升级	PC → 设备
0xAA	FIRMWARE_UPGRADE_STATUS	获取升级状态	PC ↔ 设备
0xAB	FIRMWARE_UPGRADE_ABORT	中止固件升级	PC → 设备
0xAC	FIRMWARE_UPGRADE_ERASE	擦除升级镜像	PC → 设备
0xAE	DEVICE_REBOOT	设备重启	PC → 设备
0xB3	SET_EQ_BAND_COUNT	设置 EQ 段数	PC → 设备
0xB4	GET_EQ_BAND_COUNT	获取 EQ 段数	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, 小端序，范围 -50dB ~ 0dB）
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-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）
• 每级约2dB的衰减变化

设备端处理:

• 参数会通过现有的定时保存机制自动保存到Flash
• 如果参数超出范围（>60），固件将拒绝设置并返回false

返回值: 无直接返回值。如需确认音量是否设置成功，请使用 GET_VOLUME (0x94) 命令读取。

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）

LED 状态枚举:

• 0: LED_STATUS_OFF (熄灭)
• 1: LED_STATUS_SOLID (常亮)
• 2: LED_STATUS_SLOW_BLINK (慢闪)
• 3: LED_STATUS_FAST_BLINK (快闪)
• 4: LED_STATUS_BREATHE (呼吸)

!!! note - RGB颜色值基于当前LED颜色定义转换（低电平有效） - LED状态基于当前LED显示模式（常亮/闪烁）判断

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	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	1	saved_mode	保存的模式值（0-9，0xFF 表示未保存）
5-63	59	reserved	保留字段（填充0）

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

功能说明: 读取当前采样率、DSD 模式和 DAC 采样分辨率

请求格式（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	sample_rate	采样率（uint32, 小端序，单位：Hz）
7	1	dsd_mode	DSD 模式（0=PCM, 1=DOP, 2=Native DSD）
8-62	55	reserved	保留字段（填充0）

自动上报机制:

• 设备中监控采样率和 DSD 模式的变化
• 当这些值发生变化时，设备会自动构建 0x9F 响应数据包并通过 HID 状态报告上报
• 主机可以通过 HID GET_REPORT 接收这些自动上报的状态变化

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）

参数说明:

• 0: 低阻模式（适合高灵敏度耳机）
• 1: 高阻模式（适合高阻抗耳机）

返回值: 无直接返回值。如需确认增益模式是否设置成功，请使用 GET_GAIN_MODE (0xA1) 命令读取。

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）

功能说明: 设置 DAC 数字滤波器模式

请求格式（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

返回值: 无直接返回值。如需确认滤波器模式是否设置成功，请使用 GET_FILTER_MODE (0xA3) 命令读取。

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）

游戏模式定义:

• 0: 无音效（标准立体声）
• 1: FPS模式（增强定位感）
• 2: 虚拟7.1（环绕声效果）

返回值: 无直接返回值。如需确认游戏模式是否设置成功，请使用 GET_GAME_MODE (0xA5) 命令读取。

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 格式）
4	1	minor	次版本号（BCD 格式）
5	1	patch	修订版本号（BCD 格式）
6-63	58	reserved	保留字段（填充0）

版本号格式说明:

• 版本号采用 BCD（Binary Coded Decimal）格式
• 3个字节分别表示：主版本号、次版本号、修订版本号
• 例如：0x01 0x00 0x0C 表示版本 1.0.12

2.2.30 开始固件升级（0xA7）

功能说明: 启动固件升级流程，发送固件大小并获取升级参数

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	report_id	固定为 0x01
1	1	sync_header	同步头: 0x77
2	1	cmd_header	命令头: 0xA7
3-6	4	fw_size	固件大小（字节，uint32, 小端序）
7-63	57	reserved	保留字段（填充0）

响应格式（64 字节）（主动上报）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xA7
2	1	status	状态码（0x00=成功, 0x01=失败, 0x03=大小无效）
3-6	4	aligned_size	页对齐后的实际大小（uint32, 小端序）
7-8	2	total_blocks	总块数（uint16, 小端序）
9-63	55	reserved	保留字段（填充0）

2.2.31 传输固件数据块（0xA8）

功能说明: 传输固件数据块，每块固定 57 字节

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xA8
2-3	2	block_num	块序号（从0开始，uint16, 小端序）
4	1	data_len	数据长度（固定57）
5-61	57	data	固件数据（57字节）
62	1	checksum	Checksum（字节0-61累加 mod 256）

响应格式（64 字节）（主动上报）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xA8
2	1	status	状态码（0x00=成功, 0x04=块号错误, 0x05=Checksum错误）
3-4	2	ack_block	已确认块序号（uint16, 小端序）
5-63	59	reserved	保留字段（填充0）

2.2.32 结束固件升级（0xA9）

功能说明: 完成固件传输，验证镜像完整性

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xA9
2-5	4	fw_size	固件总大小（用于验证，uint32, 小端序）
6-63	58	reserved	保留字段（填充0）

响应格式（64 字节）（主动上报）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xA9
2	1	status	状态码（0x00=成功, 0x01=失败）
3-63	61	reserved	保留字段（填充0）

2.2.33 获取升级状态（0xAA）

功能说明: 查询升级状态、进度、已接收块数等信息

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xAA
2-63	62	reserved	保留字段（填充0）

响应格式（64 字节）（主动上报）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xAA
2	1	status	升级状态（0=空闲, 1=准备中, 2=传输中, 3=完成中, 4=已完成, 5=错误, 6=已中止）
3-4	2	received_blocks	已接收块数（uint16, 小端序）
5-6	2	total_blocks	总块数（uint16, 小端序）
7-8	2	written_pages	已写页数（uint16, 小端序）
9-10	2	total_pages	总页数（uint16, 小端序）
11-14	4	received_bytes	已传输字节数（uint32, 小端序）
15-18	4	total_bytes	总字节数（uint32, 小端序）
19	1	error_code	错误码
20-63	44	reserved	保留字段（填充0）

升级状态枚举:

• 0: IDLE (空闲)
• 1: PREPARING (准备中)
• 2: TRANSFERRING (传输中)
• 3: FINALIZING (完成中)
• 4: COMPLETED (已完成)
• 5: ERROR (错误)
• 6: ABORTED (已中止)

2.2.34 中止固件升级（0xAB）

功能说明: 中止当前升级流程，可选择是否擦除已传输数据

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xAB
2	1	erase_flag	清理标志（0x00=保留数据, 0x01=擦除数据）
3-63	61	reserved	保留字段（填充0）

响应格式（64 字节）（主动上报）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xAB
2	1	status	状态码（0x00=成功）
3-63	61	reserved	保留字段（填充0）

2.2.35 擦除升级镜像（0xAC）

功能说明: 擦除 Flash 中现有的升级镜像

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xAC
2-63	62	reserved	保留字段（填充0）

响应格式（64 字节）（主动上报）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xAC
2	1	status	状态码（0x00=成功）
3-63	61	reserved	保留字段（填充0）

2.2.36 设备重启（0xAE）

功能说明: 立即重启设备

请求格式（64 字节）:

偏移	长度	字段名	描述
0	1	sync_header	同步头: 0x77
1	1	cmd_header	命令头: 0xAE
2-63	62	reserved	保留字段（填充0）

响应: 无响应，设备立即重启。

2.2.37 设置 EQ 段数（0xB3）

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

请求格式（64 字节）:

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

EQ 段数定义:

• 8: 仅 Core0 参与处理
• 16: Core0 + Core1 参与处理
• 24: Core0 + Core1 + Core2 参与处理
• 32: 全部 4 个 Core 参与处理

设备端处理:

• 仅接受 8、16、24、32 四个有效值，其他值拒绝
• 设置后保存到 Flash（独立文件 eq_band_cnt），开机时自动恢复
• 设置后触发参数同步到 tile1，tile1 上未参与处理的 Core 对音频做透传（bypass）

响应格式（64 字节）:

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

2.2.38 获取 EQ 段数（0xB4）

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

请求格式（64 字节）:

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

响应格式（64 字节）:

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

2.2.39 设置采样率升频（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.40 获取采样率升频（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.1.4 固件升级流程

1. GUI发送 FIRMWARE_UPGRADE_START 命令 (0xA7)，发送固件大小
2. 设备返回页对齐后大小和总块数
3. GUI循环发送 FIRMWARE_UPGRADE_DATA 命令 (0xA8) 传输固件数据块
4. 传输完成后发送 FIRMWARE_UPGRADE_END 命令 (0xA9) 结束升级
5. 设备验证镜像完整性并返回状态

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	CLASSIC	古典音乐优化	预设模式
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"