Version: 6.0.0 (Latest)

灵动上下位机通讯协议

阅读指南

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

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

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

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

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><同步按键><姿态按键>`

注意： 仅v5.5时应答帧指令ID为0x14。

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 | 0x01 | 0xFF |

自左向右注释如下：

0xAA：帧头；

0x02：指令ID；

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

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

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

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

0x01：校验位。

0xFF：帧尾。

（二）应答帧

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

自左向右注释如下：

0xAA：帧头；

0x12：指令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`，接收为`0x14`
指令长度	`0x12`（固定为18字节长度）
控制指令	`<舵机量程值1><舵机量程值2>...<舵机量程值N>`（N = 18）

注意： 指令发送帧与应答帧格式仅指令ID不相同。

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 = 0x05（机械臂参数更改）

字段	值与释义
指令ID与功能	`0x05`（机械臂参数更改）
指令长度	不定长度（根据参数内容变化）
控制指令	`<参数类型><参数内容...>`

控制指令说明：

<参数类型>：1字节，指定要更改的参数内存地址（如 0x15、0x16、0x17、0x29、0x2E、0x38 等，详见下表和代码定义）。
<参数内容...>：长度和内容依参数类型而定。
- 若为 PID 参数（如 0x15、0x16、0x17），则后续为各舵机的参数值，长度为 舵机数量 字节。
- 若为加速度（0x29）、速度（0x2E）、位置（0x38）等，后续为各舵机的参数值，通常每个舵机2字节（低位在前，高位在后）。
- 具体参数内容和长度由 指令长度 字段给出。

典型流程：

控制端发送参数更改指令，指定参数类型和对应参数内容。
下位机根据参数类型，批量写入各舵机参数。
若参数非法或写入失败，下位机会通过 0xEE 错误反馈指令返回错误信息。

常用参数类型举例：

参数类型（内存地址）	说明
`0x15`	位置环比例系数P
`0x16`	位置环微分系数D
`0x17`	位置环积分系数I
`0x29`	加速度
`0x2E`	目标速度
`0x38`	目标位置

示例：

批量设置所有舵机的P参数：

| 0xAA | 0x05 | N | 0x15 | <P1> | <P2> | ... | <Pn> | <校验位> | 0xFF |

其中：

0x05：指令ID
N：指令长度（参数类型+参数内容长度）
0x15：P参数寄存器地址（十六进制）
<P1>...<Pn>：各舵机的P参数值

caution

警示： 根据寄存器表，0x05指令支持连续写入多个参数（如P、D、I），即参数类型字段可为起始寄存器地址，后续参数内容依次写入。例如：

| 0xAA | 0x05 | N*3 | 0x15 | <P1> | <D1> | <I1> | <P2> | <D2> | <I2> | ... | <Pn> | <Dn> | <In> | <校验位> | 0xFF |

此时，N为舵机数量，参数内容按寄存器顺序连续排列。请严格按照寄存器顺序和长度组织数据，避免写入异常。

注意：

本指令仅有发送帧而无应答帧。
若参数非法或写入失败，下位机会通过 0xEE 错误反馈指令返回错误信息。

2.5 指令ID = 0x0A（查询固件版本号）

字段	值与释义
指令ID与功能	`0x0A`（查询固件版本号）
指令长度	`0x03`（固定为3字节）
控制指令	`<主版本号><次版本号><修订号>`

应答帧格式：

| 0xAA | 0x0A | 0x03 | <主版本号> | <次版本号> | <修订号> | <校验位> | 0xFF |

<版本号>(data[3] >> 16) & 0xFF . (data[4] >> 8) &0xFF . data[5]

说明：

该指令为查询指令，主机发送0x0A后，下位机返回当前固件版本号。
校验位为前三个版本号字节求和后对2取模。

2.6 指令ID = 0x13（机械臂扭矩开关）

字段	值与释义
指令ID与功能	`0x13`（机械臂扭矩开关）
指令长度	`0x01`（固定为1字节）
控制指令	`<开关状态>`

<开关状态>：0x00 表示关闭扭矩，0x01 表示打开扭矩。

说明：

当处于非同步或高权限模式时，指令生效。
若为示教通信模式，数据会转发到相关接口。
本指令仅有发送帧，无应答帧。

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

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

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

1. 错误码

错误码含义解释：

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

0x01：校验错误；

0x02：模式错误；

0x03：舵机ID无效。

2. 附加信息

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

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

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

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

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