Skip to main content

云擎通讯协议 v1.0.0

最后更新时间：2026年1月27日 19:00

串口通信参数：

  • 有重力补偿帧率：830 Hz

  • 无重力补偿帧率：1000 Hz

  • 极限帧率：1630 Hz（适用于C/C++）

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

一、协议基本构成​

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

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

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

二、指令ID目录​

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

三、详细指令说明​

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

功能​

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

字段定义​

  • 指令ID：0x01

  • 功能码：0x7E（请求）、0xFE（反馈，即 0x80 + 0x7E）

  • 有效数据：

    1. 唯一序列号（16字节ASCII码）：格式为「AMFS 2511 29X1 0L23」，各段含义如下：

      • AM→云擎（产品系列代号）、FS→操作臂标准版（设备类型代号）

      • 2511 29→2025年11月29日（生产日期）

      • X1 0L23→唯一代号（初始烧录时上位机赋予）

    2. 硬件版本（4字节）：如v1.0.0对应 0x00 00 00 64

    3. 固件版本（4字节）：如v1.1.0对应 0x00 00 00 6E

云系列产品代号表​

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

示例​

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

  1. 查询机器信息（请求帧）：
帧头指令ID功能码有效数据长度占位符校验位帧尾
0xAA0x010x7E0x010xFEcrc32&0xFF0xFF
  1. 机器信息反馈（响应帧）：
帧头指令ID功能码有效数据长度有效数据（24字节）校验位帧尾
0xAA0x010xFE0x18唯一序列号+硬件版本+固件版本crc32&0xFF0xFF

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

3.2.1 功能说明​

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

3.2.2 字段定义​

  • 指令ID：0x02

  • 功能码（1字节）：

    • 最高bit位：区分读写操作（0=读取，1=写入）

    • 低7bit位：指定功能类型（bit0=保留，bit1=夹爪行程，bit2=定时上传电机姿态，bit3-bit6=待定）

  • 有效数据长度：根据操作类型和功能数量确定

  • 有效数据：4字节小端序（功能当前值/目标值）

个性化功能addr表​

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

示例​

  1. 读取前3个个性化设置值（请求帧）：
帧头指令ID功能码有效数据长度占位符校验位帧尾
0xAA0x020x030x010xFEcrc32&0xFF0xFF
  1. 读取反馈（响应帧）：
帧头指令ID功能码有效数据长度有效数据（12字节）校验位帧尾
0xAA0x020x030x08功能1+功能2crc32&0xFF0xFF
  1. 同时设置夹爪行程和定时上传电机姿态（请求帧）：
帧头指令ID功能码有效数据长度夹爪行程值（4字节）定时上传值（4字节）校验位帧尾
0xAA0x020x830x084字节小端序4字节小端序crc32&0xFF0xFF
  1. 设置反馈（响应帧）：
帧头指令ID功能码有效数据长度接收结果（0x01=成功，0x00=失败）校验位帧尾
0xAA0x020x830x010x01crc32&0xFF0xFF

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

功能​

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

字段定义​

  • 指令ID：0x03

  • 功能码（1字节，各bit位含义如下）：

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

  • 有效数据长度：2×N（N为功能码中置1的bit位数量，每个置1bit对应2字节数据）

  • 有效数据（每个置1bit对应）：

    • 第1字节：起始关节ID

    • 第2字节：起始关节的正方向偏移数量

  • 反馈：成功返回0x01，失败返回0xEE错误指令

示例​

  1. 请求：设置示教臂（bit0=1）1~7关节、操作臂（bit1=1）2~5关节以当前位姿为初始位姿
帧头指令ID功能码有效数据长度起始关节（示教）偏移数量（示教）起始关节（操作）偏移数量（操作）校验位帧尾
0xAA0x030x030x040x000x070x010x04crc32&0xFF0xFF
  1. 反馈（设置成功）：
帧头指令ID功能码有效数据长度接收状态校验位帧尾
0xAA0x030x830x010x01crc32&0xFF0xFF

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

功能​

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

字段定义​

  • 指令ID：0x05

  • 功能码（1字节，各bit位含义如下）：

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

  • 有效数据长度：2×N（N为功能码中置1的bit位数量，不含bit7）

  • 有效数据（每个置1bit对应）：

    • 第1字节：起始关节ID

    • 第2字节：起始关节的正方向偏移数量

  • 云擎关节数量：7个

  • 反馈：成功返回0x01，失败返回0xEE错误指令

