Skip to main content

云擎通讯协议 v1.0.0

阅读指南
  1. 本协议适用于云擎（Alicia-M）系列相关产品。
  2. 本协议中的数值统一采用十进制或十六进制表示，以 0x 标识的为十六进制数。

云擎按键功能：

  • 单击：切换电机模式，mit mode ↔ pv mode（掉电保存）
  • 双击：按键灯快速闪烁，回放记录的动作（期间任意键停止回放）
  • 长按：1~2s 内切换重力补偿模式（仅 mit 模式有效）
  • 超长按：2s 以上按键灯慢闪烁，记录按键灯闪烁期间的动作（期间任意键停止记录）

串口通信参数：

  • 有重力补偿帧率：830 Hz
  • 无重力补偿帧率：1000 Hz
  • 极限帧率：1630 Hz（适用于 C/C++）

上一次修改时间：2026年1月27日 19:00

注：该通讯协议文档及其相关功能的最终解释权由 玄雅科技有限公司 所有。

1. 协议基本构成​

云系列产品的通讯协议由帧头、指令ID、功能码、有效数据长度、有效数据、校验位、帧尾 依次构成，各字段定义如下：

字段定义说明
帧头固定为 0xAA，标识数据帧的起始位置
指令ID控制指令唯一标识，每个ID对应特定控制逻辑或数据格式，便于接收端匹配处理流程
功能码细化指令功能，区分读写操作、指定操作部位/功能类型，部分包含反馈标识
有效数据长度后续"有效数据"字段的字节数
有效数据关节位置、速度、加速度、力矩等业务数据，或配置参数信息
校验位CRC32校验，计算范围为「帧头之后、校验位之前的所有字节」，取低8位（1字节）
帧尾固定为 0xFF，标识数据帧的结束位置

校验位计算规则：Check = CRC32(指令ID + 功能码 + 有效数据长度 + 有效数据) & 0xFF

2. 指令ID目录​

指令ID指令功能
0x01获得固件版本、硬件版本和唯一标识码（机械类型）
0x02用户个性化设置（夹爪行程、定时上传电机姿态等）
0x03设置机械当前位姿为初始位姿
0x05机械锁控制、重力补偿（关节力矩开关）
0x06关节数据获取与控制（MIT模式、线性轨迹速度等）
0x09机器人部位的失能和使能
0x11关节控制幅值和驱动参数设置
0xEE错误反馈（数据帧校验、系统模式等错误提示）

3. 详细指令说明​

3.1 指令ID 0x01：版本与设备信息获取​

功能​

获取设备固件版本、硬件版本和唯一标识码（含机械类型）。

字段定义​

字段取值/说明
指令ID0x01
功能码0x7E（请求）、0xFE（反馈，即 0x80 + 0x7E）
有效数据唯一序列号（16字节 ASCII）+ 硬件版本（4字节）+ 固件版本（4字节）

有效数据说明​

项目说明
唯一序列号（16字节 ASCII）格式为 AMFS 2511 29X1 0L23
硬件版本4字节，如 v1.0.0 对应 0x00 00 00 64
固件版本4字节，如 v1.1.0 对应 0x00 00 00 6E

序列号格式说明：

字段片段含义
AM云擎（产品系列代号）
FS操作臂标准版（设备类型代号）
2511 292025年11月29日（生产日期）
X1 0L23唯一代号（初始烧录时上位机赋予）

云系列产品代号表​

产品类别代号
云擎AM
云弈BM
云犀GM
示教臂L
操作臂F
标准款S
强力款X
夹爪行程100mmH

发送帧示例​

注：占位符0xFE为固定填充值，无实际业务含义，仅用于满足帧结构完整性

帧头指令ID功能码有效数据长度占位符校验位帧尾
0xAA0x010x7E0x010xFEcrc32&0xFF0xFF

返回帧示例​

帧头指令ID功能码有效数据长度有效数据（24字节）校验位帧尾
0xAA0x010xFE0x18唯一序列号+硬件版本+固件版本crc32&0xFF0xFF

3.2 指令ID 0x02：个性化设置​

功能说明​

支持用户个性化信息的读取与设置（掉电保存），包括夹爪行程、定时上传电机姿态等功能。

字段定义​

字段取值/说明
指令ID0x02
功能码1字节；最高 bit 位区分读写，低7 bit 位指定功能类型
有效数据长度根据操作类型和功能数量确定
有效数据4字节小端序（功能当前值/目标值）

功能码说明​

位段含义
bit7区分读写操作（0=读取，1=写入）
bit0保留
bit1夹爪行程
bit2定时上传电机姿态
bit3-bit6待定

个性化功能 addr 表​

功能名称addr默认值
夹爪量程0x010x00 95mm（对应4字节小端序数据）
定时上传电机姿态0x020x00（不定时上传）/ 0x01（定时上传）

发送帧示例1：读取前3个个性化设置值​

帧头指令ID功能码有效数据长度占位符校验位帧尾
0xAA0x020x030x010xFEcrc32&0xFF0xFF

返回帧示例1：读取反馈​

