hsk protocol Release:2022.03.01

1.版本记录

增加index字段,调整DevAddr顺序

版本V2.0 alpha2 内部版本,未发布

修改物理层协议

版本V2.0 alpha1 内部版本,未发布

调整命令,模块数据大小,增加返回CMD跟结果,增加外设模块跟存储器模块

版本V2.1 内部版本,未发布

2.名词解释

FX: special effect for sound

HKS: HANMUS karaoke system

INT16 INT32 数据格式的数据所有都是高字节在前低字节在后传输

3.用户须知

HKS 主要针对工厂自定义效果板应用, 要求工厂必须具体MCU开发能力, 否则将不易使用该系列模块.

应用场景: HKS应用场景主要为KTV 设备.

4.信号流程图

5.通讯描述

5.1 硬件连接

主机(MASTER): 外部MCU/PC等, 以下简称MCU

从机(SLAVE): HANMUS KTV SYS[HKS], 以下简称HKS,连接如下图:

5.2 设备发现

HKS采用UART 与外部MCU通信, 从机收到正确数据帧后, 3ms内必须对主机作出响应, 但响应时间不包括传输时间. 为了兼容从机不同的处理能力, 而且达到最优的性能, 总是期望从机能够跑快一些, 但实际上从机不同的应用处理器,支持的UART 能力不尽相同, 因此,我们在协议上制定了灵活的标准, 通过主机探测来兼容不同的从机速度, 物理上, 从机能够支持以下格式中的一种,如下表:

SPEED	Baud rate	Verify)	Word len	stop bit
NORMAL	115200	N	8	1
X2	230400	N	8	1
X4	460800	N	8	1
X8	921600	N	8	1
SPEED	2000000	N	8	1

5.3 协议管理

HKS通信协议分为3层管理,各层之间是独立的,互不制约,事实上,第一层, 第二层协议适用于HANMUS大部分产品通信, 不同的是应用层的内容,类似于, 你可以收到纸质信件或EMAIL信件, 同时, 你也可以用纸质信件给任何人写信, 只要我们愿意,用这个协议去传输一部电影也是可以的. 三层结构如下:

第一层为物理层,可以是USB, UART, BLE, WIFI, ETHERNET;

第二层为传输层,负责协议帧打包,解包,检查数据帧完整性以及正确性, 允许数据帧传输出现断续,重传;

第三层为应用层, 这是应用程序看到的数据层, 业务数据在这里处理。

5.4 传输层数据结构

采用数据流的方式传输,允许数据断续, 重传. 协议规定0xF0-0xFF 为协议关键字, 除了SOF, EOF外，任何地方出现的关键字，将在传输层转换为0xF0+N, 发送出去, 并在接收端将SOF, EOF以外的所有关键字恢复出来. 帧结构为:

SECTION	SOF	ADDR	INDEX	LEN	payload	checkout
LEN(bytes)	1	1	1	1	LEN	2
DATA	0x55	00-FF	00-7F	01-FF	ANY	[u16]SUM

6.设备连接

6.1 握手设备[01]

说明:为了快速探测设备是否在线, 这是一条短命令, 仅包含一个命令字[0x01], 无参数.

主机发送: [55 A3 01 01 01 00 FB]

[55]: 帧头(SOF);

[A3]: 从设备地址;

[01]: 发送端帧序号;

[01]: 数据包长度为1字节;

[01]: 数据包首字节, 首字节为命令字, 01 代表握手设备;

[00 FB]: 校验和SUM(55 A3 01 01 01);

从机应答: [55 A3 01 05 01 00 00 00 00 00 FF]

[55]: 帧头(SLAVE SOF);

[A3]: 从设备地址;

[01]: 应答帧序号跟发送帧序号一致;

[05]: 数据包长度为5字节;

[01]: 命令字返回

[00 00 00 00]: 发送结果, 0x00表示握手成功

[00 FF]: 校验和XOR(55 A3 01 05 01 00 00 00 00);

