.. _topics-hsk: ======================================== 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.信号流程图 =============== .. image:: ../images/signalLogic.jpg 5.通讯描述 =============== 5.1 硬件连接 ------------- 主机(MASTER): 外部MCU/PC等, 以下简称MCU 从机(SLAVE): HANMUS KTV SYS[HKS], 以下简称HKS,连接如下图: .. image:: ../images/hardwareConnect.jpg 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信件, 同时, 你也可以用纸质信件给任何人写信, 只要我们愿意,用这个协议去传输一部电影也是可以的. 三层结构如下: .. image:: ../images/protocollayer.jpg 第一层为物理层,可以是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);