发布时间: 2026-07-22

CS_ROS2软件包接口手册

本文面向使用 Elite_Robots_CS_ROS2_Driver 的集成客户，说明如何通过 ROS2 控制机器人、切换控制器，以及监视机器人关节、TCP、力矩、IO、机器人模式和安全状态等数据。
驱动基于 ros2_control。其中 eli_cs_robot_driver 提供硬件接口 hardware_interface，负责与机器人通信；eli_cs_controllers 提供 Elite CS 机器人专用控制器，例如 ScaledJointTrajectoryController、GPIOController、SpeedScalingStateBroadcaster 和 FreedriveController。

1. 启动驱动

典型启动方式如下：
ros2 launch eli_cs_robot_driver elite_control.launch.py \
  cs_type:=cs66 \
  robot_ip:=192.168.1.200 \
  local_ip:=192.168.1.100
常用参数：
参数
说明
cs_type
机器人型号，例如 cs63、cs66、cs68、cs612、cs616、cs620、cs625、cs66a、cs520h、ls65 等。
robot_ip
机器人控制器 IP。
local_ip
运行 ROS2 驱动的工控机/PC IP。机器人需要能访问此地址。
headless_mode
是否无示教器任务方式下发外部控制脚本。若为 true，机器人通常需要处于远程模式。
initial_joint_controller
启动后加载的关节控制器，默认是 scaled_joint_trajectory_controller。
activate_joint_controller
是否启动时激活初始关节控制器。
tf_prefix
多机器人场景下使用的前缀。设置后 topic 名称通常不变，但关节名和硬件接口名会带此前缀。
启动后默认会加载以下控制器：
控制器
默认状态
作用
joint_state_broadcaster
active
发布 /joint_states。
io_and_status_controller
active
发布 IO、工具、机器人模式、安全模式，并提供 IO/速度/payload 等服务。
speed_scaling_state_broadcaster
active
发布机器人速度缩放比例。
force_torque_sensor_broadcaster
active
发布 TCP 力/力矩数据。
tcp_pose_broadcaster
active
发布 TCP 位姿。
scaled_joint_trajectory_controller
active，默认
推荐的轨迹控制器。
forward_position_controller
inactive
直接位置控制器。
freedrive_controller
inactive
拖动示教控制器。
查看控制器状态：
ros2 control list_controllers
查看硬件接口：
ros2 control list_hardware_interfaces

2. 机器人运动控制接口

2.1 推荐方式：ScaledJointTrajectoryController

推荐客户优先使用 scaled_joint_trajectory_controller 控制机器人轨迹。
它继承自 joint_trajectory_controller/JointTrajectoryController，对外接口与标准 FollowJointTrajectory action 基本一致，同时会读取机器人实际速度缩放接口：
speed_scaling/speed_scaling_factor
当示教器速度滑块不是 100%、机器人暂停、外部控制程序暂停或机器人侧速度受限时，普通 joint_trajectory_controller 仍会按 ROS 侧时间推进轨迹，可能导致实际路径与期望路径偏差。scaled_joint_trajectory_controller 会根据机器人报告的速度缩放同步调整轨迹进度，因此更适合真实机器人。
Action 名称：
/scaled_joint_trajectory_controller/follow_joint_trajectory
Action 类型：
control_msgs/action/FollowJointTrajectory
关节名称，六轴机型默认如下：
shoulder_pan_joint
shoulder_lift_joint
elbow_joint
wrist_1_joint
wrist_2_joint
wrist_3_joint
如果启动时设置了 tf_prefix，关节名也需要带相同前缀，例如 robot1_shoulder_pan_joint。
命令行发送一个简单关节目标示例：
ros2 action send_goal /scaled_joint_trajectory_controller/follow_joint_trajectory \
  control_msgs/action/FollowJointTrajectory \
  "{trajectory: {joint_names: [shoulder_pan_joint, shoulder_lift_joint, elbow_joint, wrist_1_joint, wrist_2_joint, wrist_3_joint], points: [{positions: [0.0, -1.57, 1.57, 0.0, 1.57, 0.0], time_from_start: {sec: 5, nanosec: 0}}]}}"
