灵越上下位机通讯协议
-
《玄雅·灵越上下位机通讯协议》正在持续优化和迭代中。如在实际使用过程中发现与本协议存在版本不一致的情况，请与我们联系，我们将第一时间为您提供所需的技术支持；
-
本协议中的所有数值统一采用十进制或十六进制表示，其中以0x标识的数据为十六进制数，未有标识的数据一律为十进制数；
-
本协议适用于所有购买玄雅·灵越系列产品的用户。
上一次修改时间：2025年9月23日
1. 玄雅通讯协议基本构成
《玄雅·灵越上下位机通讯协议》是一种适用于多种通信方式的数据传输协议，采用固定帧格式设计，旨在确保数据传输过程中的稳定性与可解析性。协议数据帧由以下字段组成：
指令格式：
| 帧头 | 指令 | 数据长度 | 参数 | 数据 | 校验 | 帧尾 |
|---|---|---|---|---|---|---|
0xAA | 指令ID | length | function | data1 ~ dataN | check | 0xFF |
-
帧头：固定为
0xAA，数据帧的起始位置。 -
指令：控制指令 ID，每个ID对应一种特定的控制逻辑或数据格式，便于程序在接收时动态匹配处理流程。
-
指令长度：等于数据的长度 N 加上1，即 “N+1”。
-
参数：每个指令中有不同的功能，各功能对应不同参数。
-
数据：
-
校验位：校验 Check，计算方式：Check = (function + data1 +...data N) % 2。
-
帧尾：固定为
0xFF，数据帧的结束位置
2. 关节控制指令
关节控制帧的指令ID为 0x06 ，该指令包含3个功能分别是获取左右臂即夹爪角度数据、控制右臂关节角度和控制左臂关节角度。
2.1 关节数据获取指令
- 功能：获取左右臂关节及左右夹爪数据。
- 指令：
0x06 - 参数：
0x00 - 数据长度：
0x01 - 数据：无
- 机制：灵越的数据获取方式是应答式，即发送一次数据获取帧，回复一次关节数据。
- 校验：
check = (参数 + 数据) % 2
示例：获取关节和夹爪的角度数据。
| 帧头 | 指令 | 数据长度 | 参数 | 校验 | 帧尾 |
|---|---|---|---|---|---|
0xAA | 0x06 | 0x01 | 0x00 | 0x00 | 0xFF |
2.2 数据获取应答帧
- 功能：反馈左右臂关节数据和夹爪开合角度。
- 指令；
0x06 - 数据长度：
0x21 - 参数：
0x38 - 数据：一共32字节，前14个字节是右臂的七个关节角度，15-28字节是左臂的七个关节角度，最后四个字节是右臂和左臂夹爪的角度数据。
- 机制：在发送数据获取帧之后就会回应一帧数据应答帧。
- 校验：
check = (参数 + 数据) % 2
示例：回复左右臂关节角度和夹爪角度。
| 帧头 | 指令 | 数据长度 | 参数 | 数据 | 校验 | 帧尾 |
|---|---|---|---|---|---|---|
0xAA | 0x06 | 0x21 | 0x38 | 04 08 FE 07 FC 07 FF 03 00 08 03 08 02 08 03 08 FE 07 02 08 FE 07 FD 07 FE 07 01 08 B7 07 44 0B | 0x00 | 0xFF |
2.3 关节控制指令
- 功能：控制右边机械臂的各关节角度。
- 指令；
0x06 - 数据长度：
0x0F - 参数：
0x01表示右侧机械臂，0x02表示左侧机械臂。 - 数据：一共14字节，机械臂的7个关节角度。
- 校验：
check = (参数 + 数据) % 2
示例：设置右臂各关节角度
| 帧头 | 指令 | 数据长度 | 参数 | 数据 | 校验 | 帧尾 |
|---|---|---|---|---|---|---|
0xAA | 0x06 | 0xF | 0x01 | 00 07 00 08 00 08 00 08 00 08 00 08 00 08 | 0x01 | 0xFF |
3 夹爪控制帧
夹爪控制帧用于单侧或双侧夹爪的开合角度控制，指令 ID 为 0x02。
3.1 夹爪控制指令
- 功能：控制左右夹爪的目标角度。
- 指令：
0x02 - 参数：
0x01表示右侧夹爪，0x02表示左侧夹爪。（后续如扩展双侧同时控制，可使用其它识别值） - 数据长度：识别字节 + 2 字节目标角度，共 3 字节，对应长度字段值：
0x03。 - 数据：2 字节角度值，低位在前，高位在后，表示单个夹爪目标角度。
- 校验：
check = (参数 + 数据) % 2
示例：设置右侧夹爪角度（角度值示例为 0x0800，按小端发送为 00 08）
| 帧头 | 指令 | 数据长度 | 参数 | 数据 | 校验 | 帧尾 |
|---|---|---|---|---|---|---|
0xAA | 0x02 | 0x03 | 0x01 | 00 08 | 0x01 | 0xFF |
4 设置零点指令帧
设置零点指令帧用于将机械臂当前姿态标定为零点，指令 ID 为 0x03。
4.1 零点设置指令
- 功能：设置左/右或双侧机械臂的零点基准。
- 指令：
0x03 - 数据长度：
0x01。 - 参数：
0x01右侧零点；0x02左侧零点；0x03双侧同时设置零点。 - 校验：
check = (参数) % 2
示例：设置右侧机械臂零点
| 帧头 | 指令 | 数据长度 | 参数 | 校验 | 帧尾 |
|---|---|---|---|---|---|
0xAA | 0x03 | 0x01 | 0x01 | 0x01 | 0xFF |
5 力矩开关指令帧
力矩开关指令用于打开或关闭机械臂伺服的力矩输出，指令 ID 为 0x13。
5.1 力矩开关控制
- 功能：控制左右或双侧机械臂的力矩使能状态。
- 指令：
0x13 - 数据长度：
0x02。 - 参数：
0x01右侧；0x02左侧；0x03双侧同时设置。 - 数据：
0x00关闭力矩；0x01打开力矩。 - 校验：
check = (参数 + 数据) % 2
示例：打开右侧机械臂力矩
| 帧头 | 指令 | 数据长度 | 参数 | 数据 | 校验 | 帧尾 |
|---|---|---|---|---|---|---|
0xAA | 0x13 | 0x02 | 0x01 | 0x01 | 0x00 | 0xFF |
6 云台控制指令帧
云台控制指令用于控制云台的两个轴角度（X / Y），指令 ID 为 0x14。
6.1 云台角度控制
- 功能：设置云台 X 轴与 Y 轴目标角度。
- 指令：
0x14 - 数据长度：
0x04。 - 数据：共 4 字节，前 2 字节为 X 轴角度（低位在前，高位在后），后 2 字节为 Y 轴角度（低位在前，高位在后）。
示例：X 轴角度 0x0800，Y 轴角度 0x0800
| 帧头 | 指令 | 数据长度 | 数据 (X_L X_H Y_L Y_H) | 校验 | 帧尾 |
|---|---|---|---|---|---|
0xAA | 0x14 | 0x04 | 00 08 00 08 | 0x00 | 0xFF |