帧头指令ID功能码有效数据长度有效数据（12字节）校验位帧尾
0xAA0x020x030x08功能1+功能2crc32&0xFF0xFF

发送帧示例2：同时设置夹爪行程和定时上传电机姿态​

帧头指令ID功能码有效数据长度夹爪行程值（4字节）定时上传值（4字节）校验位帧尾
0xAA0x020x830x084字节小端序4字节小端序crc32&0xFF0xFF

返回帧示例2：设置反馈​

帧头指令ID功能码有效数据长度接收结果（0x01=成功，0x00=失败）校验位帧尾
0xAA0x020x830x010x01crc32&0xFF0xFF

3.3 指令ID 0x03：位姿重置​

功能​

设置指定部位的关节以当前位姿为初始位姿。

字段定义​

字段取值/说明
指令ID0x03
功能码1字节，低8 bit 位表示目标部位
有效数据长度2 × N（N 为功能码中置 1 的 bit 位数量，每个置 1 bit 对应2字节数据）
有效数据每个置 1 bit 对应2字节：起始关节ID + 起始关节的正方向偏移数量
反馈成功返回 0x01，失败返回 0xEE 错误指令

功能码说明​

bit位对应部位
bit0示教臂
bit1操作臂

有效数据说明​

字节位置含义
第1字节起始关节ID
第2字节起始关节的正方向偏移数量

发送帧示例​

设置示教臂（bit0=1）1~7关节、操作臂（bit1=1）2~5关节以当前位姿为初始位姿：

帧头指令ID功能码有效数据长度起始关节（示教）偏移数量（示教）起始关节（操作）偏移数量（操作）校验位帧尾
0xAA0x030x030x040x000x070x010x04crc32&0xFF0xFF

返回帧示例​

帧头指令ID功能码有效数据长度接收状态校验位帧尾
0xAA0x030x830x010x01crc32&0xFF0xFF

3.4 指令ID 0x05：肢体力矩控制​

功能​

设置指定部位关节的力矩状态（关节力矩开关），卸力后设备进入重力补偿状态。

字段定义​

字段取值/说明
指令ID0x05
功能码1字节，低8 bit 位表示目标部位
有效数据长度2 × N（N 为功能码中置 1 的 bit 位数量，不含 bit7）
有效数据每个置 1 bit 对应2字节：起始关节ID + 起始关节的正方向偏移数量
云擎关节数量7 个
反馈成功返回 0x01，失败返回 0xEE 错误指令

功能码说明​

bit位对应部位
bit0示教臂
bit1操作臂

有效数据说明​

字节位置含义
第1字节起始关节ID
第2字节起始关节的正方向偏移数量

发送帧示例​

设置示教臂（bit0=1）1~6关节锁定、操作臂（bit1=1）2~5关节锁定：

帧头指令ID功能码有效数据长度起始关节（示教）偏移数量（示教）起始关节（操作）偏移数量（操作）校验位帧尾
0xAA0x050x030x040x010x060x020x04crc32&0xFF0xFF

返回帧示例​

帧头指令ID功能码有效数据长度接收状态校验位帧尾
0xAA0x050x830x010x01crc32&0xFF0xFF

3.5 指令ID 0x06：关节与夹具状态控制​

功能说明​

分为「状态获取」和「状态控制」两类操作，支持获取/设置所有关节和夹具的指定数据（位置、速度、力矩等）及外设运行状态。

字段定义​

字段取值/说明
指令ID0x06
功能码1字节；最高 bit 位区分读写，低7 bit 位指定部位类型
有效数据长度2字节（偏移属性）+ 偏移数量 × 关节数量 × 数据字节数 + 1字节（运行状态）
有效数据数据帧属性 + 偏移数量 + 关节数据 + 运行状态

功能码说明​

位段含义
bit7区分读写操作（0=读取，1=写入）
bit0示教臂
bit1操作臂

有效数据说明​

顺序字段说明
1数据帧属性（1字节）最高 bit 位 = 反馈帧标识（0=非反馈，1=反馈），用于防止数据混淆
2偏移数量（1字节）指定起始地址的正方向偏移数量
3关节数据根据自定义数据表的 addr 和数据位数确定，12位数据采用2字节存储（高4位保留，低12位为有效数据）
4运行状态（1字节）各 bit 位定义见下表

运行状态说明​

部位bit位含义
示教臂bit0=锁定，bit1=同步，bit2-bit5=待定，bit6=夹具过高力矩运动方向锁定（0x07），bit7=电机错误（0x08）
操作臂bit0=单击，bit1=双击，bit2=长按，bit3=重复长按，bit4-bit5=待定，bit6=夹具过高力矩运动方向锁定（0x07），bit7=电机错误（0x08）

自定义数据 addr 表​

目标数据数据位数addr数据单位
当前位置/期望位置160x00rad
当前速度/期望速度120x01rad/s
当前力矩/额外力矩120x02N/m
位置环kp160x030~500
速度环kd160x040~5
线性轨迹速度120x05rad/s

发送帧示例1：状态获取（读取示教臂每个关节0~4地址数据）​

帧头指令ID功能码有效数据长度起始地址偏移数量校验位帧尾
0xAA0x060x020x020x000x05crc32&0xFF0xFF