Python 程序可参考：
eli_cs_robot_driver/example/python/example_safe_joint_move.py
该示例会先读取 /joint_states，根据当前位置和最大关节速度计算轨迹时间，再向 FollowJointTrajectory action 发送目标。

2.2 标准 JointTrajectoryController

驱动也配置了标准控制器：
/joint_trajectory_controller/follow_joint_trajectory
类型同样是：
control_msgs/action/FollowJointTrajectory
该控制器适合仿真、调试或明确不需要速度缩放同步的场景。真实机器人业务中通常建议使用 scaled_joint_trajectory_controller。
默认启动时该控制器不会单独加载，若需要使用，可在启动时指定：
ros2 launch eli_cs_robot_driver elite_control.launch.py \
  cs_type:=cs66 \
  robot_ip:=192.168.1.200 \
  local_ip:=192.168.1.100 \
  initial_joint_controller:=joint_trajectory_controller

2.3 Forward Position Controller

forward_position_controller 类型为：
position_controllers/JointGroupPositionController
它通过 topic 接收一组关节位置命令，适合上层算法已经自行完成插补、限速和安全约束的场景。
使用前需要切换控制器：
ros2 control switch_controllers \
  --deactivate scaled_joint_trajectory_controller \
  --activate forward_position_controller
发送位置命令：
ros2 topic pub /forward_position_controller/commands std_msgs/msg/Float64MultiArray \
  "{data: [0.0, -1.57, 1.57, 0.0, 1.57, 0.0]}"
注意：该接口是直接位置命令，不负责生成平滑轨迹。真实机器人使用时应由上层确保命令连续、速度和加速度满足机器人限制。

2.4 Forward Velocity Controller

配置文件中提供 forward_velocity_controller：
velocity_controllers/JointGroupVelocityController
它通过 topic 接收关节速度命令，适合伺服、遥操作或自定义控制算法。
默认启动流程没有自动 spawn 该控制器。如需使用，先加载为 inactive：
ros2 control load_controller --set-state inactive forward_velocity_controller
切换控制器：
ros2 control switch_controllers \
  --deactivate scaled_joint_trajectory_controller \
  --activate forward_velocity_controller
发送速度命令：
ros2 topic pub /forward_velocity_controller/commands std_msgs/msg/Float64MultiArray \
  "{data: [0.0, 0.0, 0.1, 0.0, 0.0, 0.0]}"
停止时应及时发送全 0 速度，或切回轨迹控制器。

2.5 Freedrive 拖动示教

freedrive_controller 用于开启/关闭拖动示教模式。它与位置/速度/轨迹控制器互斥，启用前需要先停用当前关节控制器。
切换到 freedrive：
ros2 control switch_controllers \
  --deactivate scaled_joint_trajectory_controller \
  --activate freedrive_controller
持续发布 true 开启拖动：
ros2 topic pub --rate 2 /freedrive_controller/enable_freedrive std_msgs/msg/Bool "{data: true}"
发布 false 退出拖动：
ros2 topic pub --rate 2 /freedrive_controller/enable_freedrive std_msgs/msg/Bool "{data: false}"
注意：enable_freedrive 发布频率需要保持大于 1 Hz，否则控制器会因超时自动退出 freedrive。
退出后切回轨迹控制器：
ros2 control switch_controllers \
  --deactivate freedrive_controller \
  --activate scaled_joint_trajectory_controller

3. 机器人状态监视接口

3.1 关节状态

Topic：
/joint_states
类型：
sensor_msgs/msg/JointState
包含：
字段
说明
name
关节名称。
position
关节位置，单位 rad。
velocity
关节速度，单位 rad/s。
effort
关节电流/力矩相关反馈，具体含义取决于底层机器人接口。
查看命令：
ros2 topic echo /joint_states

