5.1.8 末端执行器控制

备注

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

末端执行器控制目前支持:

• 灵巧手: 智元 OmniHand 灵动款 2025 / 灵动触觉款 2025

• 夹爪: 智元 OmniPicker

控制方式

末端执行器提供两种控制方式，开发者可按应用场景选择：

• 推荐使用 上肢控制（非底层控制）：通过 /mc/upper_body_command 话题和 UPPERBODY_REMOTE_SPLIT 模式，将手部作为上肢控制体系的一部分统一控制。此模式下运控模块可保持走跑管理等原生功能，无需手动停止运控。

• 底层控制：通过话题 /aima/hal/joint/hand/command 直接向手部发送 HandCommandArray 指令。此方式需在运控计算单元（PC1）上执行 aima em stop-app mc 以禁止原生运控模块接管手部，适用于需要独立控制手部而不使用上肢控制体系的场景。

注意

使用底层控制方式前，应确保机器人处于安全状态，并在运控计算单元（PC1）上执行 aima em stop-app mc 以禁止原生运控模块接管手部控制。

以下章节详述底层控制所需的接口定义。上肢控制的使用方式参见 上肢控制。

底层控制接口

手部控制特点

• 灵巧手模式: 支持多指协调控制，适合复杂操作

• 夹爪模式: 支持开合控制，适合简单抓取

• 状态监控: 实时监控手部状态和故障代码

• 类型查询: 支持动态查询当前手部类型

手部控制话题

话题名称	数据类型	描述	QoS	频率
/aima/hal/joint/hand/command	HandCommandArray	手部控制命令	BEST_EFFORT+VOLATILE	用户发送（按需）

• HandCommandArray ros2-msg @ hal/msg/HandCommandArray.msg

  # 手部控制命令数组
  MessageHeader header             # 消息头
  HandType left_hand_type          # 左手类型（left_hand_type.value：1 (NIMBLE_HANDS 灵巧手), 2 (CLAW 夹爪)）
  HandCommand[] left_hands         # 左手命令
  HandType right_hand_type         # 右手类型（right_hand_type.value：1 (NIMBLE_HANDS 灵巧手), 2 (CLAW 夹爪)）
  HandCommand[] right_hands        # 右手命令
  

  HandType 有效取值为 1 (NIMBLE_HANDS) 和 2 (CLAW)。传入 0 (NONE)、0xFF (ERROR) 或其他值时，该侧手的命令将被静默丢弃，不会执行也不会返回错误。左右手独立处理，互不影响。

  HandCommand[]长度与顺序说明:

  手类型	数组长度	顺序
  夹爪 OmniPicker	1	N/A
  灵巧手 OmniHand	10	按主动轴索引顺序排列，详见关节索引与名称映射

  name 仅作调试辅助，可能随版本变动。识别关节应以数组索引顺序为准，不应依赖 name 字段匹配。

  索引	name（左手）	name（右手）
  0	L_thumb_roll_joint	R_thumb_roll_joint
  1	L_thumb_abad_joint	R_thumb_abad_joint
  2	L_thumb_mcp_joint	R_thumb_mcp_joint
  3	L_index_abad_joint	R_index_abad_joint
  4	L_index_pip_joint	R_index_pip_joint
  5	L_middle_pip_joint	R_middle_pip_joint
  6	L_ring_abad_joint	R_ring_abad_joint
  7	L_ring_pip_joint	R_ring_pip_joint
  8	L_pinky_abad_joint	R_pinky_abad_joint
  9	L_pinky_pip_joint	R_pinky_pip_joint

  • HandCommand ros2-msg @ hal/msg/HandCommand.msg

    # 手部控制命令
    string name                      # 关节名称（可不填）
    float64 position                 # 位置（含义依手类型而异，见下方说明）
    float64 velocity                 # 速度（含义依手类型而异，见下方说明）
    float64 acceleration             # 加速度（含义依手类型而异，见下方说明）
    float64 deceleration             # 减速度（含义依手类型而异，见下方说明）
    float64 effort                   # 力矩（含义依手类型而异，见下方说明）
    

    注意！该消息内的字段含义和取值范围依具体手类型有较大差异:

    • 夹爪 OmniPicker:

      字段名称	取值范围	含义说明
      position	0.0-1.0	线性映射夹爪张合行程, 1.0完全张开
      velocity	0.0-1.0	线性映射夹爪运行速度, 1.0最快速度
      acceleration	0.0-1.0	线性映射夹爪加速度, 1.0最大加速度
      deceleration	0.0-1.0	线性映射夹爪减速度, 1.0最大减速度
      effort	0.0-1.0	线性映射夹爪夹持力矩, 1.0最大力矩

    • 灵巧手 OmniHand:

      字段名称	取值范围	含义说明
      position	相应主动轴活动范围（单位：rad）	当前位置
      velocity	N/A	未使用
      acceleration	N/A	未使用
      deceleration	N/A	未使用
      effort	N/A	未使用

      备注

      灵巧手底层控制当前仅支持下发位置指令（position），velocity、effort、acceleration、deceleration 字段暂未启用。力位混合控制等高级模式请使用 上肢控制。

注意

使用底层控制方式前, 需在运控计算单元（PC1）上执行 aima em stop-app mc 以禁止原生运控模块接管手部。

