AIMA开放平台文档中心AimDK A3-ultra

7.1 运动控制部分

7.1 运动控制部分

7.1.2 状态机切换、查询 RPC 接口

接口名pb:/aimdk.protocol.MotionControlActionService/SetAction
功能概述切换运动控制状态机
接口类型 HTTP JSON RPC
URLhttp://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlActionService/SetAction
入参
text
{
  "header": {
    "timestamp": {
      "seconds": 1763614279,
      "nanos": 847810000,
      "ms_since_epoch": 1763614279847
    },
    "control_source": "ControlSource_SAFE"
  },
  "command": {
      "action": "MotionControlAction_GET_UP",
      "ext_action": "GET_UP"
  }
}
  • action: 从GetAvailableActions接口获取
  • ext_action: 从GetAvailableActions接口获取
出参
text
{
  "header": {
    "code": "0",
    "msg": "called successfully.",
    "timestamp": {
      "seconds": "1763643079",
      "nanos": 849593506,
      "ms_since_epoch": "0"
    },
    "trace_id": "",
    "domin": ""
  },
  "state": "CommonState_SUCCESS"
}
  • state: 调用请求状态
示例脚本examples/mc/S_SetAction.py
备注
  • 异步接口，调用完成不代表切换即完成，需配合 GetAction 接口查询切换是否完成
  • 本接口无 Action 限制
接口名pb:/aimdk.protocol.MotionControlActionService/GetAction
功能概述查询运动控制状态机
接口类型 HTTP JSON RPC
URLhttp://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlActionService/GetAction
入参
text
{}
出参
text
{
  "header": {
    "code": "0",
    "msg": "called successfully.",
    "timestamp": {
      "seconds": "1763643026",
      "nanos": 8207141,
      "ms_since_epoch": "0"
    },
    "trace_id": "",
    "domin": ""
  },
  "info": {
    "current_action": "MotionControlAction_PASSIVE",
    "ext_action": "",
    "status": "MotionControlActionStatus_RUNNING"
  }
}
  • current_action: 当前运行的 Action
  • ext_action: 扩展 Action，一般不使用
  • status：Action 状态，一般不使用
示例脚本example/mc/S_GetAction.py
备注
  • 本接口无 Action 限制

7.1.3 机器人可用Action 查询 RPC 接口

接口名pb:/aimdk.protocol.MotionControlActionService/GetAvailableActions
功能概述获取可用动作
接口类型 HTTP JSON RPC
URLhttp://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlActionService/GetAvailableActions
入参
text
{ 
    "header": {
      "timestamp": {
        "seconds": "0",
        "nanos": 0,
        "ms_since_epoch": "1744598548952"
      }
    }
}
出参
text
{
  "header": {
    "code": "0",
    "msg": "called successfully.",
    "timestamp": {
      "seconds": "1775639638",
      "nanos": 585833612,
      "ms_since_epoch": "0"
    },
    "trace_id": "module_mc",
    "domin": ""
  },
  "commands": [
    {
      "action": "MotionControlAction_DAMPING",
      "ext_action": "DAMPING"
    },
    {
      "action": "MotionControlAction_GET_UP",
      "ext_action": "GET_UP"
    },
    {
      "action": "MotionControlAction_LIE_DOWN",
      "ext_action": "LIE_DOWN"
    },
......
  ]
}
  • action：可切换的action名称，
  • ext_action：action代码名，与action出参对应
示例脚本examples/mc/S_SetAction.py
备注一般会通过GetAvailableActions接口查询当前可切换action状态，再通过SetAction接口设置action状态

7.1.4 行走控制指令 Topic 接口

接口名/motion/control/locomotion_velocity
功能概述行走控制指令
接口类型 ROS2 Topic
入参
text
{
  "data": {
    "mode": MotionControl_LocomotionMode_DEFAULT,
    "forward_velocity": 0.1,
    "lateral_velocity": 0.0,
    "angular_velocity": 0.0
  }
}
  • mode: 速度控制模式
    • MotionControl_LocomotionMode_DEFAULT为默认模式
    • MotionControl_LocomotionMode_NAVIGATION为导航模式
  • forward_velocity: 前进速度比例系数，发送比例系数范围-1.0~1.0 ，+为前进,-为后退，由mc计算速度
  • lateral_velocity: 水平速度比例系数，发送比例系数范围-1.0~1.0 ，+为左侧移动,-为右侧移动，由mc计算速度
  • angular_velocity: 旋转速度比例系数，发送比例系数范围-1.0~1.0 ，+为左旋转,-为右旋转，由mc计算速度
