跳到主要内容

灵动上下位机通讯协议

阅读指南

  1. 本协议中的所有数值统一采用十进制或十六进制表示，其中以0x标识的数据为十六进制数，未有标识的数据一律为十进制数；

  2. 本协议适用于所有购买玄雅·灵动系列产品的用户。

上一次修改时间：2026年9月9日

1. 协议构成

灵系列产品的通讯协议由帧头、指令、功能码、数据长度、数据、校验、帧尾构成，通信波特率为 1000000。

字段说明示例/固定值
帧头数据帧的起始位置0xAA（固定）
指令控制指令ID，对应特定控制逻辑或数据格式，便于接收时动态匹配处理流程指令ID
功能码每个指令下的细分功能，各功能对应不同参数function
数据长度后续“数据”字段的长度length
数据关节的位置、速度、加速度或力矩数据data1 ~ dataN
校验对指令ID、功能码、数据长度及全部数据字节计算 CRC32，取低八位；不包含帧头和帧尾Check
帧尾数据帧的结束位置0xFF（固定）

1.1 指令ID与对应功能说明​

指令ID指令功能
0x01查询机器类型、固件版本、硬件版本及唯一标识码
0x03机器零点位置设置
0x04夹爪行程设置
0x05机器扭矩开关、控制模式及直接电流控制
0x06关节及夹爪控制、状态获取与力反馈
0XFE机器自检指令

2. 指令功能

2.1 查询机器信息指令​

指令ID为 0x01，用于查询机器的序列号、硬件版本号和固件版本号。

字段取值
指令0x01
功能码0x00
数据长度0x01
数据0xFE
校验0x23

发送帧示例​

帧头指令功能码数据长度数据校验帧尾
0xAA0x010x000x010xFE0x230xFF

返回帧示例​

帧头指令功能码数据长度数据校验帧尾
0xAA0x010x000x180x41 0x44 0x4C 0x53 0x32 0x35 0x31 0x32 0x30 0x35 0x31 0x32 0x33 0x34 0x35 0x36 0x6E 0x00 0x00 0x00 0x62 0x02 0x00 0x000x920xFF

返回帧数据解析​

返回帧的数据字段共 24字节（0x18），按顺序分为三部分：

颜色字段长度对应字节
蓝色序列号16字节0x41 0x44 ... 0x35 0x36
橙色硬件版本4字节0x6E 0x00 0x00 0x00
绿色固件版本4字节0x62 0x02 0x00 0x00

序列号（16字节）​

每个字节为字符的 ASCII 码。以上示例转换为字符串即：ADLS251205123456。

其含义为：产品标识 + 出厂日期 + 序列号尾码，每台机器唯一。

硬件版本（4字节，小端序）​

4字节组成一个小端序整数。以上示例：0x6E 0x00 0x00 0x00 → 十进制 110，表示硬件版本 v1.10。

换算方式：0x6E = 110（十进制），高3字节均为0，故整数值为 110。版本号 = 110 ÷ 100 = 1.10。

固件版本（4字节，小端序）​

同理，以上示例：0x62 0x02 0x00 0x00 → 十进制 610，表示固件版本 v6.10。

换算方式：0x02 × 256 + 0x62 = 512 + 98 = 610（小端序：低字节在前）。版本号 = 610 ÷ 100 = 6.10。

提示

返回帧的校验值因每台机器的序列号不同而不同，属于正常现象。

2.2 机器零点位置设置指令​

机器零点位置设置指令ID为0x03，该指令用于设置机器零点位置。该指令会关闭扭矩。

字段取值
指令0x03
功能码0x00
数据长度0x01
数据0xFE
校验0xA8（功能码0x00时）

功能码说明​

功能码功能含义
0x00灵动系列：设置零点位置

示例：设置灵动零点位置​

帧头指令功能码数据长度数据校验帧尾
0xAA0x030x000x010xFE0xA80xFF

2.3 夹爪行程设置指令​

夹爪行程设置指令ID为0x04，该指令用于设置机器夹爪的行程，同时支持查询夹爪行程配置。

字段取值
指令0x04
功能码0x00、0x01、0x02、0x0E
数据长度0x01
数据0xFE（指令发送时）；行程类型值（查询返回时）
校验0x7F

功能码说明​

功能码功能含义
0x00设置夹爪为50mm行程
0x01设置夹爪为75mm行程
0x02设置夹爪为100mm行程
0x0E查询夹爪行程配置

示例1：设置夹爪行程为100mm​

帧头指令功能码数据长度数据校验帧尾
0xAA0x040x020x010xFE0x7F0xFF

示例2：查询夹爪行程配置​

帧头指令功能码数据长度数据校验帧尾
0xAA0x040x0E0x010xFE0x7F0xFF