手部状态信息话题

话题名称	数据类型	描述	QoS	频率
/aima/hal/joint/hand/state	HandStateArray	手部状态信息	BEST_EFFORT+TRANSIENT_LOCAL	200Hz（调度优先级低，负载增大时频率会降低）

• HandStateArray ros2-msg @ hal/msg/HandStateArray.msg

  # 手部状态数组
  MessageHeader header                          # 消息头
  HandType left_hand_type                       # 左手类型
  HandState[] left_hands                        # 左手状态
  HandTouchSensorData left_touch_sensors        # 左手触摸传感器数据
  HandType right_hand_type                      # 右手类型
  HandState[] right_hands                       # 右手状态
  HandTouchSensorData right_touch_sensors       # 右手触摸传感器数据
  

  HandType 取值：

  值	含义	数据有效性
  1 (NIMBLE_HANDS)	灵巧手	有效
  2 (CLAW)	夹爪	有效
  0 (NONE 无)	手部未连接	HandState[] 和 HandTouchSensorData 保持上一次有效值，不会清零
  0xFF (ERROR 错误)	通信异常或固件错误	同上

  • HandTouchSensorData ros2-msg @ hal/msg/HandTouchSensorData.msg

    # 手心触摸传感器数据 (灵巧手 OmniHand: 5×5=25, 仅用前25字节)
    uint8[36] palm_touch_data              # 手心触摸数据
    # 手背触摸传感器数据
    uint8[36] back_of_hand_touch_data      # 手背触摸数据
    
    # 指尖触摸传感器数据 (灵巧手 OmniHand: 共16个传感器, 使用全部16字节)
    uint8[16] thumb_touch_data             # 拇指指尖
    uint8[16] index_finger_touch_data      # 食指指尖
    uint8[16] middle_finger_touch_data     # 中指指尖
    uint8[16] ring_finger_touch_data       # 无名指指尖
    uint8[16] little_finger_touch_data     # 小指指尖
    

  HandState[]长度与顺序说明:

  手类型	数组长度	顺序
  夹爪 OmniPicker	1	N/A
  灵巧手 OmniHand 灵动款 2025 / 灵动触觉款 2025	10	同关节索引与名称映射

  • HandState ros2-msg @ hal/msg/HandState.msg

    # 手部状态信息
    string name                      # 关节名称
    float64 position                 # 当前位置（含义依手类型而异，见下方说明）
    float64 velocity                 # 当前速度（含义依手类型而异，见下方说明）
    float64 effort                   # 当前力矩（含义依手类型而异，见下方说明）
    int32 state                      # 状态
    int32 faultcode                  # 故障代码
    

    注意！该消息内的字段含义和取值范围依具体手类型有较大差异:

    • 夹爪 OmniPicker:

      name 取值为 "claw"。

      字段名称	取值范围	含义说明
      position	0.0-1.0	当前行程，取值范围同前
      velocity	0.0-1.0	当前速度，取值范围同前
      effort	0.0-1.0	当前力矩，取值范围同前
      state	0-已到达目标位置/1-夹爪移动中/2-夹爪堵转/3-物体掉落	状态
      faultcode	0-无故障/1-过温警报/2-超速警报/3-初始化故障警报/4-超限检测警报	故障代码

    • 灵巧手 OmniHand:

      字段名称	取值范围	含义说明
      position	当前位置（单位：rad）	当前位置
      velocity	原始反馈值	当前速度（待适配）
      effort	原始反馈值	当前力矩（待适配）
      state	N/A	暂未使用
      faultcode	原始反馈值	故障代码（待适配）

查询手部类型服务

服务名称	数据类型	描述
/aimdk_5Fmsgs/srv/GetHandType	GetHandType	主动查询手部类型

• GetHandType ros2-srv @ hal/srv/GetHandType.srv

  # 获取手部类型
  # 服务名称: /aimdk_5Fmsgs/srv/GetHandType
  
  # 请求
  CommonRequest request            # 通用请求
  
  ---
  
  # 响应
  CommonResponse reponse           # 通用响应（未启用，请直接读取下方手部类型字段）
  HandType left_hands_type         # 左手类型（left_hands_type.value：1 (NIMBLE_HANDS 灵巧手), 2 (CLAW 夹爪), 0 (NONE 无), 0xFF (ERROR 错误)）
  HandType right_hands_type        # 右手类型（right_hands_type.value：1 (NIMBLE_HANDS 灵巧手), 2 (CLAW 夹爪), 0 (NONE 无), 0xFF (ERROR 错误)）
  

备注

该服务的 reponse 字段未启用，请直接读取 left_hands_type、right_hands_type，不应依赖 reponse.header.code、status 判断成功与否。

编程示例

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

• C++ 示例:

  • 夹爪控制

  • 灵巧手控制

  • 灵巧手触觉数据（T2.1支持）

• Python 示例:

  • 夹爪控制

  • 灵巧手控制

  • 灵巧手触觉数据（T2.1支持）

安全注意事项

警告

• 手部组件自主控制需关闭原生运控, 请注意接管机器人的其他关节, 做好安全防护

• 请勿自行修改手部组件的配置, 特殊系统适配需求请联系技术支持

小心

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

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