3.2 轨迹控制器状态

Topic：
/scaled_joint_trajectory_controller/controller_state
类型通常为：
control_msgs/msg/JointTrajectoryControllerState
可用于监视期望值、实际值和误差：
ros2 topic echo /scaled_joint_trajectory_controller/controller_state

3.3 机器人速度缩放

Topic：
/speed_scaling_state_broadcaster/speed_scaling
类型：
std_msgs/msg/Float64
该值由 speed_scaling_state_broadcaster 发布，表示机器人当前速度缩放百分比，范围通常为 0.0 到 100.0。
ros2 topic echo /speed_scaling_state_broadcaster/speed_scaling

3.4 TCP 力/力矩

Topic：
/force_torque_sensor_broadcaster/ft_data
类型：
geometry_msgs/msg/WrenchStamped
坐标系默认是：
tool0
查看：
ros2 topic echo /force_torque_sensor_broadcaster/ft_data
力/力矩传感器归零：
ros2 service call /io_and_status_controller/zero_ftsensor std_srvs/srv/Trigger "{}"

3.5 TCP 位姿

Topic：
/tcp_pose_broadcaster/pose
类型通常为：
geometry_msgs/msg/PoseStamped
其配置中的 pose_name 为 tcp_pose，frame 默认基于 base，child frame 为 tool0_controller。
可先确认实际 topic：
ros2 topic list | grep tcp_pose
再查看数据：
ros2 topic echo /tcp_pose_broadcaster/pose

3.6 IO 状态

Topic：
/io_and_status_controller/io_states
类型：
eli_common_interface/msg/IOState
字段：
字段
说明
standard_out
标准数字输出状态。
standard_in
标准数字输入状态。
config_out
配置数字输出状态。
config_in
配置数字输入状态。
tool_out
工具数字输出状态。
tool_in
工具数字输入状态。
standard_analog_out
标准模拟输出，包含类型和值。
standard_analog_in
标准模拟输入，包含类型和值。
查看：
ros2 topic echo /io_and_status_controller/io_states

3.7 工具数据

Topic：
/io_and_status_controller/tool_data
类型：
eli_common_interface/msg/ToolData
包含工具模式、输出电压、输出电流、温度、工具模拟输入/输出等。
ros2 topic echo /io_and_status_controller/tool_data

3.8 机器人模式、安全模式、任务运行状态

机器人模式：
/io_and_status_controller/robot_mode
eli_common_interface/msg/RobotMode
常见值：
值
含义
3
POWER_OFF
4
POWER_ON
5
IDLE
7
RUNNING
安全模式：
/io_and_status_controller/safety_mode
eli_common_interface/msg/SafetyMode
常见值：
值
含义
1
NORMAL
2
REDUCED
3
PROTECTIVE_STOP
5
SAFEGUARD_STOP
7
ROBOT_EMERGENCY_STOP
9
FAULT
任务运行状态：
/io_and_status_controller/robot_task_running
std_msgs/msg/Bool
该值为 true 时，表示机器人任务处于运行中并且驱动与机器人保持连接。真实机器人执行 ROS 外部控制时，应确保该值为 true。

4. IO、速度、负载和脚本控制服务

以下服务由 io_and_status_controller 提供。

4.1 设置数字 IO

Service：
/io_and_status_controller/set_io
类型：
eli_common_interface/srv/SetIO
fun 可选值：
值
常量
说明
1
FUN_SET_DIGITAL_OUT
设置标准数字输出。
2
FUN_SET_CONFIGURE_OUT
设置配置数字输出。
3
FUN_SET_TOOL_DIG_OUT
设置工具数字输出。
4
FUN_SET_ANALOG_OUT
设置标准模拟输出。
5
FUN_SET_TOOL_VOLTAGE
设置工具电压。
设置标准数字输出 0 为 ON：
ros2 service call /io_and_status_controller/set_io eli_common_interface/srv/SetIO \
  "{fun: 1, pin: 0, state: 1.0, analog_type: 0}"