示例脚本examples/mc/walk.py
备注
  • 该消息的 ROS2 类型为 ros2_plugin_proto/msg/RosMsgWrapper，需要 source prebuilt/ros2_plugin_proto_aarch64/share/ros2_plugin_proto/local_setup.bash 后使用。
  • 本接口有调用限制，仅可在 MOTION 状态调用。

7.1.5 手臂控制指令、状态 Topic 接口

接口名/motion/control/arm_joint_command
功能概述手臂关节控制指令
接口类型 ROS2 Topic
入参sensor_msgs::msg::JointState
  • name：关节名称，固定填写为["left_shoulder_pitch_joint","left_shoulder_roll_joint","left_shoulder_yaw_joint", "left_elbow_joint", "left_wrist_roll_joint", "left_wrist_pitch_joint", "left_wrist_yaw_joint", "right_shoulder_pitch_joint", "right_shoulder_roll_joint", "right_shoulder_yaw_joint", "right_elbow_joint", "right_wrist_roll_joint", "right_wrist_pitch_joint", "right_wrist_yaw_joint"]
  • position：关节角度，必须填写 14 个关节的角度值
  • velocity: 无效字段，置为 0.0 即可
  • effort: 无效字段，置为 0.0 即可
示例脚本examples/mc/arm.py
备注
  • 本接口推荐以 100 Hz 的频率进行调用，调用时需要注意相邻指令间隔不要超过 30ms，确保速度不超过 4 rad/s，并且指令尽量顺滑，否则可能会有抖动，推荐起码使用基本的低通滤波方法：y(k) = (1 - a) * y(k - 1) + a * x(k)。
  • 角度限位如下（单位 rad）
    • left_shoulder_pitch_joint: ±2.87979
    • left_shoulder_roll_joint: -0.08727 ~ 2.61799
    • left_shoulder_yaw_joint: ±2.79253
    • left_elbow_joint: -0.95993 ~ 1.74533
    • left_wrist_roll_joint: ±2.79253
    • left_wrist_pitch_joint: ±1.62316
    • left_wrist_yaw_joint: ±1.62316
    • right_shoulder_pitch_joint: ±2.87979
    • right_shoulder_roll_joint: -2.61799 ~ 0.08727
    • right_shoulder_yaw_joint: ±2.79253
    • right_elbow_joint: -0.95993 ~ 1.74533
    • right_wrist_roll_joint: ±2.79253
    • right_wrist_pitch_joint: ±1.62316
    • right_wrist_yaw_joint: ±1.62316
  • 本接口有调用限制，仅可在 MOTION 状态下调用
  • 由于motion_player模块一直在向motion_control模块下发命令，在下发命令前请关闭motion_player模块
接口名/motion/control/arm_joint_state
功能概述手臂关节状态话题
接口类型 ROS2 Topic
出参sensor_msgs::msg::JointState
  • name: 14 个关节名称
  • position: 14 个关节角度
  • velocity: 14 个关节速度
  • effort: 14 个关节力矩
示例脚本examples/mc/joint_state.py
备注本接口无 Action 限制

7.1.6 腰部姿态控制 Topic 接口

接口名/motion/control/move_waist
功能概述腰部姿态控制
接口类型 ros2 topic
入参
text

