运控接口清单

用法：接口速查表用于快速定位接口，介绍、类型、频率和配置要点都在表内；每行最后一列可跳转到附录中对应条目的 JSON 配置。附录的 ```json 块即 RFrame ChannelConfigLoader 可直接加载的最终配置（键为实例名，复制进自己进程的 {"channels": {...}} 即可用；service 条目调用时 method 取服务全名最后一段）。附录 JSON 保留通信使能、路由等关键设置，未列出的字段使用框架默认值。 字段含义见《RFrame 开发指南》§7.3。

1. 关节信息查看

关节信息可在 RobbyLink 产品的「关节点动」页面查看。开发关节相关 Topic / Service 时，可通过该页面查阅关节信息。

2. 接口速查表

表格用于快速定位接口；完整 Hybrid 配置和 Service 请求模板见附录对应条目。

2.1. 发布 Topic（客户端 READER）

Topic	类型	用途	通道和频率	RFrame 关键配置	配置详情
/robotic/joint_states	sensor_msgs/msg/JointState	机器人关节位置、速度、力矩。	Hybrid.ros2； 最高约 100 Hz；	QoS depth=5、best_effort；auto_route=false、require_all=false。	JSON / Schema
/robotic/observed_external_torques	std_msgs/msg/Float64MultiArray	观测外力矩。	Hybrid.ros2； 最高约 100 Hz；	QoS depth=10、reliable；auto_route=false、require_all=false。	JSON / Schema
/robotic/tcp_data	r2_motion_msgs/msg/TCP	腰、左臂、右臂 TCP 位姿。	Hybrid.ros2； 最高约 100 Hz；	QoS depth=10、reliable；auto_route=false、require_all=false。	JSON / Schema
/robotic/joint_trajectory	trajectory_msgs/msg/JointTrajectory	机器人关节轨迹反馈。	Hybrid.ros2； 最高约 100 Hz；	QoS depth=10、reliable；auto_route=false、require_all=false。	JSON / Schema
/robotic/Imu	sensor_msgs/msg/Imu	IMU 数据；Topic 中 I 为大写。	Hybrid.ros2； 最高约 100 Hz；	QoS depth=5、best_effort；auto_route=false、require_all=false。	JSON / Schema
/robotic/ft_sensor_left	geometry_msgs/msg/WrenchStamped	左侧六维力/力矩数据。	Hybrid.ros2； 最高约 100 Hz；	QoS depth=10、reliable；auto_route=false、require_all=false。	JSON / Schema
/robotic/ft_sensor_right	geometry_msgs/msg/WrenchStamped	右侧六维力/力矩数据。	Hybrid.ros2； 最高约 100 Hz；	QoS depth=10、reliable；auto_route=false、require_all=false。	JSON / Schema

2.2. 订阅 Topic（客户端 WRITER）

Topic	类型	用途	通道	RFrame 关键配置	配置详情
/robotic/servoj_data	r2_motion_msgs/msg/ServoJ	ServoJ 实时关节目标；要求 ServoJ(2)	Hybrid.ros2	QoS depth=10、reliable；auto_route=false、require_all=false。	JSON / Schema
/robotic/servo_ry_hand_data	r2_motion_msgs/msg/ServoRYHandDual	双灵巧手实时目标。	Hybrid.ros2	QoS depth=10、reliable；auto_route=false、require_all=false。	JSON / Schema 与构型相关

2.3. Hybrid RPC Service

Service	类型	用途	RFrame 关键配置	配置详情
/robotic/movej_cmd	r2_motion_msgs/srv/MoveJ	关节空间运动。	Hybrid RPC（ROS2）；auto_route=false。	JSON / Schema
/robotic/movel_cmd	r2_motion_msgs/srv/MoveL	笛卡尔直线运动。	Hybrid RPC（ROS2）；auto_route=false。	JSON / Schema
/robotic/task_status_cmd	r2_motion_msgs/srv/TaskStatus	按 task_id 查询任务状态。	Hybrid RPC（ROS2）；auto_route=false。	JSON / Schema
/robotic/stop_cmd	std_srvs/srv/Trigger	停止运动。	Hybrid RPC（ROS2）；auto_route=false。	JSON / Schema
/robotic/release_stop	std_srvs/srv/Trigger	解除软停止。	Hybrid RPC（ROS2）；auto_route=false。	JSON / Schema
/robotic/global_vel_cmd	r2_motion_msgs/srv/GlobalVel	设置全局速度。	Hybrid RPC（ROS2）；auto_route=false。	JSON / Schema
/robotic/move_gripper_cmd	r2_motion_msgs/srv/MoveGripper	控制左右夹爪位置。	Hybrid RPC（ROS2）；auto_route=false。	JSON / Schema
/robotic/sucker_control_cmd	r2_motion_msgs/srv/SuckerControl	控制左右吸盘状态：正常（0）、吸气（1）、吹气（2）。	Hybrid RPC（ROS2）；auto_route=false。	JSON / Schema
/robotic/motor_sucker_length_angle_control_cmd	r2_motion_msgs/srv/MotorSuckerLengthAngleControl	根据短杆目标行程和机构角度计算左侧电机吸盘两根推杆的位置。 length：两根推杆中较短一根的目标行程，单位 m，并非吸盘末端的笛卡尔前移距离。 angle：吸盘机构末端连杆相对初始水平位置的转角，按机构侧视图逆时针为正，单位 rad，范围约 0～1.5708（0～90°）。 两根推杆最终行程均需在 0～0.036 m 内；可用 length 上限受角度和机构可达性约束。	Hybrid RPC（ROS2）；auto_route=false。	JSON / Schema
/robotic/switch_mode_cmd	r2_motion_msgs/srv/SwitchMode	切换 Motion 运行模式；ServoJ(2)、ServoJForRL(22)、ServoJForVA(23)，返回 Auto(0)。	Hybrid RPC（ROS2）；auto_route=false。	JSON / Schema
/robotic/get_system_state_cmd	r2_motion_msgs/srv/GetSystemState	查询当前 Motion 运行模式、系统状态与错误信息。	Hybrid RPC（ROS2）；auto_route=false。	JSON / Schema

3. 附录：JSON 配置

每条配置对应概览表中的一行，键为实例名。显式保留通信使能与路由等关键设置，其余默认或无作用字段按需省略；框架默认见《RFrame 部署指南》。

3.1. 发布 Topic（客户端 READER）

3.1.1. /robotic/joint_states

{
  "robotic_joint_states": {
    "type": "hybrid",
    "topic": "/robotic/joint_states",
    "handler": "reader",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "sensor_msgs/msg/JointState",
      "qos": {
        "depth": 5,
        "reliability": "best_effort"
      }
    }
  }
}

3.1.1.1. 类型 Schema

类型：sensor_msgs/msg/JointState

来源：ROS 2 Humble 标准模块 sensor_msgs（由 RTypes 声明为依赖）

# This is a message that holds data to describe the state of a set of torque controlled joints.
#
# The state of each joint (revolute or prismatic) is defined by:
#  * the position of the joint (rad or m),
#  * the velocity of the joint (rad/s or m/s) and
#  * the effort that is applied in the joint (Nm or N).
#
# Each joint is uniquely identified by its name
# The header specifies the time at which the joint states were recorded. All the joint states
# in one message have to be recorded at the same time.
#
# This message consists of a multiple arrays, one for each part of the joint state.
# The goal is to make each of the fields optional. When e.g. your joints have no
# effort associated with them, you can leave the effort array empty.
#
# All arrays in this message should have the same size, or be empty.
# This is the only way to uniquely associate the joint name with the correct
# states.

std_msgs/Header header

string[] name
float64[] position
float64[] velocity
float64[] effort

语义说明：header.stamp 为本次发布时间，当前不填写 frame_id；name、position、velocity、effort 语义上按相同索引对应，关节数量和顺序取决于当前机器人构型，不可假定固定长度。

机器人本体轴的 position 单位为 rad，velocity 单位为 rad/s，effort 为关节力矩，单位 N·m。配置夹爪时可能追加 GripperL、GripperR：其位置是无量纲闭合比例，0 为完全张开、1 为完全闭合，effort 为电流 A；还可能追加用于 URDF 展示的虚拟关节。

配置 RYHand 时会追加手指关节，其位置、速度和电流分别按 rad、rad/s、mA 表示。

3.1.2. /robotic/observed_external_torques

{
  "robotic_observed_external_torques": {
    "type": "hybrid",
    "topic": "/robotic/observed_external_torques",
    "handler": "reader",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "std_msgs/msg/Float64MultiArray"
    }
  }
}

3.1.2.1. 类型 Schema

类型：std_msgs/msg/Float64MultiArray

来源：ROS 2 Humble 标准模块 std_msgs（由 RTypes 声明为依赖）

# This was originally provided as an example message.
# It is deprecated as of Foxy
# It is recommended to create your own semantically meaningful message.
# However if you would like to continue using this please use the equivalent in example_msgs.

# Please look at the MultiArrayLayout message definition for
# documentation on all multiarrays.

MultiArrayLayout  layout        # specification of data layout
float64[]         data          # array of data

语义说明：data 为运动学/动力学模块计算并滤波后的观测外力矩，按 RobbyMotion 内部机器人轴顺序排列，单位按关节力矩约定为 N·m；不包含关节名称，消费端应使用当前构型的关节顺序进行对应。

3.1.3. /robotic/tcp_data

{
  "robotic_tcp_data": {
    "type": "hybrid",
    "topic": "/robotic/tcp_data",
    "handler": "reader",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "r2_motion_msgs/msg/TCP"
    }
  }
}

3.1.3.1. 类型 Schema

类型：r2_motion_msgs/msg/TCP

来源：RTypes develop：ros2_types/r2_motion_msgs/msg/TCP.msg

# TCP.msg
#
# 定义一个消息，用于发布腰部、左臂、右臂的目标位姿

# 腰部目标位姿
geometry_msgs/Pose pose_waist
# 左臂目标位姿
geometry_msgs/Pose pose_l
# 右臂目标位姿
geometry_msgs/Pose pose_r

语义说明：pose_waist、pose_l、pose_r 分别对应当前运动学模型中的 hip_roll_link、left_tip_link、right_tip_link 位姿；position 单位为 m，orientation 为四元数。

该消息没有 Header，无法从消息自身识别时间戳和参考坐标系，调用方必须与当前 RobbyMotion 运动学模型的参考系约定保持一致。

3.1.4. /robotic/joint_trajectory

{
  "robotic_joint_trajectory": {
    "type": "hybrid",
    "topic": "/robotic/joint_trajectory",
    "handler": "reader",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "trajectory_msgs/msg/JointTrajectory"
    }
  }
}

3.1.4.1. 类型 Schema

类型：trajectory_msgs/msg/JointTrajectory

来源：ROS 2 Humble 标准模块 trajectory_msgs（由 RTypes 声明为依赖）

# The header is used to specify the coordinate frame and the reference time for
# the trajectory durations
std_msgs/Header header

# The names of the active joints in each trajectory point. These names are
# ordered and must correspond to the values in each trajectory point.
string[] joint_names

# Array of trajectory points, which describe the positions, velocities,
# accelerations and/or efforts of the joints at each time point.
JointTrajectoryPoint[] points

语义说明：该 Topic 是机器人状态快照，不是可直接送给轨迹控制器执行的时间参数化轨迹。

消息固定包含两个点：points[0] 为实际 position/velocity/effort，points[1] 为目标 position/velocity/effort；当前不填写 accelerations 和 time_from_start。

机器人本体轴分别使用 rad、rad/s、N·m；配置夹爪时会在末尾追加 GripperL/GripperR，其位置为 [0,1] 闭合比例，目标速度和目标 effort 当前填 0。

3.1.5. /robotic/Imu

{
  "robotic_Imu": {
    "type": "hybrid",
    "topic": "/robotic/Imu",
    "handler": "reader",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "sensor_msgs/msg/Imu",
      "qos": {
        "depth": 5,
        "reliability": "best_effort"
      }
    }
  }
}

3.1.5.1. 类型 Schema

类型：sensor_msgs/msg/Imu

来源：ROS 2 Humble 标准模块 sensor_msgs（由 RTypes 声明为依赖）

# This is a message to hold data from an IMU (Inertial Measurement Unit)
#
# Accelerations should be in m/s^2 (not in g's), and rotational velocity should be in rad/sec
#
# If the covariance of the measurement is known, it should be filled in (if all you know is the
# variance of each measurement, e.g. from the datasheet, just put those along the diagonal)
# A covariance matrix of all zeros will be interpreted as "covariance unknown", and to use the
# data a covariance will have to be assumed or gotten from some other source
#
# If you have no estimate for one of the data elements (e.g. your IMU doesn't produce an
# orientation estimate), please set element 0 of the associated covariance matrix to -1
# If you are interpreting this message, please check for a value of -1 in the first element of each
# covariance matrix, and disregard the associated estimate.

std_msgs/Header header

geometry_msgs/Quaternion orientation
float64[9] orientation_covariance # Row major about x, y, z axes

geometry_msgs/Vector3 angular_velocity
float64[9] angular_velocity_covariance # Row major about x, y, z axes

geometry_msgs/Vector3 linear_acceleration
float64[9] linear_acceleration_covariance # Row major x, y z

语义说明：orientation 由设备输出的 Roll、Pitch、Yaw 角转换为四元数；角度输入按 degree 转为 rad 后参与计算。angular_velocity 和linear_acceleration 当前直接复制 IMU 设备原始字段。

三组 covariance 当前均保持全零，按 ROS 语义表示协方差未知。header.stamp 为发布时间；header.frame_id 当前是递增数字字符串，不是稳定 TF 坐标系名称，不能用于 TF 查找或坐标变换。

3.1.6. /robotic/ft_sensor_left

{
  "robotic_ft_sensor_left": {
    "type": "hybrid",
    "topic": "/robotic/ft_sensor_left",
    "handler": "reader",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "geometry_msgs/msg/WrenchStamped"
    }
  }
}

3.1.6.1. 类型 Schema

类型：geometry_msgs/msg/WrenchStamped

来源：ROS 2 Humble 标准模块 geometry_msgs（由 RTypes 声明为依赖）

# A wrench with reference coordinate frame and timestamp

std_msgs/Header header
Wrench wrench

语义说明：仅在左侧配置为六维力传感器且底层数据至少包含6项时发布。

传感器数组 [0,1,2] 映射到 wrench.force.{x,y,z}，[3,4,5] 映射到wrench.torque.{x,y,z}；按 WrenchStamped 约定，单位分别为 N 和 N·m。

header.stamp 为发布时间，header.frame_id 固定为 left_kw_ft_link。

3.1.7. /robotic/ft_sensor_right

{
  "robotic_ft_sensor_right": {
    "type": "hybrid",
    "topic": "/robotic/ft_sensor_right",
    "handler": "reader",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "geometry_msgs/msg/WrenchStamped"
    }
  }
}

3.1.7.1. 类型 Schema

类型：geometry_msgs/msg/WrenchStamped

来源：ROS 2 Humble 标准模块 geometry_msgs（由 RTypes 声明为依赖）

# A wrench with reference coordinate frame and timestamp

std_msgs/Header header
Wrench wrench

语义说明：仅在右侧配置为六维力传感器且底层数据至少包含6项时发布。

传感器数组 [0,1,2] 映射到 wrench.force.{x,y,z}，[3,4,5] 映射到wrench.torque.{x,y,z}；按 WrenchStamped 约定，单位分别为 N 和 N·m。

header.stamp 为发布时间，header.frame_id 固定为 right_kw_ft_link。

3.2. 订阅 Topic（客户端 WRITER）

3.2.1. /robotic/servoj_data

{
  "robotic_servoj_data": {
    "type": "hybrid",
    "topic": "/robotic/servoj_data",
    "handler": "writer",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "r2_motion_msgs/msg/ServoJ"
    }
  }
}

3.2.1.1. 类型 Schema

类型：r2_motion_msgs/msg/ServoJ

来源：RTypes develop：ros2_types/r2_motion_msgs/msg/ServoJ.msg

# ServoJ.msg
#
# 定义一个消息，用于接收VLA关节位置控制指令

# 关节数组，包含所有需要控制的关节位置数据
float32[] joint
# 左手夹爪开合度控制指令 [0.0-1.0, 1.0完全闭合, 0.0完全张开]
float32 gripper_l
# 右手夹爪开合度控制指令 [0.0-1.0, 1.0完全闭合, 0.0完全张开]
float32 gripper_r

语义说明：仅在运行模式为 ServoJ(2) 时处理，其他模式下消息会被静默忽略。

joint 按 RobbyMotion 当前内部轴顺序填写，单位为 rad，正常情况下长度至少等于当前机器人轴数，多余元素会被截断；兼容旧20维输入的指定21轴机型会在索引19补入 J_NeckYaw=0，并将旧索引19映射到索引20的 J_NeckPitch。

关节目标必须为有限值，并符合当前构型的关节限位。

gripper_l、gripper_r 为无量纲闭合比例，建议取有限值 [0,1]，0 为完全张开、1 为完全闭合。

3.2.2. /robotic/servo_ry_hand_data

{
  "robotic_servo_ry_hand_data": {
    "type": "hybrid",
    "topic": "/robotic/servo_ry_hand_data",
    "handler": "writer",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "r2_motion_msgs/msg/ServoRYHandDual"
    }
  }
}

3.2.2.1. 类型 Schema

类型：r2_motion_msgs/msg/ServoRYHandDual

来源：RTypes develop：ros2_types/r2_motion_msgs/msg/ServoRYHandDual.msg

# ServoRYHandDual.msg
#
# 定义一个消息，用于接收双 RYHand 手指开合度实时控制指令

# 左手 RYHand 6 个手指开合度控制指令 [0.0-1.0]
float32[6] left_finger_open_ratio
# 右手 RYHand 6 个手指开合度控制指令 [0.0-1.0]
float32[6] right_finger_open_ratio

语义说明：控制双 RYHand 的手指开合，需配置 RYHand 执行器；支持 Remote(1)、ServoJ(2)、ServoJForRL(22)、ServoJForVA(23)，其他模式下忽略消息。本消息不包含机器人本体关节目标；与本页关节实时控制配合时，在 ServoJ(2) 模式下另向 /robotic/servoj_data 发送关节目标。

left_finger_open_ratio和 right_finger_open_ratio 各固定6项，API顺序为 [拇指滑块、食指滑块、中指滑块、无名指滑块、小指滑块、拇指根部]，每项必须为有限值 [0,1]。尽管字段名为 open_ratio，实际定义是 0=配置的张开位置、1=配置的闭合位置。

3.3. Service（Hybrid RPC 客户端）

每个 Service 使用独立的 Hybrid RPC 配置，ros2.service_type 与该 Service 类型保持一致。本文仅启用 ROS2：Topic 显式设置 enable_remote=true，Service 显式设置 enable_ros2=true，两者均保留 enable_shm=false、auto_route=false。省略单通路无作用的 preferred_ingress 和当前 ROS2 runtime 不读取的 spin_internally。两个 service_prefix 均保留为 /robotic，因为显式提供 ros2 块时，子通道前缀默认仍为 /r/frame/rpc，不会继承外层前缀。客户端需正常启动 RFrame ROS2 runtime 的 executor。

超时设置：附录 JSON 中的 5000 ms 仅为可修改的示例值，不是接口要求，也不是经过实测确定的统一推荐值。请根据服务响应耗时、网络延迟及应用可接受的等待时间设置各 Channel 的 ros2.default_timeout_ms。设置过短可能在服务尚未响应时超时，过长则会延迟应用发现无响应；应通过实际调用测试确定合适的值。

本次调用传入正数 RpcCallOptions.timeout_ms 时优先使用该值，否则使用 ros2.default_timeout_ms；后者省略时，当前 ROS2 runtime 默认使用 2000 ms。显式配置 ros2 块时，不继承外层 hybrid_rpc.default_timeout_ms，因此自定义超时仍放在 ros2 下。超时表示等待服务就绪及响应的总时间，不是机器人运动完成时限；调用超时也不代表运动已停止。

3.3.1. /robotic/movej_cmd

• 请求模板：{"task_id":1,"joint":[],"scale":0.1,"start":false}

{
  "robotic_movej_cmd_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/robotic",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false
    },
    "ros2": {
      "service_type": "r2_motion_msgs/srv/MoveJ",
      "service_prefix": "/robotic",
      "default_timeout_ms": 5000
    }
  }
}

3.3.1.1. 类型 Schema

类型：r2_motion_msgs/srv/MoveJ

来源：RTypes develop：ros2_types/r2_motion_msgs/srv/MoveJ.srv

# MoveJ.srv
#
# 定义一个服务，用于关节移动

# 任务ID
int32 task_id
# 关节位置
float32[] joint
# 速度缩放因子
float32 scale
# 是否启动
bool start
---
# 任务ID
int32 task_id
# 错误代码，0表示成功，非0值表示具体的错误类型
ErrorCode error_code

语义说明：需处于 Auto(0) 模式。task_id 是 int32 任务标识；组合任务必须沿用同一个 task_id。

joint 按当前机器人内部轴顺序填写，单位为 rad，正常情况下长度必须等于当前轴数；指定21轴白名单机型兼容旧20维输入，其颈部补位规则为索引19补 J_NeckYaw=0、旧索引19映射到索引20的 J_NeckPitch。

所有关节值必须有限并位于当前机型软限位内，否则返回输入无效。scale 为无量纲速度缩放，建议使用有限值 (0,1]；小于 1e-6 会被拒绝，大于1会在规划器中钳制为1。

start=false 只把任务加入当前组合队列，start=true 触发该批任务规划和执行。响应中的 task_id 为请求值，error_code.error_code=0 仅表示请求已被接受或成功开始规划，不表示运动已经完成；最终结果应通过 /robotic/task_status_cmd 查询。

3.3.2. /robotic/movel_cmd

• 请求模板：{"task_id":1,"pose_l":{"position":{"x":0.0,"y":0.0,"z":0.0},"orientation":{"x":0.0,"y":0.0,"z":0.0,"w":1.0}},"pose_r":{"position":{"x":0.0,"y":0.0,"z":0.0},"orientation":{"x":0.0,"y":0.0,"z":0.0,"w":1.0}},"nullspace":[],"scale":0.1,"start":false}

{
  "robotic_movel_cmd_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/robotic",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false
    },
    "ros2": {
      "service_type": "r2_motion_msgs/srv/MoveL",
      "service_prefix": "/robotic",
      "default_timeout_ms": 5000
    }
  }
}

3.3.2.1. 类型 Schema

类型：r2_motion_msgs/srv/MoveL

来源：RTypes develop：ros2_types/r2_motion_msgs/srv/MoveL.srv

# MoveJPath.srv
#
# 定义一个服务，用于笛卡尔空间内的直线运动

# 任务ID
int32 task_id
# 左臂TCP位姿
geometry_msgs/Pose pose_l
# 右臂TCP位姿
geometry_msgs/Pose pose_r
# 零位置空间
float32[] nullspace
# 速度缩放因子
float32 scale
# 是否启动
bool start
---
# 任务ID
int32 task_id
# 错误代码，0表示成功，非0值表示具体的错误类型
ErrorCode error_code

语义说明：需处于 Auto(0) 模式。pose_l 和 pose_r 分别表示左右臂 TCP 目标位姿，position 单位为 m，orientation 为四元数。请求没有 Header，无法携带坐标系，位姿必须使用当前运动学模型约定的参考系。位置和四元数各分量必须为有限值，四元数须归一化为单位四元数。

nullspace 是当前MoveL 模板中姿态任务使用的冗余关节参考，单位为 rad，其长度和顺序由当前构型及激活的运动模板决定；接口层不做严格长度校验，错误可能在规划阶段暴露。

scale 建议为有限值 (0,1]，小于 1e-6 会被拒绝，大于1在规划器中钳制为1。start=false 加入组合队列，start=true 触发同一 task_id 下的组合规划。响应成功不等于运动完成，最终状态应通过任务状态接口查询。

3.3.3. /robotic/task_status_cmd

• 请求模板：{"task_id":1}

{
  "robotic_task_status_cmd_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/robotic",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false
    },
    "ros2": {
      "service_type": "r2_motion_msgs/srv/TaskStatus",
      "service_prefix": "/robotic",
      "default_timeout_ms": 5000
    }
  }
}

3.3.3.1. 类型 Schema

类型：r2_motion_msgs/srv/TaskStatus

来源：RTypes develop：ros2_types/r2_motion_msgs/srv/TaskStatus.srv

# TaskStatus.srv
#
# 定义一个服务，用于查询任务状态

# 任务ID
int32 task_id
---
# 任务ID
int32 task_id
# 任务状态
int32 status
# 任务消息
string message

# status定义
int32 TASK_FINISHED=0
int32 TASK_NOT_START=1
int32 TASK_RUNNING=2
int32 TASK_ERROR=3
int32 TASK_NOT_FOUND=4

语义说明：task_id 为待查询的运动任务标识，响应原样回显。status 枚举为：0=TASK_FINISHED，任务成功结束；1=TASK_NOT_START，任务已登记但尚未开始；2=TASK_RUNNING，任务执行中；3=TASK_ERROR，任务失败；4=TASK_NOT_FOUND，任务不存在。TASK_ERROR 时，message 包含底层错误码和错误文本。

通过start=false 暂存但尚未由 start=true 提交的组合任务可能还未登记到任务管理器，此时查询可能返回 TASK_NOT_FOUND。任务记录没有在该接口中承诺永久保存，调用方不应把它作为持久化历史接口。

3.3.4. /robotic/stop_cmd

• 请求模板：{}

{
  "robotic_stop_cmd_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/robotic",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false
    },
    "ros2": {
      "service_type": "std_srvs/srv/Trigger",
      "service_prefix": "/robotic",
      "default_timeout_ms": 5000
    }
  }
}

3.3.4.1. 类型 Schema

类型：std_srvs/srv/Trigger

来源：ROS 2 Humble 标准模块 std_srvs（由 RTypes 声明为依赖）

---
bool success   # indicate successful run of triggered service
string message # informational, e.g. for error messages

语义说明：接口触发 RobbyMotion 软件软停止，不等同于安全等级硬件急停。调用后会锁存软停止状态，把正在运行的运动任务标记为 TASK_ERROR/SafeEmergencyStop，清理 JointJog 输入，并向底盘请求软停。

success=true 表示软停止处理已被接受，不保证服务返回瞬间所有机构已经物理静止；调用方仍应观察系统状态和实际速度。软停止后普通运动命令会被拒绝，恢复需调用 /robotic/release_stop。

3.3.5. /robotic/release_stop

• 请求模板：{}

{
  "robotic_release_stop_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/robotic",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false
    },
    "ros2": {
      "service_type": "std_srvs/srv/Trigger",
      "service_prefix": "/robotic",
      "default_timeout_ms": 5000
    }
  }
}

3.3.5.1. 类型 Schema

类型：std_srvs/srv/Trigger

来源：ROS 2 Humble 标准模块 std_srvs（由 RTypes 声明为依赖）

---
bool success   # indicate successful run of triggered service
string message # informational, e.g. for error messages

语义说明：该接口仅解除 RobbyMotion 软件软停止，不能解除硬件急停、HARD_STOP 或 FAULT。调用时会尝试清理软停运行态、恢复到 Auto 模式、进入 IDLE 并安装 MoveHold，随后等待最多约200 ms确认状态恢复；恢复失败或状态不一致时会重新触发软停止并返回失败。

接口具有幂等性：当前未处于软停止时调用也返回成功。释放软停止不会恢复此前失败任务，调用方需要重新提交运动命令。

3.3.6. /robotic/global_vel_cmd

• 请求模板：{"global_vel":0.1}

{
  "robotic_global_vel_cmd_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/robotic",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false
    },
    "ros2": {
      "service_type": "r2_motion_msgs/srv/GlobalVel",
      "service_prefix": "/robotic",
      "default_timeout_ms": 5000
    }
  }
}

3.3.6.1. 类型 Schema

类型：r2_motion_msgs/srv/GlobalVel

来源：RTypes develop：ros2_types/r2_motion_msgs/srv/GlobalVel.srv

# GlobalVel.srv
#
# 定义一个服务，用于设置机械臂全局速度

float32 global_vel  # 全局速度值，用于控制机器人的整体运动速度
---
# 错误代码，0表示成功，非0值表示具体的错误类型
ErrorCode error_code

语义说明：global_vel 是机器人全局速度无量纲缩放系数，建议提供有限值 [0,1]。

3.3.7. /robotic/move_gripper_cmd

• 请求模板：{"gripper_l":0.0,"gripper_r":0.0}

{
  "robotic_move_gripper_cmd_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/robotic",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false
    },
    "ros2": {
      "service_type": "r2_motion_msgs/srv/MoveGripper",
      "service_prefix": "/robotic",
      "default_timeout_ms": 5000
    }
  }
}

3.3.7.1. 类型 Schema

类型：r2_motion_msgs/srv/MoveGripper

来源：RTypes develop：ros2_types/r2_motion_msgs/srv/MoveGripper.srv

# MoveGripper.srv
#
# 定义一个服务，用于控制夹爪位置

# 左夹爪位置
float32 gripper_l
# 右夹爪位置
float32 gripper_r
---
# 错误代码，0表示成功，非0值表示具体的错误类型
ErrorCode error_code

语义说明：gripper_l 和 gripper_r 分别为左右传统夹爪的无量纲闭合比例，0 表示完全张开，1 表示完全闭合；执行层会把有限的越界值钳制到 [0,1]。

3.3.8. /robotic/sucker_control_cmd

• 请求模板：{"sucker_l":[0,0],"sucker_r":[0,0]}

{
  "robotic_sucker_control_cmd_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/robotic",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false
    },
    "ros2": {
      "service_type": "r2_motion_msgs/srv/SuckerControl",
      "service_prefix": "/robotic",
      "default_timeout_ms": 5000
    }
  }
}

3.3.8.1. 类型 Schema

类型：r2_motion_msgs/srv/SuckerControl

来源：RTypes：r2_motion_msgs/srv/SuckerControl.srv

# SuckerControl.srv
#
# 定义一个服务，用于控制吸盘的工作状态

# 左吸盘: 0: 正常 1: 吸气 2: 吹气
int32[] sucker_l
# 右吸盘: 0: 正常 1: 吸气 2: 吹气
int32[] sucker_r
---
# 错误代码，0表示成功，非0值表示具体的错误类型
ErrorCode error_code

# 正常
int32 CONTROL_NORMAL=0
# 吸气
int32 CONTROL_SNIFF=1
# 吹气
int32 CONTROL_BLOW=2

语义说明：sucker_l、sucker_r 分别对应左右吸盘，每侧最多提供两个控制值：0=正常、1=吸气、2=吹气。当前实现每侧只读取前两项，缺少项补 0，多余项忽略；缺省不表示保持原状态。夹爪集成吸盘和电机吸盘每侧只使用第一个控制值。error_code.error_code=0 表示请求已被接受，不表示已达到目标真空度。

3.3.9. /robotic/motor_sucker_length_angle_control_cmd

• 请求模板：{"length":0,"angle":0}

{
  "robotic_motor_sucker_length_angle_control_cmd_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/robotic",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false
    },
    "ros2": {
      "service_type": "r2_motion_msgs/srv/MotorSuckerLengthAngleControl",
      "service_prefix": "/robotic",
      "default_timeout_ms": 5000
    }
  }
}

3.3.9.1. 类型 Schema

类型：r2_motion_msgs/srv/MotorSuckerLengthAngleControl

来源：RTypes：r2_motion_msgs/srv/MotorSuckerLengthAngleControl.srv

# MotorSuckerLengthAngleControl.srv
#
# 根据短杆长度和 相对水平角度控制左侧电机吸盘两根推杆。

# 两根推杆中较短那条的目标行程，单位 m
float32 length
# 吸盘机构末端连杆相对初始水平位置的转角，单位 rad，逆时针为正
float32 angle
---
# 错误代码，0表示成功，非0值表示具体的错误类型
ErrorCode error_code

语义说明：用于设置左侧电机吸盘的推杆伸出量和末端连杆转角，系统自动换算成两根推杆的目标位置。length 是两根推杆中较短一根的伸出行程，单位 m，范围 0～0.036（即0～36 mm）；angle 是吸盘机构末端连杆相对初始水平位置的转角，单位 rad：范围约 0～1.5708（0～90°），0 表示初始水平位置，方向按机构侧视图逆时针为正。

length 不是吸盘末端在空间中的前移距离，angle 也不是机械臂的姿态角。两项需要配合设置：换算后的两根推杆都不能超过 36 mm 行程，无法达到的组合会返回错误。适用于配有电机吸盘的机型；若右侧也配置了电机吸盘，本次调用还会将右侧两根推杆的目标设为零行程。返回 error_code.error_code=0 表示请求已接受，推杆可能仍在运动。

3.3.10. /robotic/switch_mode_cmd

• 请求模板：{"mode":2,"impedance":false}

{
  "robotic_switch_mode_cmd_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/robotic",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false
    },
    "ros2": {
      "service_type": "r2_motion_msgs/srv/SwitchMode",
      "service_prefix": "/robotic",
      "default_timeout_ms": 5000
    }
  }
}

3.3.10.1. 类型 Schema

类型：r2_motion_msgs/srv/SwitchMode

来源：RTypes：r2_motion_msgs/srv/SwitchMode.srv

# SwitchMode.srv
#
# 定义一个服务，用于切换模式

# 运行模式，取值见下方 mode 定义

# 自动模式
int32 MODE_AUTO=0
# 遥操作模式
int32 MODE_REMOTE=1
# ServoL 力控模式（废弃）
int32 MODE_SERVOL_FT=11
# 遥操作 remap 模式
int32 MODE_REMOTE_REMAP=12
# ServoJ 模式
int32 MODE_SERVOJ=2
# ServoJ 力控模式（废弃）
int32 MODE_SERVOJ_FT=21
# ServoJ 给RL注册的模式
int32 MODE_SERVOJ_RL=22
# ServoJ 给VA注册的模式
int32 MODE_SERVOJ_VA=23
# ServoJ Remap 模式
int32 MODE_SERVOJ_REMAP=24
# ServoJ Stamped Chunk模式
int32 MODE_SERVOJ_STAMPED=25
# 单关节 Jog 模式
int32 MODE_JOINT_JOG=26
# 平衡模式（废弃）
int32 MODE_BALANCE=3
# 手动拖动模式
int32 MODE_MANUAL_DRAG=4
# 拖动力控模式
int32 MODE_DRAG_FT=51
# 测试模式
int32 MODE_TEST=99

# 请求切换的目标模式
int32 mode
# 是否阻抗
bool impedance
---
# 服务调用结果
bool success
# 错误代码，0表示成功，非0值表示具体的错误类型
ErrorCode error_code

语义说明：调用 method 为 switch_mode_cmd，完整服务名为 /robotic/switch_mode_cmd。本表的 /robotic/servoj_data 使用 mode=2（ServoJ）；/robotic/servo_ry_hand_data 支持 mode=1（Remote）、2（ServoJ）、22（ServoJForRL）、23（ServoJForVA）。普通 MoveJ/MoveL 使用 mode=0（Auto），已处于 Auto 时无需重复切换。

先在机器人已使能且处于 IDLE 时调用模式切换，确认 success=true 且 error_code.error_code=0 后，再向对应 Topic 发送目标。FAULT、软停止、硬停止、未上电、未使能或非 IDLE 状态下不能按此接口正常切换；切换失败应检查 error_code.message。impedance=false 为普通位置控制；true 仅支持 Auto(0)、Remote(1)、ServoJ(2)、ServoJStamped(25)，还要求对应运动配置及传感器健康检查通过，RL(22)/VA(23) 应设为 false。

不支持切换到 mode=11、12、21、24；本页关节实时控制使用 mode=2，普通 MoveJ/MoveL 使用 mode=0。

3.3.11. /robotic/get_system_state_cmd

• 请求模板：{}

{
  "robotic_get_system_state_cmd_rpc": {
    "type": "hybrid_rpc",
    "hybrid_rpc": {
      "service_prefix": "/robotic",
      "enable_shm": false,
      "enable_ros2": true,
      "auto_route": false
    },
    "ros2": {
      "service_type": "r2_motion_msgs/srv/GetSystemState",
      "service_prefix": "/robotic",
      "default_timeout_ms": 5000
    }
  }
}

3.3.11.1. 类型 Schema

类型：r2_motion_msgs/srv/GetSystemState

来源：RTypes：r2_motion_msgs/srv/GetSystemState.srv

# GetSystemState.srv
#
# 定义一个服务，用于获取系统当前的状态

---
# 系统状态码，表示当前机器人系统的运行状态
int32 state
# 状态描述信息，包含当前状态的详细说明
string message
# 错误码，表示当前状态下可能出现的错误类型
ErrorCode error_code
# 运行模式，取值见下方 run_mode 定义
uint8 run_mode
# 底盘是否启动
bool cmd_start
# 底盘状态码
int32 chassis_state_code

# run_mode 定义
# 自动模式
int32 MODE_AUTO=0
# 遥操作模式
int32 MODE_REMOTE=1
# ServoL 力控模式
int32 MODE_SERVOL_FT=11
# 遥操作 remap 模式
int32 MODE_REMOTE_REMAP=12
# ServoJ 模式
int32 MODE_SERVOJ=2
# ServoJ 力控模式
int32 MODE_SERVOJ_FT=21
# ServoJ 给RL注册的模式
int32 MODE_SERVOJ_RL=22
# ServoJ 给VA注册的模式
int32 MODE_SERVOJ_VA=23
# ServoJ Remap 模式
int32 MODE_SERVOJ_REMAP=24
# ServoJ Stamped Chunk模式
int32 MODE_SERVOJ_STAMPED=25
# 单关节 Jog 模式
int32 MODE_JOINT_JOG=26
# 平衡模式
int32 MODE_BALANCE=3
# 手动拖动模式
int32 MODE_MANUAL_DRAG=4
# 拖动力控模式
int32 MODE_DRAG_FT=51
# 测试模式
int32 MODE_TEST=99

语义说明：空请求，调用 method 为 get_system_state_cmd，完整服务名为 /robotic/get_system_state_cmd。

响应 run_mode 为当前 Motion 运行模式：0=Auto、2=ServoJ、22=ServoJForRL、23=ServoJForVA，可与 /robotic/switch_mode_cmd 配套查询切换前后的模式。

state、message 为系统状态码及描述，与 run_mode 不同；error_code 为系统错误信息，cmd_start、chassis_state_code 为底盘启动标志及状态码。