# universalrobots/universal_robots_ros2_driver architecture

> Architecture diagram of the GitHub repository universalrobots/universal_robots_ros2_driver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/universalrobots/universal_robots_ros2_driver
- Repository: https://github.com/universalrobots/universal_robots_ros2_driver

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Physical & Simulated Robot
    RobotSim[/"Physical UR Robot \/ URSim"/]:::hardware
    click RobotSim "https://github.com/universalrobots/universal_robots_ros2_driver/tree/main/.github/dockerursim/"

    %% URCL Library
    URCL["Universal_Robots_Client_Library (URCL)"]:::urcl
    click URCL "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/src/urscript_interface.cpp"

    URCL -->|TCP/IP| RobotSim

    %% ur_robot_driver Package
    subgraph "ur_robot_driver"
        subgraph "Nodes"
            HWInterface["hardware_interface node"]:::nodes
            DashboardClient["dashboard_client_node"]:::nodes
            ControllerStopper["controller_stopper_node"]:::nodes
            TrajUntil["trajectory_until_node"]:::nodes
            RobotStateHelper["robot_state_helper_node"]:::nodes
        end
    end

    click HWInterface "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/src/hardware_interface.cpp"
    click HWInterface "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/include/ur_robot_driver/hardware_interface.hpp"
    click HWInterface "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/hardware_interface_plugin.xml"
    click DashboardClient "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/src/dashboard_client_node.cpp"
    click DashboardClient "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/include/ur_robot_driver/dashboard_client_ros.hpp"
    click ControllerStopper "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/src/controller_stopper_node.cpp"
    click ControllerStopper "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/include/ur_robot_driver/controller_stopper.hpp"
    click TrajUntil "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/src/trajectory_until_node.cpp"
    click TrajUntil "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/include/ur_robot_driver/trajectory_until_node.hpp"
    click RobotStateHelper "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/src/robot_state_helper_node.cpp"
    click RobotStateHelper "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/include/ur_robot_driver/robot_state_helper.hpp"

    URCL -->|protocol| HWInterface
    DashboardClient -->|TCP/IP| RobotSim
    ControllerStopper -->|ros2_control| ControllerManager
    TrajUntil -->|ros2_control| ControllerManager
    RobotStateHelper -->|ros2_control| ControllerManager

    %% ROS2 Control manager
    subgraph "ROS2 Control"
        ControllerManager["controller_manager"]:::controller
    end
    click ControllerManager "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/hardware_interface_plugin.xml"

    ControllerManager --> JointBroadcaster
    ControllerManager --> ScaledTraj
    ControllerManager --> ToolContact
    ControllerManager --> ForceMode
    ControllerManager --> Freedrive
    ControllerManager --> Passthrough
    ControllerManager --> SpeedScaling
    ControllerManager --> URConfig

    %% ur_controllers Package
    subgraph "ur_controllers"
        JointBroadcaster["joint_state_broadcaster"]:::controllers
        ScaledTraj["scaled_joint_trajectory_controller"]:::controllers
        ToolContact["tool_contact_controller"]:::controllers
        ForceMode["force_mode_controller"]:::controllers
        Freedrive["freedrive_mode_controller"]:::controllers
        Passthrough["passthrough_trajectory_controller"]:::controllers
        SpeedScaling["speed_scaling_state_broadcaster"]:::controllers
        URConfig["ur_configuration_controller"]:::controllers
        ModeMatrix["mode_compatibility_matrix"]:::config
    end

    click ModeMatrix "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_controllers/controller_plugins.xml"
    click ForceMode "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_controllers/src/force_mode_controller.cpp"
    click Freedrive "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_controllers/src/freedrive_mode_controller.cpp"
    click Passthrough "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_controllers/src/passthrough_trajectory_controller.cpp"
    click ScaledTraj "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_controllers/src/scaled_joint_trajectory_controller.cpp"
    click SpeedScaling "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_controllers/src/speed_scaling_state_broadcaster.cpp"
    click ToolContact "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_controllers/src/tool_contact_controller.cpp"
    click URConfig "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_controllers/src/ur_configuration_controller.cpp"

    %% Calibration Tool
    subgraph "ur_calibration"
        Calibration["calibration node"]:::tools
    end
    click Calibration "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_calibration/src/calibration.cpp"
    Calibration -->|data extraction| RobotSim

    %% MoveIt2 Integration
    subgraph "ur_moveit_config"
        MoveIt["MoveIt2 Planning & RViz"]:::tools
    end
    click MoveIt "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_moveit_config/launch/ur_moveit.launch.py"
    MoveIt -->|subscribes /joint_states| JointBroadcaster
    MoveIt -->|publishes /joint_trajectory| ScaledTraj

    %% External Clients
    subgraph "External Clients"
        Scripts["example scripts (force_mode.py, move_until)"]:::external
    end
    click Scripts "https://github.com/universalrobots/universal_robots_ros2_driver/blob/main/ur_robot_driver/examples/force_mode.py"
    Scripts -->|topics/services| HWInterface
    Scripts -->|actions/services| ControllerManager

    %% Styles
    classDef hardware fill:#cccccc,stroke:#333,stroke-width:1px
    classDef urcl fill:#80bfff,stroke:#333,stroke-width:1px
    classDef nodes fill:#b3ffb3,stroke:#333,stroke-width:1px
    classDef controller fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef controllers fill:#ffff99,stroke:#333,stroke-width:1px
    classDef config fill:#ffebcc,stroke:#333,stroke-width:1px
    classDef tools fill:#d9b3ff,stroke:#333,stroke-width:1px
    classDef external fill:#b3e6ff,stroke:#333,stroke-width:1px
```