返回数据说明​

查询夹爪行程配置后，返回的数据字段为夹爪的行程类型，对应关系如下：

  • 0x00：50mm行程夹爪
  • 0x01：75mm行程夹爪
  • 0x02：100mm行程夹爪

返回帧示例（以75mm行程为例）​

帧头指令功能码数据长度数据校验帧尾
0xAA0x040x0E0x010x010x7F0xFF

2.4 机器扭矩开关指令​

机器扭矩开关指令ID为0x05，该指令用于设置机器的扭矩开关。

字段取值
指令0x05
功能码0x00
数据长度0x01
数据0x00、0x01
校验0x6F

数据字段说明​

数据值含义
0x00关闭力矩
0x01开启力矩

指令帧示例​

帧头指令功能码数据长度数据校验帧尾
0xAA0x050x000x010x000x6F0xFF

2.5 关节及夹爪控制指令​

关节及夹爪控制帧的指令ID为 0x06，该指令包含多个功能，下面分别说明。

获取位置和运动状态​

  • 功能码：0x00
  • 数据：0xFE
  • 数据长度：0x01

发送帧示例：

帧头指令功能码数据长度数据校验帧尾
0xAA0x060x000x010xFE0x9A0xFF

返回帧示例：

帧头指令功能码数据长度数据校验帧尾
0xAA0x060x000x0F0x02 0x08 0xFB 0x07 0xFB 0x07 0x02 0x08 0xFA 0x07 0x01 0x08 0x03 0x08 0x000xA90xFF

数据格式：关节角度（每个关节2字节） + 夹爪位置（2字节） + 运行状态（1字节），数据低位在前高位在后。

灵动系列：6关节角度 + 夹爪位置 + 运行状态。

运行状态（最后一字节）：

状态值含义
0x00空闲
0x01锁定
0x10同步
0x11同步锁定
0xE1过热状态
0xE2过热保护

获取温度数据​

  • 功能码：0x01
  • 数据：0xFE

发送帧示例（灵动Alicia-DL示教臂6个舵机，操作臂10个）：

帧头指令功能码数据长度数据校验帧尾
0xAA0x060x010x010xFE0xAD0xFF

返回帧示例（灵动示教返回6个，操作返回10个）：

帧头指令功能码数据长度数据校验帧尾
0xAA0x060x010x0A0x23 0x24 0x23 0x26 0x23 0x26 0x23 0x25 0x24 0x240x4B0xFF

在温度功能码下，如果数据不为 0xFE，则为设置温度保护最大阈值。示例：设置最大阈值为 100（0x64），默认值为 85：

帧头指令功能码数据长度数据校验帧尾
0xAA0x060x010x010x640xF70xFF

获取速度数据​

  • 功能码：0x02
  • 数据：0xFE

发送帧示例（灵动Alicia-DL示教臂6个舵机，操作臂10个）：

帧头指令功能码数据长度数据校验帧尾
0xAA0x060x020x010xFE0xF40xFF

返回帧示例（灵动示教返回6个，操作返回10个）：

帧头指令功能码数据长度数据校验帧尾
0xAA0x060x020x140x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x000xE90xFF

关节、夹爪及状态控制​

  • 功能码：0x03
  • 数据长度：0x1C
  • 数据格式：关节角度 + 速度（每个关节4字节），数据低位在前高位在后
    • 灵动系列：6关节角度 + 夹爪位置

示例：控制各关节角度为0度、速度1000，夹爪闭合到一半（0x3E8）。运动速度最高可设为5000，数据先位置角度再速度。夹爪映射范围为 0~1000，1000 为张开到最大量程。

帧头指令功能码数据长度数据校验帧尾
0xAA0x060x030x1C0x00 0x08 0xE8 0x03 0x00 0x08 0xE8 0x03 0x00 0x08 0xE8 0x03 0x00 0x08 0xE8 0x03 0x00 0x08 0xE8 0x03 0x00 0x08 0xE8 0x03 0xF4 0x01 0xE8 0x030x6A0xFF

2.6 机器自检指令​

指令ID为 0xFE，用于检测舵机是否正常。返回2个字节数据，从低到高每个 bit 位代表舵机ID从低到高的状态，1 为正常，0 为异常。灵动操作臂10个 bit，示教臂6个 bit。

字段取值
指令0xFE
功能码0x00
数据长度0x03

发送帧示例​

帧头指令功能码数据长度数据校验帧尾
0xAA0xFE0x000x000xFE0x930xFF

返回帧示例（操作臂所有舵机正常）​

帧头指令功能码数据长度数据校验帧尾
0xAA0xFE0x000x020xFF 0x030x870xFF

2.7 设置控制模式（仅力反馈版示教臂）​

