玄雅·灵动上下位机通讯协议

阅读指南

《玄雅·灵动/灵越上下位机通讯协议》正在持续优化和迭代中。如在实际使用过程中发现与本协议存在版本不一致的情况，请与我们联系，我们将第一时间为您提供所需的技术支持；
本协议中的所有数值统一采用十进制或十六进制表示，其中以0x标识的数据为十六进制数，未有标识的数据一律为十进制数；
本协议适用于所有购买玄雅·灵动系列产品的用户。

上一次修改时间：2025年5月23日

1. 玄雅通讯协议基本构成

《玄雅·灵动上下位机通讯协议》是一种适用于多种通信方式的数据传输协议，采用固定帧格式设计，旨在确保数据传输过程中的稳定性与可解析性。协议数据帧由以下字段组成：帧头、指令 ID、指令长度、控制指令、校验位、帧尾，通讯波特率为921600：

1.1 帧头

长度：1 Byte；
取值：固定为 0xAA；
功能：标志数据帧的起始位置。

1.2 指令 ID

长度：1 Byte；
取值：依实际协议设计而定（参阅第2章节），可表示控制机械臂、读取机械臂数据等；
功能：每个指令 ID 对应一种特定的控制逻辑或数据格式，便于程序在接收时动态匹配处理流程。

1.3 指令长度

长度：1 Byte；
取值：一个无符号的十六进制整型值，范围为 0x00→0xFF；
功能：指明控制指令字段的长度，用于确定数据帧中控制数据的边界。

1.4 控制指令

长度：由指令长度字段决定，即[指令长度] Byte；
取值：具体的控制数据，该部分的解析方式由1.2所述的指令ID字段决定；
功能：携带需要执行或传输的数据内容。

1.5 校验位

长度：1 Byte；
取值：将控制指令字段的所有字节求和，对 2 取模（即 sum(payload) % 2）；
功能：用于数据包的简单错误检测，若校验失败，接收方可拒绝该数据帧。

1.6 帧尾

长度：1 Byte；
取值：固定为 0xFF；
功能：标志数据帧的结束位置。

2. 指令ID查询表

本章节将阐述不同的指令ID及其对应的指令长度、控制指令的定义。

2.1 指令ID = 0x02 （夹爪控制与反馈）

2.1.1 发送帧

字段	值与释义
指令ID与功能	`0x02`（执行夹爪的行程控制与行程反馈）
指令长度	`0x03`
控制指令	`<套件标识><夹爪发送量程值1><夹爪发送量程值2>`

1. 套件标识:

<套件标识>：一般为<0x01>。

2. 夹爪发送量程值:

<夹爪发送量程值1><夹爪发送量程值2>：共同控制夹爪舵机的开合动作，取值范围为<0x00><0x08>（夹爪舵机处于全开状态）至<0xDA><0x0C>（夹爪舵机处于全闭状态），即十进制下的2048（夹爪舵机全开状态）至3290（夹爪舵机全闭状态）；
<夹爪发送量程值1>：整体发送取值的低8位；
<夹爪发送量程值2>：整体发送取值的高8位。

2.1.2 应答帧

字段	值与释义
指令ID与功能	`0x02`（执行夹爪的行程控制与行程反馈）
指令长度	`0x07`
控制指令	`<套件标识><夹爪应答量程值1><夹爪应答量程值2><电位计应答量程值1><电位计应答量程值2><同步按键><姿态按键>`

1. 套件标识

<套件标识>：一般为<0x01>。

2. 夹爪应答量程值

<夹爪应答量程值1><夹爪应答量程值2>：表示夹爪舵机当前位置所对应的量程值；
<夹爪应答量程值1>：一般情况下等于<夹爪发送量程值1>，但在实际运行中可能存在微小偏差；
<夹爪应答量程值2>：一般情况下等于<夹爪发送量程值2>，但在实际运行中可能存在微小偏差。

3. 电位计应答量程值

<电位计应答量程值1><电位计应答量程值2>：表示示教臂握把电位计当前位置所对应的量程值；
<电位计应答量程值1>：在示教臂→操作臂同步状态下等于<夹爪应答量程值1>，但在实际运行中可能存在微小偏差；在非同步状态下可能为自由值；
<电位计应答量程值2>：在示教臂→操作臂同步状态下等于<夹爪应答量程值2>，但在实际运行中可能存在微小偏差；在非同步状态下可能为自由值。