返回帧示例1：状态获取反馈​

帧头指令ID功能码有效数据长度起始地址偏移数量关节数据（70字节）运行状态校验位帧尾
0xAA0x060x020x490x800x05motor1~motor7的Pos/Vel/力矩/kp/kd0x00crc32&0xFF0xFF

发送帧示例2：状态控制（设置操作臂关节数据）​

帧头指令ID功能码有效数据长度起始地址偏移数量关节数据（70字节）校验位帧尾
0xAA0x060x820x480x000x05motor1~motor7的目标Pos/Vel等crc32&0xFF0xFF

返回帧示例2：状态控制反馈​

帧头指令ID功能码有效数据长度起始地址偏移数量接收结果（0x01=成功，0x00=失败）校验位帧尾
0xAA0x060x820x030x800x050x01crc32&0xFF0xFF

3.6 指令ID 0x09：机器人部位失能/使能​

功能​

设置指定部位的关节使能或失能状态。

字段定义​

字段取值/说明
指令ID0x09
功能码1字节；最高 bit 位区分读写，低7 bit 位指定部位类型
有效数据长度0x01（仅状态值）
有效数据使能=0x01，失能=0x00
校验位CRC32计算帧头之后、校验位之前的所有字节，取低8位

功能码说明​

位段含义
bit7区分读写操作（0=读取，1=写入）
bit0示教臂
bit1操作臂

发送帧示例​

设置操作臂（bit1=1）的1~7号电机为使能（请求帧）：

帧头指令ID功能码有效数据长度设置的部位状态校验位帧尾
0xAA0x090x820x010x01crc32&0xFF0xFF

返回帧示例​

帧头指令ID功能码有效数据长度设置结果校验位帧尾
0xAA0x090x820x010x01crc32&0xFF0xFF

3.7 指令ID 0x11：关节控制幅值和驱动参数设置​

功能​

控制指定关节的控制幅值（加速度、减速度等）和驱动参数（PID参数、控制模式等）。

字段定义​

字段取值/说明
指令ID0x11
功能码1字节；最高 bit 位区分读写，低7 bit 位指定部位类型
有效数据长度0x07（起始电机ID + 偏移数量 + 参数地址 + 4字节参数）
有效数据起始电机ID索引 + 偏移电机数量 + 指定参数地址 + 4字节小端序参数

功能码说明​

位段含义
bit7区分读写操作（0=读取，1=写入）
bit0示教臂
bit1操作臂

有效数据说明​

顺序字段说明
1起始电机ID索引（1字节）起始电机编号
2偏移电机数量（1字节）指定连续设置的电机数量
3指定参数地址（1字节）见下方电机参数 addr 表
44字节小端序参数uint32_t 或 float 类型

电机参数 addr 表​

电机参数内容数据类型addr取值范围/说明
加速度float0x05-
减速度float0x06-
MID 反馈IDuint32_t0x08-
接收IDuint32_t0x09-
控制模式uint32_t0x0B0x01=MIT模式，0x02=位置速度模式
位置映射范围float0x16-
速度映射范围float0x17-
扭矩映射范围float0x18-
速度环Kpfloat0x1A-
速度环Kifloat0x1B-
位置环Kpfloat0x1C-
位置环Kifloat0x1D-

发送帧示例：更改电机模式为位置速度模式（0x02）​

帧头指令ID功能码有效数据长度起始电机ID索引偏移电机数量指定的参数地址4字节小端序参数校验位帧尾
0xAA0x110x820x070x010x070x0B02 00 00 00crc32&0xFF0xFF

返回帧示例​

帧头指令ID功能码有效数据长度起始电机ID索引偏移电机数量指定的参数地址设置状态（0x01=成功）校验位帧尾
0xAA0x110x820x040x010x070x8B0x01crc32&0xFF0xFF

3.8 指令ID 0xEE：错误反馈​

功能​

反馈数据帧处理过程中的错误（校验错误、系统模式错误等）。

字段定义​

字段取值/说明
指令ID0xEE
功能码错误类型对应的 addr 地址
有效数据长度根据错误类型确定
有效数据错误相关的辅助信息（如错误数据帧长度、校验位值等）

错误类型 addr 表​

错误描述功能码（addr）有效数据（携带提示词）
数据头/尾校验错误（帧头≠0xAA或帧尾≠0xFF）0x00错误数据帧的实际长度
数据长度校验错误（有效数据长度与实际不符）0x01错误数据帧的实际长度
数据帧校验错误（CRC32校验不通过）0x02下位机计算的校验位值
系统模式错误（检测机械臂类型失败）0x03当前下位机检测到的机械臂类型
电机角度限位中0x04角度限位的电机ID号
设定的motorData偏移与部位数量不符0x05有效数据的当前数据块长度
设定的insID偏移超过可设定的最大地址0x06起始地址+偏移的计算结果

返回帧示例：数据帧校验位错误（下位机计算校验位为0xF1）​

帧头指令ID功能码有效数据长度携带数据（校验位值）校验位帧尾
0xAA0xEE0x020x010xF1crc32&0xFF0xFF