6.1 系统描述符[10]

本协议的独特之处是,不限定描述符的长度与描述符的数量,这个特点能够让不同的设备型号共用同一个主机程序, 同样一个设备也可以连接到不同版本的主机程序, 极大程度方便主机程序,设备程序的升级与维护, 全面提升互相的兼容性. 在主机端从头开始获取描述符, 直至获取完所有描述符, 然后主机根据不同的描述符ID解析数据表, 从而获得设备的所有属性, 如果旧版本的主机程序遇到不认识的新描述符或不支持的功能,直接跳过,不加于处理即可. 这个过程类似于键盘或U盘插入电脑后,由不同的驱动伺服; 或3键鼠标与多键鼠标插入电脑都能够正常使用. 使用本协议的不同类型或不同功能的设备，也能拥有如此强大的兼容性.

如此强大的兼容性,主要归功于设备在连接时提交的各种描述符,描述符中会描述当前设备名称、版本、设备类型以及能够支持的数据包最大长度, 同时还会提供当前设备的各种属性,如音频通道数量、支持几通道EQ、是否支持压缩器、动态扩展器、效果器等. 都可以在描述符中得到, 然后这些属性都将成为主机访问设备的配置信息.

描述符还会提供一个客户编号以及产品编号, 这两个ID是唯一的,主机程序遇到相同的设备,可以通过ID去限制是否伺服此设备.

描述符还提供强大的字符串功能, 设备名称、通道名称、以及描述符的名字都会记录在字符串描述中,而不同的通道, 描述符可以通过自己的字符串ID在字符串描述符中获取到相应的字符串.

以下为字描述符获取,解析各个描述符实例:

主机发送: [55 A3 02 02 10 00 10 0C]

[55]: 帧头(SOF);

[A3]: 从设备地址;

[02]: 帧序号;

[02]: 数据包长度为2字节;

[10]: 数据包首字节, 首字节为命令字, 10代表获取描述符;

[00]: 数据包第二字节, 这里只指明,需要第几个描述符,而不指定描述符的类型, 而事实上,不同的案子,描述符的顺序可能是不一样的,而且,描述符的数量也可以不一样的.

00: 查询设备第一张描述符;

01: 代表第二张描述符,

02: 代表第三张描述符

主机可以一直查询下去, 直到返回空描述符.

[10 0C]: 校验和SUM(55 A3 02 02 10 00);

从机应答:

从机应答是一张描述符,而这张描述符的类型是不确定的,需要主机根据描述符ID去处理当前表的内容,以下列出几个返回示例:

描述符ID	类型	说明
0x11	设备描述符	包括了设备名称、版本,客户编号等
0x12	系统配置描述符	包括了采样频率,以及一些内部调试信息
0x13	项目配置描述符	包括了产品的输入,输出通道数量

示例1: 返回设备描述符, 描述符ID:0x11

[55 A3 02 25 10 00 00 00 00 20 11 02 01 00 01 00 33 47 21 47 01 00 02 21 11 22 01 03 FF 40 00 12 34 56 78 00 00 00 00 00 00 04 F4 ]

[55]: 帧头(SLAVE SOF);

[A3]: 从设备地址;

[02]: 应答帧序号跟发送帧序号一致;

[25]: 数据包长度为33字节;

[10]: 数据包首字节, 首字节为命令字, 10代表获取描述符命令;

[00 00 00 00]:返回结果[高位在前,低位在后] 0x00表示读取成功

[20]: 该描述符长度,包含本字段; //32字节

[11]: 当前描述符ID, 0x11 表示当前返回为设备描述符;

[02]: 设备名称字符串ID

[01]: 设备大类,01 表示KTV , 此类设备支持效果器;

[00]: 设备子类编号;

[01]: 通信协议主版本号, BCD编码, 01表示 v1.0;

[00]: 通信协议子版本号, BCD编码, 00表示 v0.0;

