5.1.7 灵创动作

备注

X2 EDU（人人造版）不支持本节功能。 本节内容仅适用于 X2 Ultra（旗舰版）与 X2 Ultra(new version)（旗舰焕新版）。

关于 LinkCraft

LinkCraft 是智元的动作创作和管理平台，用于创建、编辑、调试和部署机器人动作。在 LinkCraft 平台上创作的动作部署至机器人后，可通过本节所述的 ROS 接口获取已部署的资源列表，并触发单机播放或多机群控播放。

平台侧的使用请参阅 LinkCraft 使用手册。

接口说明

服务名称	数据类型	描述
/aimdk_5Fmsgs/srv/GetRobotResources	GetRobotResources	获取机器人上的资源列表
/aimdk_5Fmsgs/srv/ExecuteActionResource	ExecuteActionResource	播放指定的灵创动作资源
/aimdk_5Fmsgs/srv/GroupControlTimeSync	GroupControlTimeSync	群控时间同步

• GetRobotResources ros2-srv @ app_proxy/srv/GetRobotResources.srv

  # 获取机器人上资源列表
  # 服务名称: /aimdk_5Fmsgs/srv/GetRobotResources
  
  # 请求
  CommonRequest header         # 请求头
  
  ---
  
  # 响应
  CommonResponse header        # 响应头
  RobotResource[] robot_resources  # 机上资源信息列表
  

  • RobotResource ros2-msg @ app_proxy/msg/RobotResource.msg

    string resource_key            # 资源唯一标识
    CurrentVersion current_version    # 当前版本信息
    

    • CurrentVersion ros2-msg @ app_proxy/msg/CurrentVersion.msg

      string version               # 版本号
      string name                  # 资源名称
      string[] files               # 资源文件列表
      uint64 download_timestamp_seconds         # 资源下载时间
      

• ExecuteActionResource ros2-srv @ app_proxy/srv/ExecuteActionResource.srv

  # 播放灵创动作
  # 服务名称: /aimdk_5Fmsgs/srv/ExecuteActionResource
  
  # 请求
  CommonRequest header         # 请求头
  string resource_key          # 资源唯一标识（从 GetRobotResources 获取）
  string resource_version      # 资源版本号
  SlaveDevice[] slaves         # 从设备列表（群控时填写从机 IP，单机播放可为空）
  string meta                  # JSON 格式的扩展参数
  
  ---
  
  CommonResponse header        # 响应头，header.message 为结果信息（成功时为 "Play success"）
  

  • SlaveDevice ros2-msg @ app_proxy/msg/SlaveDevice.msg

    string ip                    # 从设备 IP 地址
    

  meta 字段格式：

  场景	meta 值
  单机全身动作（onnx）	{"resource_type": "BODY_MONTION"}
  单机手臂动作	{"resource_type": "ARM_MONTION"}
  群控全身动作（onnx）	{"control_type": "GROUP_CONTROL","resource_type": "BODY_MONTION"}
  群控手臂动作	{"control_type": "GROUP_CONTROL","resource_type": "ARM_MONTION"}

  resource_key 中包含 onnx 时为全身动作，否则为手臂动作。

  群控场景下，meta 还可携带以下可选字段：

  • if_play_master（bool，默认 true）：是否播放主设备。设为 false 时仅播放从设备，主设备不动作。

  通过 header.message 判断实际结果，header.status.value 不可用于判断成功与否。

  单机播放：

  header.message	说明
  Play success	播放成功
  No valid resource files found	资源目录下无有效文件
  The robot is playing	机器人正在播放，无法触发新任务
  The robot is in a faulty state	机器人处于故障状态
  The robot is not in ready posture	机器人未处于就绪姿态
  MC ROS service not ready	运控 ROS 服务未就绪
  Audio ROS service not ready	音频 ROS 服务未就绪
  Face ROS service not ready	表情 ROS 服务未就绪
  Trigger MC ROS service error: <异常描述>	运控 ROS 服务调用异常（<异常描述> 为运行时填充的具体异常信息）
  Trigger Audio ROS service error: <异常描述>	音频 ROS 服务调用异常（同上）
  Trigger Face ROS service error: <异常描述>	表情 ROS 服务调用异常（同上）
  Trigger interaction error	调用交互播放接口失败
  Bad request	请求参数错误
  Error processing play item <N>: <异常描述>	处理播放项时内部异常（<N> 为播放项序号，<异常描述> 为运行时填充的具体异常信息）
  No time sync result for slave device <ip>	群控时从机未完成时间同步（<ip> 为从机 IP）
  <异常描述>	处理过程中发生未预期异常（内容为 Python 异常的字符串表示，取决于具体异常类型，不可枚举）

  群控播放（部分从机失败）：

  header.message 为 JSON 字符串，包含各失败从机的详情，格式如下：

  {
    "192.168.2.19": {
      "sn": "机器人序列号",
      "error_code": 412,
      "error_msg": "The robot is playing"
    }
  }
  

  其中 key 为失败从机的 IP（由用户在 slaves 字段中填写），sn 为该从机的序列号，error_code 和 error_msg 为该从机播放失败的具体错误码和描述。

  JSON 中 error_code 的可能取值：

  error_code	说明
  400	请求参数错误
  401	调用交互播放接口失败
  402	机器人未处于就绪姿态
  403	作品存在危险/损害机器人动作（预留）
  404	作品不存在（预留）
  405	机器人处于故障状态
  406	运控 ROS 服务未就绪
  407	音频 ROS 服务未就绪
  408	表情 ROS 服务未就绪
  409	运控 ROS 服务调用异常
  410	音频 ROS 服务调用异常
  411	表情 ROS 服务调用异常
  412	机器人正在播放
  413	存在未时间同步的从机（预留）
  450	群控有任务失败（预留）
  500	内部服务器错误
  503	服务不可用（预留）

  解析示例：

  import json
  if header.message == "Play success":
      print("播放成功")
  else:
      try:
          details = json.loads(header.message)
          for ip, info in details.items():
              print(f"从机 {ip}: 错误码 {info['error_code']}, {info['error_msg']}")
      except json.JSONDecodeError:
          print(f"播放失败: {header.message}")
  

• GroupControlTimeSync ros2-srv @ app_proxy/srv/GroupControlTimeSync.srv

  # 群控时间同步
  # 服务名称: /aimdk_5Fmsgs/srv/GroupControlTimeSync
  
  # 请求
  CommonRequest header         # 请求头
  SlaveDevice[] slaves         # 群控从节点列表
  
  ---
  
  # 响应
  CommonResponse header        # 响应头，header.status.value 为状态码（1 (SUCCESS 成功), 2 (FAILURE 失败)）
  int32 error_code             # 错误码，0 表示成功，1 表示失败
  string error_msg             # 错误信息
  

  群控播放前需先调用此接口完成多机时间同步，error_code 为 0 表示同步成功，为 1 表示失败（error_msg 含失败从机详情）。

编程示例

详细的编程示例和代码说明请参考：

• C++ 示例：

  • 播放灵创动作

  • 群控播放灵创动作

• Python 示例：

  • 播放灵创动作

  • 群控播放灵创动作

小心

ROS的服务(service)机制在跨板通信时存在一些待优化问题, 二次开发时请参考例程添加异常处理、快速重试等保护机制

机器人处于稳定站立 / 走跑模式时, 请勿批量快速启动 ROS 节点(建议不超过 2 个/秒), 短时间内大量节点参与 DDS 发现会造成通信拥塞、影响运控实时性, 存在机器人失稳摔倒风险