用于切换力反馈示教臂的位置模式与电流模式。模式切换与扭矩开关是两个独立操作，切换模式不应被视为已经锁定姿态或开启力反馈。

适用范围

本节及后续 2.8～2.10 节为力反馈版新增功能，仅适用于支持对应协议的 Alicia-DL 力反馈示教臂固件，原版示教臂不支持。查询模式或诊断状态无需先开启力反馈。

字段取值
指令0x05
功能码0x01
数据长度0x01
数据0x00：位置模式；0x01：电流模式

数据字段说明​

数据值模式功能说明
0x00position，位置模式用于位置控制及姿态保持；右键用于锁定 / 解除姿态锁定
0x01current，电流模式用于电流控制及配套遥操作；右键用于开启 / 关闭力反馈

发送帧示例​

功能帧头指令功能码数据长度数据校验帧尾
切换位置模式0xAA0x050x010x010x000x580xFF
切换电流模式0xAA0x050x010x010x010xCE0xFF

返回帧格式​

帧头指令功能码数据长度数据校验帧尾
0xAA0x050x010x03VERSION REQUESTED_MODE RESULTCRC32 低八位0xFF

所有 DATA 偏移均从数据区第一个字节开始，以 0 为起点。

DATA 偏移字段说明
0VERSION回包格式版本，当前为 0x01
1REQUESTED_MODE原样返回请求模式
2RESULT0x00 表示请求已接受；非零表示拒绝或不支持

ACK 只表示请求被接受，不表示物理模式切换完成。收到 ACK 后，应使用 0x06 / 0x24 回读，确认当前模式与目标模式一致。非零结果码的细分定义需按交付固件版本核对，不能把超时当成成功。

对应 SDK：set_control_mode()、get_control_mode()。SDK 的遥操作开关复用模式接口，没有额外增加独立的遥操作功能码。

2.8 六轴直接电流控制（仅力反馈版示教臂）​

向 J1～J6 下发目标电流，用于电流模式调试。该功能直接接收上位机指定的电流，与根据 Alicia-M 回传力矩生成输出的力反馈功能不同。

固件支持待核对

本节按配套 SDK 的组帧及回包解析实现编写。当前检查的 STM32 工作区源码尚未包含 0x05 / 0x02 处理，不能据此认定所有标记为 v6.1.8 的固件均已支持。正式发布前需对照最终交付固件完成确认。

字段取值
指令0x05
功能码0x02
数据长度0x0C，即 12 字节
数据J1～J6 的六个有符号 16 位整数，小端序，单位 mA

数据字段说明​

DATA 偏移字段类型 / 单位
0～1J1 目标电流int16 / mA
2～3J2 目标电流int16 / mA
4～5J3 目标电流int16 / mA
6～7J4 目标电流int16 / mA
8～9J5 目标电流int16 / mA
10～11J6 目标电流int16 / mA

例如，+100 mA 编码为 64 00，-100 mA 编码为 9C FF。正负号表示电流方向。

发送帧格式​

帧头指令功能码数据长度数据校验帧尾
0xAA0x050x020x0CJ1～J6 电流，共 12 字节CRC32 低八位0xFF

返回数据说明​

配套 SDK 按以下格式解析 ACK，最小 DATA 长度为 4 字节：

DATA 偏移字段说明
0VERSIONACK 格式版本；固定取值待交付固件确认
1RESULT0 表示接受，非零表示拒绝
2ACCEPTED_MASKbit0～bit5 分别对应 J1～J6，1 表示对应轴被接受
3REFRESH_DEADLINE刷新期限，单位为 10 ms；例如 10 表示 100 ms

返回帧沿用 0xAA / 0x05 / 0x02 / LEN / DATA / CRC / 0xFF 格式。

根据配套 SDK 的接口约定，该命令要求电流模式已生效、扭矩已开启且控制器状态稳定。调用方应根据 ACK 刷新期限持续更新目标，检查实际发送间隔及接受结果，不能认为发送一次即可永久保持输出。

配套 SDK 当前允许输入 -6000～6000 mA，该范围是参数校验范围，不代表每个关节在任意姿态下的允许工作电流；实际输出仍受固件限制和保护状态约束。

对应 SDK：set_direct_current()。

2.9 力反馈开关与状态查询（仅力反馈版示教臂）​

用于设置力反馈请求，或查询当前请求及实际生效状态。实际力反馈需与 Alicia-M 操作臂配套使用，并满足同步、有效回传及设备状态要求。

字段取值
指令0x06
功能码0x20
数据长度0x01
数据0x00 关闭请求；0x01 开启请求；0xFE 只读查询

发送帧示例​

功能帧头指令功能码数据长度数据校验帧尾
关闭力反馈0xAA0x060x200x010x000x610xFF
开启力反馈0xAA0x060x200x010x010xF70xFF
查询状态0xAA0x060x200x010xFE0x7A0xFF