示例​

  1. 请求：设置示教臂（bit0=1）1~6关节锁定、操作臂（bit1=1）2~5关节锁定
帧头指令ID功能码有效数据长度起始关节（示教）偏移数量（示教）起始关节（操作）偏移数量（操作）校验位帧尾
0xAA0x050x030x040x010x060x020x04crc32&0xFF0xFF
  1. 反馈（设置成功）：
帧头指令ID功能码有效数据长度接收状态校验位帧尾
0xAA0x050x830x010x01crc32&0xFF0xFF

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

3.5.1 功能说明​

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

3.5.2 字段定义​

  • 指令ID：0x06

  • 功能码（1字节）：

    • 最高bit位：区分读写操作（0=读取，1=写入）

    • 低7bit位：指定部位类型（bit0=示教臂，bit1=操作臂）

  • 有效数据长度：2字节（偏移属性）+ 偏移数量×关节数量×数据字节数 + 1字节（运行状态）

  • 有效数据：

    1. 数据帧属性（1字节）：最高bit位=反馈帧标识（0=非反馈，1=反馈），用于防止数据混淆

    2. 偏移数量（1字节）：指定起始地址的正方向偏移数量

    3. 关节数据：根据自定义数据表的addr和数据位数确定，12位数据采用2字节存储（高4位保留，低12位为有效数据）

    4. 运行状态（1字节，各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地址数据）​

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

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

  1. 控制帧：
帧头指令ID功能码有效数据长度起始地址偏移数量关节数据（70字节）校验位帧尾
0xAA0x060x820x480x000x05motor1~motor7的目标Pos/Vel等crc32&0xFF0xFF
  1. 反馈帧（设置结果）：
帧头指令ID功能码有效数据长度起始地址偏移数量接收结果（0x01=成功，0x00=失败）校验位帧尾
0xAA0x060x820x030x800x050x01crc32&0xFF0xFF

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

功能​

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

字段定义​

  • 指令ID：0x09

  • 功能码（1字节）：

    • 最高bit位：区分读写操作（0=读取，1=写入）

    • 低7bit位：指定部位类型（bit0=示教臂，bit1=操作臂）

  • 有效数据长度：0x01（仅状态值）

  • 有效数据：使能=0x01，失能=0x00

  • 校验位：CRC32计算帧头之后、校验位之前的所有字节，取低8位

示例​

  1. 设置操作臂（bit1=1）的1~7号电机为使能（请求帧）：
帧头指令ID功能码有效数据长度设置的部位状态校验位帧尾
0xAA0x090x820x010x01crc32&0xFF0xFF
  1. 反馈帧（设置成功）：
帧头指令ID功能码有效数据长度设置结果校验位帧尾
0xAA0x090x820x010x01crc32&0xFF0xFF

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

功能​

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

字段定义​

  • 指令ID：0x11

  • 功能码（1字节）：

    • 最高bit位：区分读写操作（0=读取，1=写入）

    • 低7bit位：指定部位类型（bit0=示教臂，bit1=操作臂）

  • 有效数据长度：0x07（起始电机ID+偏移数量+参数地址+4字节参数）

  • 有效数据：

    1. 起始电机ID索引（1字节）

    2. 偏移电机数量（1字节）

    3. 指定参数地址（1字节，见电机参数addr表）

    4. 4字节小端序参数（uint32_t或float类型）

电机参数addr表​

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

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

  1. 请求帧：
帧头指令ID功能码有效数据长度起始电机ID索引偏移电机数量指定的参数地址4字节小端序参数校验位帧尾
0xAA0x110x820x070x010x070x0B02 00 00 00crc32&0xFF0xFF
  1. 反馈帧（设置成功）：
帧头指令ID功能码有效数据长度起始电机ID索引偏移电机数量指定的参数地址设置状态（0x01=成功）校验位帧尾
0xAA0x110x820x040x010x070x8B0x01crc32&0xFF0xFF

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

功能​

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

字段定义​

  • 指令ID：0xEE

  • 功能码：错误类型对应的addr地址

  • 有效数据长度：根据错误类型确定

  • 有效数据：错误相关的辅助信息（如错误数据帧长度、校验位值等）

错误类型addr表​

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

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

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