Motion Control Interfaces

Draft for website testing. This is a condensed English draft, not a complete translation. Both language versions await final content-owner updates. Original technical details, code comments, tables, and illustrations are retained in Chinese in the expandable reference below.

Read the Chinese source

1. Using the interface reference

The reference tables link to each interface's JSON configuration and message or service Schema. Copy selected entries into {"channels": {...}}; keys are instance names. For a service, the method is the last segment of its full name. See §7.3 of the Development Guide for loader fields.

Unlisted fields use framework defaults. Do not invent additional settings. Joint information is available on the Joint Jogging page in RobbyLink. The source contains configuration-dependent and pending items; their notes are retained below.

2. Feedback topics: client readers

Topic	Data
`/robotic/joint_states`	Joint position, velocity, and effort.
`/robotic/observed_external_torques`	Observed external torque.
`/robotic/tcp_data`	Waist and left/right arm TCP poses.
`/robotic/joint_trajectory`	Joint trajectory feedback.
`/robotic/Imu`	IMU data; the capital `I` is significant.
`/robotic/ft_sensor_left`	Left six-axis force/torque data.
`/robotic/ft_sensor_right`	Right six-axis force/torque data.

The source lists Hybrid ROS 2 feedback up to approximately 100 Hz. Preserve each topic's own QoS and routing settings from the original configuration.

3. Command topics: client writers

Servo commands use /robotic/servoj_data, /robotic/servoj_for_rl_data, and /robotic/servoj_for_va_data, with the corresponding Motion modes ServoJ (2), ServoJForRL (22), and ServoJForVA (23). The combined joint and dexterous-hand entry is configuration-dependent and marked pending in the source. Do not treat its presence as confirmation of support on every robot configuration.

4. Hybrid RPC services

The service set includes joint-space and Cartesian motion, task-state queries, stopping and releasing a soft stop, global velocity, grippers, suction, motorized suction geometry, Motion mode switching, and system-state queries. Preserve the exact request and response schemas in the appendix.

For /robotic/motor_sucker_length_angle_control_cmd, length is the target travel of the shorter pushrod in metres, not Cartesian forward travel of the suction end. angle is the linkage rotation from the initial horizontal position, positive counterclockwise in the side view, in radians (approximately 0–1.5708). Both pushrods must remain within 0–0.036 m; the feasible length depends on angle and mechanism reachability.

5. Configuration and Schema appendix

The complete source below retains explicit JSON and Schema anchors, message fields, enums, units, numeric limits, and code examples. It also retains the source's differing interface counts and pending notes for subsequent owner review. Use the complete Chinese reference for operational details; this English overview is a website test draft.

6. Original technical reference (Chinese)

Expand the original chapters, tables, code, and illustrations

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

关节信息查看

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

接口速查表

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

发布 Topic（客户端 READER）开放7个

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