{
  "header": {
    "timestamp": {
      "seconds": 1763681490,
      "nanos": 943287000,
      "ms_since_epoch": 1763681490943
   ]   单位：弧度
  double waist_yaw         // range: [-1.6, 1.6] 单位：弧度
  double waist_height     // range: [-0.3, 0.0]   单位：米
示例脚本examples/mc/move_waist.py
备注
  • 该消息的ROS2 类型为 ros2_plugin_proto/msg/RosMsgWrapper，需要 source prebuilt/ros2_plugin_proto_aarch64/share/ros2_plugin_proto/local_setup.bash 后使用
  • 由于motion_player模块一直在向motion_control模块下发命令，在下发命令前请关闭motion_player模块

7.1.7 脖子控制指令、状态 Topic 接口

接口名/motion/control/neck_joint_command
功能概述脖子控制指令
接口类型 ROS2 Topic
入参sensor_msgs::msg::JointState
  • name：关节名称，固定填写为 ["head_yaw_joint", "head_pitch_joint"]
  • position：关节角度，第一个值代表摇头自由度，范围 -1.04720 到 1.04720，第二个值代表点头自由度，范围 -0.43633 到 0.26180
  • velocity: 无效字段，不填
  • effort: 无效字段，不填
示例脚本examples/mc/neck.py
备注
  • 注意该接口仅在motion状态下可被调用
接口名/motion/control/neck_joint_state
功能概述脖子状态话题
接口类型 ROS2 Topic
出参sensor_msgs::msg::JointState
  • position：关节角度，第一个值代表摇头自由度，范围 -1.04720 到 1.04720，第二个值代表点头自由度，范围 -0.43633 到 0.26180
示例脚本examples/mc/joint_state.py
备注
  • 由于motion_player模块一直在向motion_control模块下发命令，在下发命令前请关闭motion_player模块

7.1.8 手指控制指令、状态 Topic 接口

接口名/motion/control/hand_joint_command
功能概述手指控制指令
接口类型 ROS2 Topic
入参sensor_msgs::msg::JointState
  • frame_id: A3 的手部类型。A3 支持 AgiHand 和 O10Hand 两种类型；不填写时默认 AgiHand。当前手部类型可通过 hand_joint_state 话题中 header.frame_id 字段识别
  • name：关节名称，可不填，保持默认即可,或从hand_joint_state话题中的name字段获取
  • position：关节角度，顺序与name字段关节对应，范围 0 到 2000，抽象值无单位，0 代表完全张开，2000 代表完全并拢
  • velocity: 无效字段，不填
  • effort: 关节力矩，暂时无效，后续版本更新
示例脚本examples/mc/hand.py
备注
  • 本接口有调用限制，仅可在 motion 调用
  • 由于motion_player模块一直在向motion_control模块下发命令，在下发命令前请关闭motion_player模块
接口名/motion/control/hand_joint_state
功能概述手指状态话题
接口类型 ROS2 Topic
出参sensor_msgs::msg::JointState
  • name：各个手指的关节名称
  • frame_id：A2手部类型
  • position：各个手指的关节角度，范围 0 到 4096
  • velocity：无效字段
  • effort：各个手指的力矩，暂时无效，后续版本更新。
    AgiHand的出参为12维对应每个关节，O10Hand出参由多维数组拼接。
    包含双手的压力传感器阵列数据。数据排列如下：
    - 左手压力: 16维 thumb + 16维 index + 16维 middle + 16维 ring + 16维 pinky + 25维 palm (掌心) + 25维 back_of_hand (手背)
    - 右手压力：结构和顺序与左手相同，追加在左手数据之后
示例脚本examples/mc/joint_state.py
备注
  • 位置因零位影响，可能范围略微有所漂移，为正常现象

7.1.9 开启手臂柔顺

接口名pb:/aimdk.protocol.MotionControlMotionService/EnableArmCompliance
功能概述进入手臂柔顺模式
接口类型 HTTP JSON RPC
URLhttp://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlMotionService/EnableArmCompliance
入参
text
{
}
出参
text
{
    "header":{
        "code":"1",
        "msg":"enabled",
        "timestamp":{
            "seconds":"1790144293",
            "nanos":597150317,
            "ms_since_epoch":"0"},
        "trace_id":"module_mc",
        "domin":""
     },
     "state":"CommonState_SUCCESS"
}
  • msg:enabled表示开启
示例脚本examples/mc/EnableArmCompliance.sh
备注手臂柔顺模式可以提高手臂的控制精度

7.1.10 关闭手臂柔顺

接口名pb:/aimdk.protocol.MotionControlMotionService/DisableArmCompliance
功能概述关闭手臂柔顺模式
接口类型 HTTP JSON RPC
URLhttp://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlMotionService/DisableArmCompliance
入参
text
{
}
出参
text
{
    "header":{
        "code":"1",
        "msg":"disabled",
        "timestamp":{
            "seconds":"1790144293",
            "nanos":597150317,
            "ms_since_epoch":"0"},
        "trace_id":"module_mc",
        "domin":""
     },
     "state":"CommonState_SUCCESS"
}
  • msg:disabled表示关闭
示例脚本examples/mc/DisableArmCompliance.sh
备注

7.1.11 查询手臂柔顺

接口名pb:/aimdk.protocol.MotionControlMotionService/CheckArmCompliance
功能概述查询手臂柔顺模式状态
接口类型 HTTP JSON RPC
URLhttp://10.42.10.12:56322/rpc/aimdk.protocol.MotionControlMotionService/DisableArmCompliance
入参
text
{
}
出参
text
{
    "header":{
        "code":"1",
        "msg":"disabled",
        "timestamp":{
            "seconds":"1790144293",
            "nanos":597150317,
            "ms_since_epoch":"0"},
        "trace_id":"module_mc",
        "domin":""
     },
     "state":"CommonState_SUCCESS"
}
  • msg:disabled表示关闭状态，enabled表示开启状态
示例脚本examples/mc/CheckArmCompliance.sh
备注