返回帧格式​

帧头指令功能码数据长度数据校验帧尾
0xAA0x060x20LEN力反馈状态CRC32 低八位0xFF
状态格式版本

当前检查的 STM32 工作区返回 VERSION=0x01、LEN=0x06。配套 SDK 的候选协议说明另有 VERSION=0x02、LEN=0x0A 扩展格式。下表分别说明，最终交付采用哪一版仍待核对；解析时必须检查版本及长度，不能固定读取 10 字节。

版本 1：6 字节 DATA​

DATA 偏移字段说明
0VERSION0x01
1REQUESTED是否请求开启力反馈，0 为关闭、1 为开启
2EFFECTIVE力反馈是否实际生效，0 为未生效、1 为生效
3INHIBIT_MASK未生效原因位掩码
4SYNC_ACTIVE是否处于同步模式
5保留状态位当前检查的固件固定返回 0，不能用它判断扭矩实际状态

版本 2：候选扩展格式，10 字节 DATA​

DATA 偏移字段说明
0VERSION0x02
1～4基础状态与版本 1 的 REQUESTED、EFFECTIVE、INHIBIT_MASK、SYNC_ACTIVE 对应
5TORQUE_ENABLED控制器记录的扭矩实际使能状态
6TORQUE_REQUESTED扭矩请求状态
7TRANSITION模式切换阶段，诊断字段
8GRIP_ENABLED_RAW握把原始使能状态，诊断字段
9REQUESTED_MODE请求模式：0 为位置模式，1 为电流模式

未生效原因说明​

原因位可同时出现，调用方应按位解析。

bit掩码说明
00x01未进入遥操作同步模式
10x02当前检查固件预留、不置位；不得直接视为机械锁定
20x04D-M 回传缺失或超时，当前有效样本期限为 30 ms
30x08硬件故障
40x10操作或协议不支持
5～7—预留

REQUESTED=1 仅表示已请求开启。实际是否生效必须检查 EFFECTIVE，例如回传超时时可能为 REQUESTED=1、EFFECTIVE=0。查询状态无需先开启力反馈。

对应 SDK：set_force_feedback_enabled()、get_force_feedback_state()。

2.10 控制模式与六轴电流诊断（仅力反馈版示教臂）​

用于读取当前模式和六轴诊断快照。该接口只读，不会开启力反馈、切换模式或修改扭矩状态。

字段取值
指令0x06
功能码0x24
数据长度0x01
数据0xFE

发送帧示例​

帧头指令功能码数据长度数据校验帧尾
0xAA0x060x240x010xFE0xA60xFF

返回帧格式​

返回 DATA 长度为 52 字节，完整帧长 58 字节。

帧头指令功能码数据长度数据校验帧尾
0xAA0x060x240x34模式及六轴诊断，共 52 字节CRC32 低八位0xFF

返回数据说明​

DATA 偏移长度字段说明
01VERSION当前为 0x01
11APPLIED_MODE公开模式值：0 为位置模式，1 为电流模式；其他值视为不支持
21BLOCKED_MASK关节阻塞诊断位，bit0～bit5 对应 J1～J6；实际支持轴随固件变化
31FEEDBACK_VALID_MASK六轴状态反馈有效位，bit0～bit5 对应 J1～J6，不等同于力反馈生效状态
4～5148六轴诊断数据按 J1～J6 顺序排列，每轴 8 字节

每轴数据均为小端序 int16，轴内偏移定义如下：

轴内偏移字段单位说明
0～1远端力矩目标0.001 N·m来自配套操作臂的力矩目标
2～3请求电流0.001 A控制器请求的电流
4～5输出电流0.001 A控制器下发的电流目标
6～7测量电流0.001 A舵机反馈的测量电流

例如原始值 300 表示 0.300 A 或 0.300 N·m，具体单位取决于字段。不能把输出电流目标当作实际测量电流。

对应 SDK：get_control_mode()、get_hls_current_diagnostics()。

2.11 力反馈版兼容性说明​

  • 原有通用指令继续沿用，但位置控制、零位校准等操作仍受当前模式及设备状态限制。
  • 模式切换、扭矩开关和力反馈开关分别控制不同状态，不应互相替代。
  • 旧固件或非力反馈版设备可能拒绝新功能或不回包，调用方必须处理超时和拒绝结果。
  • D-M 配套通信与本页上位机协议不同。上位机通过本页接口设置模式及读取状态，无需构造 D-M 实时力矩帧。
  • 本次新增协议仍有 2.8 的固件支持、2.9 的回包版本和部分诊断字段待最终交付固件核对。发布前应据实固定版本对应关系。