设置工具数字输出 0 为 OFF：
ros2 service call /io_and_status_controller/set_io eli_common_interface/srv/SetIO \
  "{fun: 3, pin: 0, state: 0.0, analog_type: 0}"
设置标准模拟输出 0 为电压模式，输出值 1.0：
ros2 service call /io_and_status_controller/set_io eli_common_interface/srv/SetIO \
  "{fun: 4, pin: 0, analog_type: 1, state: 1.0}"
设置工具电压为 24V：
ros2 service call /io_and_status_controller/set_io eli_common_interface/srv/SetIO \
  "{fun: 5, pin: 0, state: 24.0, analog_type: 0}"

4.2 设置速度滑块

Service：
/io_and_status_controller/set_speed_slider
类型：
eli_common_interface/srv/SetSpeedSliderFraction
speed_slider_fraction 范围为 (0, 1.0]，例如 0.2 表示 20%。
ros2 service call /io_and_status_controller/set_speed_slider \
  eli_common_interface/srv/SetSpeedSliderFraction \
  "{speed_slider_fraction: 0.2}"

4.3 设置负载

Service：
/io_and_status_controller/set_payload
类型：
eli_common_interface/srv/SetPayload
示例：设置负载质量 2.5 kg，质心在工具坐标下 z 方向 0.05 m。
ros2 service call /io_and_status_controller/set_payload eli_common_interface/srv/SetPayload \
  "{mass: 2.5, center_of_gravity: {x: 0.0, y: 0.0, z: 0.05}}"

4.4 重新发送外部控制脚本

Service：
/io_and_status_controller/resend_external_script
类型：
std_srvs/srv/Trigger
ros2 service call /io_and_status_controller/resend_external_script std_srvs/srv/Trigger "{}"
常用于 headless_mode 或外部控制脚本需要重新下发的场景。

4.5 交还机器人控制权

Service：
/io_and_status_controller/hand_back_control
类型：
std_srvs/srv/Trigger
ros2 service call /io_and_status_controller/hand_back_control std_srvs/srv/Trigger "{}"
调用后外部控制脚本退出，控制权交还给机器人任务。

5. Dashboard 和 Primary 服务

驱动提供 dashboard_client 和 primary_client，用于机器人上电、释放抱闸、运行/暂停/停止任务、解除保护停止等。
常用 Dashboard 服务：
Service
类型
说明
/dashboard_client/power_on
std_srvs/srv/Trigger
机器人上电。
/dashboard_client/power_off
std_srvs/srv/Trigger
机器人下电。
/dashboard_client/brake_release
std_srvs/srv/Trigger
释放抱闸。
/dashboard_client/play
std_srvs/srv/Trigger
运行当前任务。
/dashboard_client/pause
std_srvs/srv/Trigger
暂停当前任务。
/dashboard_client/stop
std_srvs/srv/Trigger
停止当前任务。
/dashboard_client/unlock_protective_stop
std_srvs/srv/Trigger
解除保护停止。
/dashboard_client/restart_safety
std_srvs/srv/Trigger
重启安全系统。
/dashboard_client/robot_mode
eli_common_interface/srv/GetRobotMode
查询机器人模式。
/dashboard_client/get_safety_mode
eli_common_interface/srv/GetSafetyMode
查询安全模式。
/dashboard_client/get_task_status
eli_common_interface/srv/GetTaskStatus
查询任务状态。
/dashboard_client/load_task
eli_dashboard_interface/srv/Load
加载任务文件。
/dashboard_client/load_configure
eli_dashboard_interface/srv/Load
加载配置文件。
/dashboard_client/custom_request
eli_dashboard_interface/srv/CustomRequest
发送自定义 Dashboard 指令。
常见上电流程：
ros2 service call /dashboard_client/power_on std_srvs/srv/Trigger "{}"
ros2 service call /dashboard_client/brake_release std_srvs/srv/Trigger "{}"
运行当前任务：
ros2 service call /dashboard_client/play std_srvs/srv/Trigger "{}"
暂停/停止：
ros2 service call /dashboard_client/pause std_srvs/srv/Trigger "{}"
ros2 service call /dashboard_client/stop std_srvs/srv/Trigger "{}"
查询机器人模式：
ros2 service call /dashboard_client/robot_mode eli_common_interface/srv/GetRobotMode "{}"
查询安全模式：
ros2 service call /dashboard_client/get_safety_mode eli_common_interface/srv/GetSafetyMode "{}"
解除保护停止：
ros2 service call /dashboard_client/unlock_protective_stop std_srvs/srv/Trigger "{}"
primary_client 也提供类似的 power_on、power_off、brake_release、pause、stop、unlock_protective_stop、restart_safety、connect 服务。若客户已经使用 Dashboard 服务，一般优先保持使用 Dashboard 服务即可。