订阅 Topic（客户端 WRITER）开放3个

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/servoj_for_rl_data`	`r2_motion_msgs/msg/ServoJ`	RL ServoJ；要求 ServoJForRL(22)	Hybrid.ros2	QoS depth=10、reliable；`auto_route=false`、`require_all=false`。	JSON / Schema
`/robotic/servoj_for_va_data`	`r2_motion_msgs/msg/ServoJ`	VA ServoJ；要求 ServoJForVA(23)	Hybrid.ros2	QoS depth=10、reliable；`auto_route=false`、`require_all=false`。	JSON / Schema
`/robotic/servoj_data /robotic/servo_ry_hand_data`	`r2_motion_msgs/msg/ServoJ` `r2_motion_msgs/msg/ServoRYHandDual`	关节与双灵巧手实时目标；要求 ServoJ(2)	Hybrid.ros2	QoS depth=10、reliable；`auto_route=false`、`require_all=false`。	JSON / Schema 待定，跟构型相关

Hybrid RPC Service 开放11个

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

附录：JSON 配置

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

发布 Topic（客户端 READER，7 个）

/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"
      }
    }
  }
}

类型 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 表示。

/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"
    }
  }
}

类型 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；不包含关节名称，消费端应使用当前构型的关节顺序进行对应。

/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"
    }
  }
}

类型 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 运动学模型的参考系约定保持一致。

/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"
    }
  }
}

类型 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。

/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"
      }
    }
  }
}

类型 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 查找或坐标变换。

/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"
    }
  }
}

类型 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。

/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"
    }
  }
}

类型 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。

订阅 Topic（客户端 WRITER，4 个）

/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"
    }
  }
}

类型 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，长度必须至少等于当前机器人轴数；多余元素会被截断。当前接口层不检查关节值是否有限或是否超出软限位，调用方必须发送有限且符合当前构型限位的目标。gripper_l、gripper_r 为无量纲闭合比例，建议取有限值 [0,1]，0 为完全张开、1 为完全闭合。

/robotic/servoj_for_rl_data

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

类型 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

语义说明：仅在运行模式为 ServoJForRL(22) 时处理，其他格式同ServoJ

/robotic/servoj_for_va_data

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

类型 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

语义说明：仅在运行模式为 ServoJForVA(23) 时处理，其他格式同ServoJ。

/robotic/servoj_with_ry_hand_data

{
  "robotic_servoj_with_ry_hand_data": {
    "type": "hybrid",
    "topic": "/robotic/servoj_with_ry_hand_data",
    "handler": "writer",
    "hybrid": {
      "enable_shm": false,
      "enable_remote": true,
      "auto_route": false
    },
    "ros2": {
      "type_name": "r2_motion_msgs/msg/ServoJwithRYhand"
    }
  }
}

类型 Schema

类型：r2_motion_msgs/msg/ServoJwithRYhand

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

# ServoR2withRYhand.msg
#
# 定义一个消息，用于同时接收 R2 关节位置控制和双 RYHand 手指开合度实时控制指令

# 关节数组，包含所有需要控制的关节位置数据
float32[] joint

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

语义说明：仅在运行模式为 ServoJ(2) 且当前构型已配置 RYHand 执行器时处理。joint 按当前内部轴顺序填写，单位为 rad，长度至少等于机器人轴数，多余元素会被截断；指定21轴白名单机型兼容旧20维输入，会在索引19补入 J_NeckYaw=0，并把旧索引19映射到索引20的 J_NeckPitch。left_finger_open_ratio和 right_finger_open_ratio 各固定6项，API顺序为 [拇指滑块、食指滑块、中指滑块、无名指滑块、小指滑块、拇指根部]，每项必须为有限值 [0,1]。尽管字段名为 open_ratio，实际定义是 0=配置的张开位置、1=配置的闭合位置。

Service（Hybrid RPC 客户端，11 个）

每个 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 下。超时表示等待服务就绪及响应的总时间，不是机器人运动完成时限；调用超时也不代表运动已停止。

/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
    }
  }
}

类型 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

语义说明：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 查询。

/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
    }
  }
}

类型 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

语义说明：pose_l 和 pose_r 分别表示左右臂 TCP 目标位姿，position 单位为 m，orientation 为四元数。请求没有 Header，无法携带坐标系，位姿必须使用当前运动学模型约定的参考系。当前接口层不检查位置和四元数的有限性，也不负责归一化四元数，调用方必须提供有效单位四元数。nullspace 是当前MoveL 模板中姿态任务使用的冗余关节参考，单位为 rad，其长度和顺序由当前构型及激活的运动模板决定；接口层不做严格长度校验，错误可能在规划阶段暴露。scale 建议为有限值 (0,1]，大于1在规划器中钳制为1。start=false 加入组合队列，start=true 触发同一 task_id 下的组合规划。响应成功不等于运动完成，最终状态应通过任务状态接口查询。

/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
    }
  }
}

类型 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。任务记录没有在该接口中承诺永久保存，调用方不应把它作为持久化历史接口。

/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
    }
  }
}

类型 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。

/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
    }
  }
}

类型 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确认状态恢复；恢复失败或状态不一致时会重新触发软停止并返回失败。接口具有幂等性：当前未处于软停止时调用也返回成功。释放软停止不会恢复此前失败任务，调用方需要重新提交运动命令。

/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
    }
  }
}

类型 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]。

/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
    }
  }
}

类型 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]。

/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
    }
  }
}

类型 Schema

类型：r2_motion_msgs/srv/SuckerControl

来源：本机 RTypes：r2_motion_msgs/srv/SuckerControl.srv；运行语义核对当前 RobbyMotion 源码。

# 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 表示请求已被接受，不表示已达到目标真空度。

/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
    }
  }
}

类型 Schema

类型：r2_motion_msgs/srv/MotorSuckerLengthAngleControl

来源：本机 RTypes：r2_motion_msgs/srv/MotorSuckerLengthAngleControl.srv；运行语义核对当前 RobbyMotion 源码。

# 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 表示请求已接受，推杆可能仍在运动。

/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
    }
  }
}

类型 Schema

类型：r2_motion_msgs/srv/SwitchMode

来源：本机 RTypes：r2_motion_msgs/srv/SwitchMode.srv；运行语义核对当前 RobbyMotion 源码。

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

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

# 自动模式
int32 MODE_AUTO=0
# 遥操作模式
int32 MODE_REMOTE=1
# ServoL 力控模式（废弃）
int32 MODE_SERVOL_FT=11
# 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。本表已开放的实时输入分别要求 mode=2（ServoJ）、22（ServoJForRL）、23（ServoJForVA）；切回普通 MoveJ/MoveL 使用 mode=0（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。Schema 中的常量不等于本清单全部开放或当前实现全部支持的模式，例如 11、21、24 不在当前支持列表中。

/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
    }
  }
}

类型 Schema

类型：r2_motion_msgs/srv/GetSystemState

来源：本机 RTypes：r2_motion_msgs/srv/GetSystemState.srv；运行语义核对当前 RobbyMotion 源码。

# 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
# ServoJ 模式
int32 MODE_SERVOJ=2
# ServoJ 力控模式
int32 MODE_SERVOJ_FT=21
# ServoJ Remap 模式
int32 MODE_SERVOJ_REMAP=22
# 单关节 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 为底盘启动标志及状态码。本机 Schema 中 MODE_SERVOJ_REMAP=22 的常量名称已滞后且未列出 23，实际模式含义以当前 RobbyMotion 实现为准。

1. Using the interface reference​

2. Feedback topics: client readers​

3. Command topics: client writers​

4. Hybrid RPC services​

5. Configuration and Schema appendix​

6. Original technical reference (Chinese)​

关节信息查看​

接口速查表​

发布 Topic（客户端 READER）开放7个​

订阅 Topic（客户端 WRITER）开放3个​

Hybrid RPC Service 开放11个​

附录：JSON 配置​

发布 Topic（客户端 READER，7 个）​

/robotic/joint_states​

类型 Schema​

/robotic/observed_external_torques​

类型 Schema​

/robotic/tcp_data​

类型 Schema​

/robotic/joint_trajectory​

类型 Schema​

/robotic/Imu​

类型 Schema​

/robotic/ft_sensor_left​

类型 Schema​

/robotic/ft_sensor_right​

类型 Schema​

订阅 Topic（客户端 WRITER，4 个）​

/robotic/servoj_data​

类型 Schema​

/robotic/servoj_for_rl_data​

类型 Schema​

/robotic/servoj_for_va_data​

类型 Schema​

/robotic/servoj_with_ry_hand_data​

类型 Schema​

Service（Hybrid RPC 客户端，11 个）​

/robotic/movej_cmd​

类型 Schema​

/robotic/movel_cmd​

类型 Schema​

/robotic/task_status_cmd​

类型 Schema​

/robotic/stop_cmd​

类型 Schema​

/robotic/release_stop​

类型 Schema​

/robotic/global_vel_cmd​

类型 Schema​

/robotic/move_gripper_cmd​

类型 Schema​

/robotic/sucker_control_cmd​

类型 Schema​

/robotic/motor_sucker_length_angle_control_cmd​

类型 Schema​

/robotic/switch_mode_cmd​

类型 Schema​

/robotic/get_system_state_cmd​

类型 Schema​

1. Using the interface reference

2. Feedback topics: client readers

3. Command topics: client writers

4. Hybrid RPC services

5. Configuration and Schema appendix

6. Original technical reference (Chinese)

关节信息查看

接口速查表

发布 Topic（客户端 READER）开放7个

订阅 Topic（客户端 WRITER）开放3个

Hybrid RPC Service 开放11个

附录：JSON 配置

发布 Topic（客户端 READER，7 个）

/robotic/joint_states

类型 Schema

/robotic/observed_external_torques

类型 Schema

/robotic/tcp_data

类型 Schema

/robotic/joint_trajectory

类型 Schema

/robotic/Imu

类型 Schema

/robotic/ft_sensor_left

类型 Schema

/robotic/ft_sensor_right

类型 Schema

订阅 Topic（客户端 WRITER，4 个）

/robotic/servoj_data

类型 Schema

/robotic/servoj_for_rl_data

类型 Schema

/robotic/servoj_for_va_data

类型 Schema

/robotic/servoj_with_ry_hand_data

类型 Schema

Service（Hybrid RPC 客户端，11 个）

/robotic/movej_cmd

类型 Schema

/robotic/movel_cmd

类型 Schema

/robotic/task_status_cmd

类型 Schema

/robotic/stop_cmd

类型 Schema

/robotic/release_stop

类型 Schema

/robotic/global_vel_cmd

类型 Schema

/robotic/move_gripper_cmd

类型 Schema

/robotic/sucker_control_cmd

类型 Schema

/robotic/motor_sucker_length_angle_control_cmd

类型 Schema

/robotic/switch_mode_cmd

类型 Schema

/robotic/get_system_state_cmd

类型 Schema