4. 同步按键

<同步按键>：用来判断示教臂→操作臂之间是否同步，取值为<0x00>时表示同步按键未被按下；取值为<0x01>时表示同步按键被按下。

5. 姿态按键

<姿态按键>：用来判断示教臂的控制姿态是否被锁定，取值为<0x00>时表示控制姿态按键未被按下；取值为<0x01>时表示控制姿态按键被按下。

示例：将夹爪完全闭合的操作方式

在该场景下，用户需将夹爪的发送量程值设置为十六进制0x0CDA（对应十进制值3290，表示夹爪完全闭合状态），因此有：

（一）发送帧

| 0xAA | 0x02 | 0x03 | 0x01 | 0xDA | 0x0C | 0x00 | 0xFF |

自左向右注释如下：

0xAA：帧头；

0x02：指令ID；

0x03：数据长度，表示发送的数据长度是3字节；

0x01：套件标识，为1号；

0xDA：夹爪发送量程值的低八位，即0x0CDA的DA；

0x0C：夹爪发送量程值的高八位，即0x0CDA的0C；

0x00：校验位；

0xFF：帧尾。

（二）应答帧

| 0xAA | 0x02 | 0x07 | 0x01 | 0xDA | 0x0C | 0xDA| 0x0C | 0x01 | 0x01 | 0x01 | 0xFF |

自左向右注释如下：

0xAA：帧头；

0x02：指令ID；

0x07：数据长度，表示应答的数据长度是7字节；

0x01：套件标识，为1号；

0xDA：夹爪应答量程值低八位，在该场景下与夹爪发送量程值的低八位应当相同；

0x0C：夹爪应答量程值高八位，在该场景下与夹爪发送量程值的高八位应当相同；

0xDA：电位计应答量程值的低八位，在该场景下与夹爪应当量程值的低八位应当相同；

0X0C：电位计应答量程值的高八位，在该场景下与夹爪应当量程值的高八位应当相同；

0X01：同步按键状态为0，表示该键已被按下；

0X01：姿态按键状态为1，表示该键已被按下；

0x01：校验位；

0xFF：帧尾。

2.2 指令ID = 0x03（机械臂调零）

字段	值与释义
指令ID与功能	`0x03`（机械臂以当前位置为零点）
指令长度	`0x01`（固定为1字节长度）
控制指令	`<0x00>`

注意： 本指令仅有发送帧而无应答帧。

2.3 指令ID = 0x04（机械臂角度控制与反馈）

字段	值与释义
指令ID与功能	`0x04`（执行机械臂的角度控制与角度反馈）
指令长度	`0x12`（固定为18字节长度）
控制指令	`<舵机量程值1><舵机量程值2>...<舵机量程值N>`（N = 18）

注意： 指令发送帧与应答帧格式完全相同。

1. 舵机对应关系

<量程值1><量程值2>默认对应舵机ID1，<量程值3><量程值4>对应舵机ID2，以此类推至第9个舵机（灵动操作臂的臂身共包含9个舵机）。

2. 度转化量程值的计算方法

设目标角度为 θ（单位：度°），则对应的角度值计算如下（计算结果需向上取整）：

角度换算量程值= 4095 / 360 × θ。

接着，将该16位角度值拆分为两个字节，例如：

<舵机量程值1> =角度换算量程值 & 0xFF；
<舵机量程值2> = 角度换算量程值 >> 8) & 0xFF。

示例：控制ID1舵机转至45°

在该场景下：

角度换算量程值= 4095 / 360 × 45 = 511.875，向上取整为511；
511 = 0x01FF；
<舵机量程值1> = 0xFF，即低八位；
<舵机量程值2> = 0x01，即高八位。

2.4 指令ID = 0xEE（错误反馈）

字段	值与释义
指令ID与功能	`0xEE`（表示错误反馈 EOR）
指令长度	`0x02`（固定为1字节长度）
控制指令	`<错误码><附加信息>`

注释： 指令仅有应答帧而无发送帧。。

1. 错误码

错误码含义解释：

0x00：帧头/帧尾或长度错误；

0x01：校验错误；

0x02：模式错误；

0x03：舵机ID无效。

2. 附加信息

针对（一）中所列各错误码，会分别产生以下附加信息：

0x00：会附加错误的指令id；

0x01：会附加所计算的错误校验位；

0x02：会附加当前的错误模式；

0x03：会附加无效的舵机ID。