6. 控制器切换建议

同一时间只应有一个关节运动控制器处于 active 状态。hardware_interface 会阻止互斥控制模式同时启动，例如位置控制、速度控制和 freedrive 不能同时控制机器人。
推荐组合：
场景
推荐控制器
MoveIt 或普通点到点/轨迹运动
scaled_joint_trajectory_controller
自己插补后的关节位置流
forward_position_controller
关节速度伺服/遥操作
forward_velocity_controller
人工拖动示教
freedrive_controller
切回推荐轨迹控制器：
ros2 control switch_controllers \
  --deactivate forward_position_controller \
  --deactivate forward_velocity_controller \
  --deactivate freedrive_controller \
  --activate scaled_joint_trajectory_controller
如果某个控制器未处于 active 状态，switch_controllers 可能提示该控制器不需要切换，可根据实际 ros2 control list_controllers 结果调整命令。

7. 客户常用排查命令

查看 topic：
ros2 topic list
查看 service：
ros2 service list
查看 action：
ros2 action list
确认轨迹 action 是否存在：
ros2 action info /scaled_joint_trajectory_controller/follow_joint_trajectory
确认机器人任务是否在运行：
ros2 topic echo /io_and_status_controller/robot_task_running
确认速度缩放是否为 0：
ros2 topic echo /speed_scaling_state_broadcaster/speed_scaling
如果速度缩放为 0 或任务未运行，轨迹控制器可能已经接收目标，但机器人不会实际运动。此时应检查示教器上的任务是否运行、ExternalControl 是否启动、机器人是否处于暂停/停止/保护停止状态。
查看控制器状态：
ros2 control list_controllers
查看关节反馈：
ros2 topic echo /joint_states
查看 IO：
ros2 topic echo /io_and_status_controller/io_states
查看安全模式：
ros2 topic echo /io_and_status_controller/safety_mode

8. 使用注意事项

  1. 真实机器人运动前，应确认急停、保护停止、安全门、示教器模式和周围环境安全。
  2. 推荐真实机器人轨迹运动使用 scaled_joint_trajectory_controller，避免速度滑块、暂停、外部控制程序状态导致轨迹时间与实际执行不同步。
  3. 发送轨迹时，建议包含当前位置作为第一个轨迹点，减少控制器接管瞬间的跳变风险。
  4. forward_position_controller 和 forward_velocity_controller 不负责轨迹规划和碰撞检查，上层必须自行限速、限加速度并保证命令连续。
  5. 使用 freedrive_controller 前，应停用其他关节控制器；退出 freedrive 后再切回轨迹控制器。
  6. IO、payload、速度滑块等服务通过异步硬件接口执行，返回 success: true 表示驱动确认命令成功。
  7. 多机器人或设置 tf_prefix 时，关节名、硬件接口名和部分 frame 名会带前缀，客户程序应使用实际 /joint_states 中的关节名。
提交反馈
上一页
CS_ROS2软件包快速使用指南
下一页
CS_ROS2软件包使用案例及说明