[33 47]: USB VID;

[21 47]: USB PID;

[01]: 软件主版本号(Major), BCD编码;

[00]: 软件次版本号(Minor), BCD编码;

[02]: 软件次版本号,修改号(Sub-minor), BCD编码;

[21 11 22 01]: 软件编译日期, BCD码表示

[03 FF]: 通信最长数据包, 在通信中,发送的最大长度,不可以超过这个数值, 否则可

能导致无法响应, 需要注意的是,协议中采用了规避关键字。

[40]: 字符串描述符中,每个字符串最大的长度, 供主机在申请内存时,无需要申请过大

内存,协助主机编程节省内存空间.

[00]: 字符串描述符编码客户,为1时为UNICODE编码;

[12 34 56 78 ]: 设备ID;

[00 00 00 00 00 00]: 保留

[04 F4]: 校验和SUM(55 A3 02 25 10 … 00 00 );

示例2: 返回系统配置描述符, 描述符ID:0x12

[55 A3 03 02 10 01 01 0E]

[55 A3 03 25 10 00 00 00 00 20 12 03 02 00 00 00 00 00 00 BB 80 BB 80 BB 80 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 05 18 ]

[55]: 帧头(SLAVE SOF);

[A3]: 从设备地址;

[03]: 应答帧序号跟发送帧序号一致;

[25]: 数据包长度为37字节;

[10]: 数据包首字节, 首字节为命令字, 10代表获取系统配置;

[00 00 00 00]:返回结果[高位在前，低位在后] 0x00表示读取成功

[20]: 该描述符长度，包含本字段; 32字节

[12]: 代表当前为系统配置描述符;

[03]: 系统配置描述符字符串ID

[02 00 00 00 00 00 00 ]: 内部测试使用, 系统保留，忽略此内容;

[BB 80]: 系统最低采样率;

[BB 80]: 系统最高采样率;

[BB 80]: 系统默认采样率;

[00 … 00]: 保留

[05 18]: 校验和SUM(55 A3 03 25 10 … 00 00 00);

示例3: 返回项目配置描述符, 描述符ID:0x13

[55 A3 04 02 10 02 01 10]

[55 A3 04 25 10 00 00 00 00 20 13 04 04 06 00 00 02 02 12 01 04 02 00 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 01 92]

[55]: 帧头(SLAVE SOF);

[A3]: 从设备地址;

[04]: 应答帧序号跟发送帧序号一致;

[25]: 数据包长度为37字节;

[10]: 数据包首字节, 首字节为命令字, 10代表获取系统配置;

[00 00 00 00]:返回结果[高位在前,低位在后] 0x00表示读取成功

[20]: 该描述符长度,包含本字段; 32字节

[13]: 代表当前为项目配置描述符;

[04]: 项目配置描述符字符串ID

[04 06]: 信号处理单元输入,输出通道数量;

[00 00]: USB声卡输入,输出通道数量,发送给电脑主机的通道数量;

[02 02]: 本地模拟输入,输出通道数量;

[12]: 总通道数量 18

[01]: MonoBus 数量

[04]:效果器通道数量

[02]:MainBus通道数量

[00]:MixerBus通道数量

[03]: 支持效果类型总数,03 代表本系统共03种效果类型;

[00 … 00]: 保留

[01 92]: 校验和SUM(55 A3 04 25 10 … 00 00);

示例4: 返回空描述符

[55 A3 06 02 10 04 01 14]

[55 A3 06 05 10 00 00 00 10 01 23]

[55]: 帧头(SLAVE SOF);

[A3]: 从设备地址;

[06]: 应答帧序号跟发送帧序号一致;

[05]: 数据包长度为5字节;

[10]: 数据包首字节, 首字节为命令字, 10代表获取系统配置;

[00 00 00 10]:返回结果[高位在前，低位在后] 0x10表示空描述符

[01 23]: 校验和SUM(55 A3 05 25 10 … 00 00);