高层全身协调与控制接口
约 7269 字大约 24 分钟
开发者可通过标准的ROS2话题(Topic)、服务(Service)和动作(Action)机制,便捷地获取机器人状态、发送控制指令,实现复杂任务的编程与集成。
Topic:订阅式话题,接收方订阅某个消息,发送方根据订阅列表向接收方发送消息,主要用于中高频或持续的数据交互。
Service:问答式服务,通过请求实现数据获取或操作。用于低频或功能切换时的数据交互。
Action:持续式动作,用于长时间运行的任务,支持任务执行过程中的状态反馈和取消操作,适用于复杂动作控制和任务执行。
高层全身协调与控制接口用于配置机器人运行参数(TCP坐标系/负载/速度)并执行笛卡尔空间运动(关节运动/直线运动/轨迹跟踪),调用内置运动学求解器(正/逆运动学)和切换高级模式(零力拖动/阻抗控制/遥操作)。
真机
| Service | /control/set_property |
|---|---|
| 生效版本 | ≥V0.3.0 |
| 接入方式 | Service Call
|
| 接口说明 | 动态配置机器人运行参数,支持全局速度缩放、TCP坐标系设置、错误清除、安全等级调节、开/关拖动示教模式、休眠模式切换、快速停止、运行模式切换、阻抗参数(关节刚度/阻尼、笛卡尔刚度/阻尼比)设置等功能。 |
| 接口参数 | string property_type{ //操作类型 "SpeedRatio"; //设置全局速度 "TcpPrimary"; //设置左臂TCP坐标系 "TcpSecondary"; //设置右臂TCP坐标系 "ClearError"; //清除机器人错误状态 "SafeLevel"; //设置安全等级,统一调控机器人的碰撞检测、运动限制、力控阈值等一系列安全行为,数值越大,安全限制越严格 "EnableDrag"; //开/关拖动示教模式 "EnableSleep"; //是否进入休眠(待机)状态 "QuickStop"; //快速停止 "SwitchRunMode"; //切换运行模式 "JointStiffness"; //在关节阻抗模式下设置关节刚度,数值越大,关节刚性越强。 "JointDamping"; //在关节阻抗模式下设置关节阻尼,数值越大,关节阻尼越大。 "CartStiffness"; //在笛卡尔阻抗模式下设置机器人在笛卡尔空间的刚度系数。 "CartDampingRatio"; //在笛卡尔阻抗模式下设置机器人在笛卡尔空间的阻尼比。 }; |
string value{ //value的值与 property_type 关联
| |
| uint64 request_id:返回此次指令的指令号,用于追踪指令执行状态 |
| Action | /control/move_robot |
|---|---|
| 生效版本 | ≥V0.2 |
| 接入方式 | Action Call
|
| 接口说明 | 控制机器人多模式运动,覆盖关节运动、直线运动、实时流控(关节 / 末端位姿 ),支持单臂 / 双臂 / 全身关节控制 |
| 接口参数 | string type{ //设置运动运动控制模式 "MoveJoint"; //控制机器人各关节移动到指定角度,实现关节空间运动 "MoveLine"; //控制末端执行器沿直线运动到目标位姿 "StartJointStreaming"; //持续接收关节位置指令,启动流控模式 "StartEEPoseStreaming"; //持续接收末端位姿指令,启动流控模式 "StopMove"; //停止运动,适用于紧急停止或任务中断 }; |
| string motion_group{ //指定参与运动控制的机器人部分 "Primary"; //左臂,关节数量为 7,适用于单臂独立任务 "Secondary"; //右臂,关节数量为 7,适用于单臂独立任务 "BothArms"; //双臂,关节数量为 14,适用于双臂协同任务 "Torso" ; //躯干,关节数量为3 "WholeBody"; //全身关节, 关节数量为20,适用于全身协同运动 }; | |
float32[] target{ //target 的值与 type 和 motion_group 关联
| |
| bool success:返回布尔值,"1"表示此次指令成功执行,"0"表示此次指令执行失败 | |
| uint64 request_id:返回此次指令的指令号,用于追踪指令执行过程、关联日志或状态查询 |
| Topic | /feedback/robot_server_state |
|---|---|
| 生效版本 | ≥V0.2 |
| 接入方式 | 订阅(subscribe) |
| 接口说明 | 获取机器人服务端当前状态 |
| 接口参数 | uint64 timestamp:时间戳 |
| string robot_type:机器人类型,示例:"W1Anthropomorphic",仿人形机器人 | |
| string robot_version: 机器人软件/硬件版本,示例:"V02" | |
| uint64 latest_queued_id:最新入列指令编号,示例: -1,表示无待执行指令 | |
| uint64 latest_finished_id:最新完成指令编号,示例:-1,表示无已完成指令 | |
| uint64 latest_errordrop_id:最新报错并丢弃的指令编号,示例:-1,表示无报错丢弃 | |
string status:机器人服务端当前状态
| |
string[] server_error_code: server错误码
| |
string run_mode:机器人运行模式
| |
string robot_statusword: 机器人状态字
| |
| string safe_level: 安全等级,影响部分控制参数,示例:"0.500000" | |
| string global_speed_ratio:全局速度比例,取值范围[0.01,1.0],示例: "0.500000" ,当前为50%速度运行 | |
| float64[] joint_stiffness:关节刚度系数,[100.0000, 100.0000, ...] (共20个关节) | |
| float64[] joint_damping:关节阻尼系数,[10.0000, 10.0000, ...] (共20个关节) | |
| float64[] cart_stiffness:笛卡尔空间刚度系数,[200.0000, 200.0000, ...] (共12维) | |
| float64[] cart_damping_ratio:笛卡尔空间阻尼比,[1.0000, 1.0000, ...] (共12维) | |
| float64[] cart_impedance_force:笛卡尔空间阻抗力,[0.0000, 0.0000, ...] (共12维) | |
string robot_statusword:电机层状态字
| |
string robot_controlword:电机层控制字,当前状态指示电机开关已打开且已使能
| |
| uint8[] motor_status:20 个关节电机的运行状态,0表示电机初始或未连接,1表示电机正常运行(即OP状态) | |
| uint8[] motor_error_code:电机错误码,格式为[0, 0, 0, ...] ,0 : 无错误,10 : 速度误差超出限制值,20 : 位置误差超出限制值,30 : 主站掉线 | |
| float64[] motor_temperature: 20 个关节电机的温度,格式为[33, 33, 33, ...] ,单位°C | |
| uint8[] motor_error_code:电机错误码,格式为[0, 0, 0, ...] ,0 : 无错误,10 : 速度误差超出限制值,20 : 位置误差超出限制值,30 : 主站掉线 | |
| float64[] joint_position_cmd: 机器人20个关节的关节位置指令,格式为[0.0000, 0.0000, ...] ,单位为弧度(rad) | |
| float64[] joint_position:机器人20个关节的位置,格式为[-0.0015, -0.0015, -0.0011, ...],单位为弧度(rad) | |
| float64[] joint_velocity_cmd: 机器人20个关节的关节速度指令,格式为[0.0000, 0.0000, ...] ,单位为弧度/秒 | |
| float64[] joint_velocity:机器人20个关节的关节速度,格式为[0.0000, 0.0000, 0.0000, ...],单位为弧度/秒 | |
| float64[] joint_torque_cmd: 机器人20个关节的关节力矩指令,格式为[-14.5904, -9.6454, ...] ,单位为Nm | |
| float64[] joint_torque:机器人20个关节的实际关节力矩,格式为[-2.0010, 1.3920, -2.6100, ...] ,单位为Nm | |
| float64[] force_sensor: 六维力传感器数据,格式为[0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000] ,前六位为左手, 后六位为右手 | |
| float64[] torque_limit_negative: 20个关节的负方向力矩限制,格式为[64.5904, 59.6454, ...] ,单位为Nm | |
| float64[] torque_limit_positive: 20个关节的正方向力矩限制,格式为[35.4096, 40.3546, ...],单位为Nm | |
| float64[] ee_pose:末端执行器(End-Effector)的位姿,格式为 [x, y, z, qw, qx, qy, qz, x, y, z, qw, qx, qy, qz],前7位 [x, y, z, qw, qx, qy, qz]为左臂位姿,后七位[x, y, z, qw, qx, qy, qz]为右臂位姿 ,位置的单位为米,姿态用四元数表示。 | |
| float64[] torso_pose_X_Z_RY:躯干位姿[X坐标, Z坐标, RY旋转],格式为[-0.0022, 1.1298, -0.0041] ,X/Z 坐标单位为米,RY 旋转角单位为弧度 |
| Topic | /control/streaming_command |
|---|---|
| 生效版本 | ≥V0.2 |
| 接入方式 | 发布(publish)
|
| 接口说明 | 流控模式下的数据通道。在通过 /control/move_robot Action 启动流控(StartJointStreaming 或 StartEEPoseStreaming)后,通过本话题高频发布连续的控制指令,驱动机器人关节或末端执行器运动。支持单臂(Primary/Secondary)、双臂(BothArms)和全身(WholeBody)控制。 |
| 接口参数 | uint64 request_id:与启动流控的 Action 请求绑定的唯一 ID。该 ID 由 /control/move_robot 的 Result 返回,用户通过本话题发布指令时应使用该 ID,以便服务端将流控数据与对应的流控任务关联,避免多任务指令混淆。 |
| bool streaming_finished:标记当前指令是否为流控序列的最后一帧,True 表示发送后立即终止本次流控,机器人停止接收后续指令;False 表示持续激活流控模式,机器人等待下一帧指令。 | |
float32[] position:目标数据数组,格式由启动流控时指定的 type 和 motion_group 决定。
|
仿真环境
| Service | /control/set_property_sim |
|---|---|
| 生效版本 | ≥V0.3 |
| 接入方式 | Service Call
|
| 接口说明 | 动态配置机器人运行参数,支持全局速度缩放、TCP坐标系设置、错误清除、安全等级调节、开/关拖动示教模式、休眠模式切换、快速停止、运行模式切换、阻抗参数(关节刚度/阻尼、笛卡尔刚度/阻尼比)设置等功能。 |
| 接口参数 | string property_type{ //操作类型 "SpeedRatio"; //设置全局速度 "TcpPrimary"; //设置左臂TCP坐标系 "TcpSecondary"; //设置右臂TCP坐标系 "ClearError"; //清除机器人错误状态 "SafeLevel"; //设置安全等级,统一调控机器人的碰撞检测、运动限制、力控阈值等一系列安全行为,数值越大,安全限制越严格 "EnableDrag"; //开/关拖动示教模式 "EnableSleep"; //开/关休眠(待机)模式,使机器人下使能。 "SwitchRunMode"; //切换运行模式 "JointStiffness"; //在关节阻抗模式下设置关节刚度,数值越大,关节刚性越强。 "JointDamping"; //在关节阻抗模式下设置关节阻尼,数值越大,关节阻尼越大。 "CartStiffness"; //在笛卡尔阻抗模式下设置机器人在笛卡尔空间的刚度系数。 "CartDampingRatio"; //在笛卡尔阻抗模式下设置机器人在笛卡尔空间的阻尼比。 }; |
string value{ //value的值与 property_type 关联
| |
| uint64 request_id:返回此次指令的指令号,用于追踪指令执行状态 |
| Action | /control/move_robot_sim |
|---|---|
| 生效版本 | ≥V0.2 |
| 接入方式 | Action Call
|
| 接口说明 | 控制机器人多模式运动,覆盖关节运动、直线运动、实时流控(关节 / 末端位姿 ),支持单臂 / 双臂 / 全身关节控制 |
| 接口参数 | string type{ //设置运动运动控制模式 "MoveJoint"; //控制机器人各关节移动到指定角度,实现关节空间运动 "MoveLine"; //控制末端执行器沿直线运动到目标位姿 "StartJointStreaming"; //持续接收关节位置指令,启动流控模式 "StartEEPoseStreaming"; //持续接收末端位姿指令,启动流控模式 "StopMove"; //停止运动,适用于紧急停止或任务中断 }; |
| string motion_group{ //指定参与运动控制的机器人部分 "Primary"; //左臂,关节数量为 7,适用于单臂独立任务 "Secondary"; //右臂,关节数量为 7,适用于单臂独立任务 "BothArms"; //双臂,关节数量为 14,适用于双臂协同任务 "Torso" ; //躯干,关节数量为3 "WholeBody"; //全身关节, 关节数量为20,适用于全身协同运动 }; | |
float32[] target{ //target 的值与 type 和 motion_group 关联
| |
| bool success:返回布尔值,"1"表示此次指令成功执行,"0"表示此次指令执行失败 | |
| uint64 request_id:返回此次指令的指令号,用于追踪指令执行过程、关联日志或状态查询 |
| Topic | /feedback/robot_server_state_sim |
|---|---|
| 生效版本 | ≥V0.2 |
| 接入方式 | 订阅(subscribe) |
| 接口说明 | 获取机器人服务端当前状态 |
| 接口参数 | uint64 timestamp:时间戳 |
| string robot_type:机器人类型,示例:"W1Anthropomorphic",仿人形机器人 | |
| string robot_version: 机器人软件/硬件版本,示例:"V02" | |
| uint64 latest_queued_id:最新入列指令编号,示例: -1,表示无待执行指令 | |
| uint64 latest_finished_id:最新完成指令编号,示例:-1,表示无已完成指令 | |
| uint64 latest_errordrop_id:最新报错并丢弃的指令编号,示例:-1,表示无报错丢弃 | |
string status:机器人服务端当前状态
| |
string[] server_error_code: server错误码
| |
string run_mode:机器人运行模式
| |
string robot_statusword: 机器人状态字
| |
| string safe_level: 安全等级,影响部分控制参数,示例:"0.500000" | |
| string global_speed_ratio:全局速度比例,取值范围[0.01,1.0],示例: "0.500000" ,当前为50%速度运行 | |
| float64[] joint_stiffness:关节刚度系数,[100.0000, 100.0000, ...] (共20个关节) | |
| float64[] joint_damping:关节阻尼系数,[10.0000, 10.0000, ...] (共20个关节) | |
| float64[] cart_stiffness:笛卡尔空间刚度系数,[200.0000, 200.0000, ...] (共12维) | |
| float64[] cart_damping_ratio:笛卡尔空间阻尼比,[1.0000, 1.0000, ...] (共12维) | |
| float64[] cart_impedance_force:笛卡尔空间阻抗力,[0.0000, 0.0000, ...] (共12维) | |
string robot_statusword:电机层状态字
| |
string robot_controlword:电机层控制字,当前状态指示电机开关已打开且已使能
| |
| uint8[] motor_status:20 个关节电机的运行状态,0表示电机初始或未连接,1表示电机正常运行(即OP状态) | |
| uint8[] motor_error_code:电机错误码,格式为[0, 0, 0, ...] ,0 : 无错误,10 : 速度误差超出限制值,20 : 位置误差超出限制值,30 : 主站掉线 | |
| float64[] motor_temperature: 20 个关节电机的温度,格式为[33, 33, 33, ...] ,单位°C | |
| uint8[] motor_error_code:电机错误码,格式为[0, 0, 0, ...] ,0 : 无错误,10 : 速度误差超出限制值,20 : 位置误差超出限制值,30 : 主站掉线 | |
| float64[] joint_position_cmd: 机器人20个关节的关节位置指令,格式为[0.0000, 0.0000, ...] ,单位为弧度(rad) | |
| float64[] joint_position:机器人20个关节的位置,格式为[-0.0015, -0.0015, -0.0011, ...],单位为弧度(rad) | |
| float64[] joint_velocity_cmd: 机器人20个关节的关节速度指令,格式为[0.0000, 0.0000, ...] ,单位为弧度/秒 | |
| float64[] joint_velocity:机器人20个关节的关节速度,格式为[0.0000, 0.0000, 0.0000, ...],单位为弧度/秒 | |
| float64[] joint_torque_cmd: 机器人20个关节的关节力矩指令,格式为[-14.5904, -9.6454, ...] ,单位为Nm | |
| float64[] joint_torque:机器人20个关节的实际关节力矩,格式为[-2.0010, 1.3920, -2.6100, ...] ,单位为Nm | |
| float64[] force_sensor: 六维力传感器数据,格式为[0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000,0.0000] ,前六位为左手, 后六位为右手 | |
| float64[] torque_limit_negative: 20个关节的负方向力矩限制,格式为[64.5904, 59.6454, ...] ,单位为Nm | |
| float64[] torque_limit_positive: 20个关节的正方向力矩限制,格式为[35.4096, 40.3546, ...],单位为Nm | |
| float64[] ee_pose:末端执行器(End-Effector)的位姿,格式为 [x, y, z, qw, qx, qy, qz, x, y, z, qw, qx, qy, qz],前7位 [x, y, z, qw, qx, qy, qz]为左臂位姿,后七位[x, y, z, qw, qx, qy, qz]为右臂位姿 ,位置的单位为米,姿态用四元数表示。 | |
| float64[] torso_pose_X_Z_RY:躯干位姿[X坐标, Z坐标, RY旋转],格式为[-0.0022, 1.1298, -0.0041] ,X/Z 坐标单位为米,RY 旋转角单位为弧度 |
| Topic | /control/streaming_command_sim |
|---|---|
| 生效版本 | ≥V0.2 |
| 接入方式 | 发布(publish)
|
| 接口说明 | 流控模式下的数据通道。在通过 /control/move_robot_sim Action 启动流控(StartJointStreaming 或 StartEEPoseStreaming)后,通过本话题高频发布连续的控制指令,驱动机器人关节或末端执行器运动。支持单臂(Primary/Secondary)、双臂(BothArms)和全身(WholeBody)控制。 |
| 接口参数 | uint64 request_id:与启动流控的 Action 请求绑定的唯一 ID。该 ID 由 /control/move_robot_sim 的 Result 返回,用户通过本话题发布指令时应使用该 ID,以便服务端将流控数据与对应的流控任务关联,避免多任务指令混淆。 |
| bool streaming_finished:标记当前指令是否为流控序列的最后一帧,True 表示发送后立即终止本次流控,机器人停止接收后续指令;False 表示持续激活流控模式,机器人等待下一帧指令。 | |
float32[] position:目标数据数组,格式由启动流控时指定的 type 和 motion_group 决定。
|