How universalrobots/universal_robots_ros2_driver works
Project Type and Purpose
• This repository is a modular ROS 2 manipulator driver for Universal Robots, composed of several ROS 2 packages:
• ur_robot_driver (hardware interface & communication nodes)
• ur_controllers (ROS 2 Control controllers)
• ur_calibration (calibration tool)
• ur_dashboard_msgs (dashboard message definitions)
• ur_moveit_config (MoveIt 2 integration)
• ur (meta-package)
• Its goal is to enable low-latency communication, robot state monitoring, trajectory control, dashboard interactions, and MoveIt 2 planning for any UR cobot model.
File Structure Analysis
• Top-level: CI/workflows, meta-package (ur), and six subfolders (ur_calibration, ur_controllers, ur_dashboard_msgs, ur_moveit_config, ur_robot_driver).
• Each subfolder follows a ROS 2 package layout (CMakeLists.txt, package.xml, src/, include/, launch/, config/, test/).
• ur_robot_driver provides ROS 2 nodes for hardware interface, dashboard client, controller stopper, trajectory node, plus examples, scripts, URDF, and resources.
• ur_controllers contains multiple controller plugins (force mode, freedrive, passthrough trajectory, scaled joint trajectory, speed scaling, tool contact, UR configuration), plus parameter YAMLs and test harnesses.
• Configuration files (in ur_robot_driver/config and ur_moveit_config/config) and launch scripts coordinate nodes and controllers.
• A mode_compatibility_matrix (in controller_plugins.xml) defines which controllers can run simultaneously.
README Insights
• The README describes driver features (safeguard stop, speed scaling, externalControl URCap) and integration with MoveIt 2.
• It lists the six packages and emphasizes Linux/ROS 2 requirements.
Main Components
a. Physical & Simulated Robot
• Real UR robot (PolyScope controller) or URSim simulator
• Communicates over TCP/IP
b. Universal_Robots_Client_Library (URCL)
• Underlying C++ library for protocol-level messaging
c. ur_robot_driver Nodes
• hardware_interface node (ROS 2 Control plugin)
• dashboard_client_node (ROS 2 node using ur_dashboard_msgs)
• controller_stopper_node, trajectory_until_node, robot_state_helper_node
d. controller_manager (ROS 2 Control)
• Loads hardware_interface plugin
• Manages controller lifecycle
e. Controllers (loaded into controller_manager)
• joint_state_broadcaster (publishes joint states)
• scaled_joint_trajectory_controller
• tool_contact_controller
• freedrive_mode_controller, force_mode_controller, passthrough_trajectory_controller, speed_scaling_state_broadcaster, ur_configuration_controller
• mode_compatibility_matrix (controller_plugins.xml) for allowable concurrency
f. ur_calibration Tool
• Separate ROS 2 node for calibration extraction/consumption
g. ur_moveit_config / MoveIt 2
• MoveIt 2 planning pipeline and RViz interface
• Subscribes to joint_states & publishes trajectory commands
h. External Clients
• User scripts / examples (force_mode.py, example_move.py)
• ROS 2 action/service clients
Relationships & Data Flows
• Robot/URSim ↔ URCL ↔ hardware_interface node
• hardware_interface ↔ controller_manager via ros2_control plugin interface
• controller_manager → joint_state_broadcaster → /joint_states topic
• controller_manager ← scaled_joint_trajectory_controller ← /joint_trajectory commands
• controller_manager ← tool_contact_controller ← /tool_contact commands
• dashboard_client_node ↔ UR robot (dashboard services via TCP)
• calibration node ↔ UR robot (data extraction) → publishes calibration info
• MoveIt 2 planning node ↔ /joint_states & → /joint_trajectory (goes into controller_manager)
• External scripts ↔ topics/services exposed by ur_robot_driver
Architectural Patterns & Principles
• Modular, package-based ROS 2 nodes
• Separation of concerns: hardware interface vs. controllers vs. calibration vs. planning
• Plugin architecture: hardware_interface and controllers as loadable plugins
• Configuration-driven: controller plugins & mode_compatibility_matrix define run-time behavior
• Standard ROS 2 Control pattern with controller_manager
Elements
• Controller_manager node & plugin interface
• joint_state_broadcaster
• scaled_joint_trajectory_controller
• tool_contact_controller
• mode_compatibility_matrix (as config)
• All other controllers from ur_controllers
• hardware_interface node (ur_robot_driver)
• URCL library
• Physical robot / URSim
• Dashboard client node
• Calibration node
• MoveIt 2 planning node
• External clients / scripts