# ros-controls/ros2_controllers architecture

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

- Interactive diagram: https://gitdiagram.com/ros-controls/ros2_controllers
- Repository: https://github.com/ros-controls/ros2_controllers

## Overview

ros2_controllers is a ROS 2 package collection of reusable ros2_control controllers and state broadcasters. A typical workflow accepts a ROS command or action, computes joint-level commands, and writes them through ros2_control interfaces to robot hardware; broadcasters expose hardware state back to ROS. The graph preserves major mobile-base, joint-motion, auxiliary-control, sensing, and operator-UI capabilities. Source excerpts are partial, so links between unsampled components are omitted where their runtime wiring cannot be verified.

Main entry points: [`joint_trajectory_controller/src/joint_trajectory_controller.cpp`](https://github.com/ros-controls/ros2_controllers/blob/master/joint_trajectory_controller/src/joint_trajectory_controller.cpp) (Joint trajectories), [`diff_drive_controller/src/diff_drive_controller.cpp`](https://github.com/ros-controls/ros2_controllers/blob/master/diff_drive_controller/src/diff_drive_controller.cpp) (Diff drive), [`mecanum_drive_controller/src/mecanum_drive_controller.cpp`](https://github.com/ros-controls/ros2_controllers/blob/master/mecanum_drive_controller/src/mecanum_drive_controller.cpp) (Mecanum drive), [`omni_wheel_drive_controller/src/omni_wheel_drive_controller.cpp`](https://github.com/ros-controls/ros2_controllers/blob/master/omni_wheel_drive_controller/src/omni_wheel_drive_controller.cpp) (Omni wheel drive)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile bases"]
  node_diff_drive["Diff drive"]
  node_mecanum["Mecanum drive"]
  node_omni["Omni wheel drive"]
  node_tricycle["Tricycle drive"]
  node_steering["Steering controllers"]
end

subgraph group_motion["Joint motion"]
  node_trajectory["Joint trajectories"]
  node_gripper["Gripper actions"]
  node_pid["PID control<br/>[pid_controller.cpp]"]
  node_admittance["Admittance control"]
  node_motion_primitives["Motion primitives"]
end

subgraph group_sensing["State and sensing"]
  node_joint_states["Joint states"]
  node_sensor_broadcasters["Sensor broadcasters"]
  node_force_torque["Force torque"]
  node_other_broadcasters["Other state broadcasters"]
end

subgraph group_auxiliary["Auxiliary control"]
  node_forward["Forward commands"]
  node_gpio["GPIO commands"]
end

subgraph group_operator["Operator tools"]
  node_trajectory_ui["Trajectory UI"]
end

node_ros_user(("ROS clients"))
node_hardware["Robot hardware"]
node_base_command["Base velocity command"]
node_ros_outputs["ROS state topics"]

node_ros_user -->|"sends commands"| node_base_command
node_base_command -->|"subscribes"| node_diff_drive
node_base_command -->|"subscribes"| node_mecanum
node_base_command -->|"subscribes"| node_omni
node_base_command -->|"subscribes"| node_tricycle
node_diff_drive -->|"writes wheel commands"| node_hardware
node_mecanum -->|"writes wheel commands"| node_hardware
node_omni -->|"writes wheel commands"| node_hardware
node_tricycle -->|"writes joint commands"| node_hardware
node_ros_user -->|"sends trajectories"| node_trajectory
node_trajectory_ui -->|"publishes trajectories"| node_trajectory
node_trajectory -->|"writes joint commands"| node_hardware
node_ros_user -->|"sends action goals"| node_gripper
node_gripper -->|"writes gripper commands"| node_hardware
node_ros_user -->|"sends references"| node_pid
node_pid -->|"writes commands"| node_hardware
node_ros_user -->|"sends references"| node_admittance
node_admittance -->|"writes commands"| node_hardware
node_ros_user -->|"sends action goals"| node_motion_primitives
node_motion_primitives -->|"writes motion commands"| node_hardware
node_ros_user -->|"sends commands"| node_forward
node_forward -->|"writes interfaces"| node_hardware
node_ros_user -->|"sends commands"| node_gpio
node_gpio -->|"writes GPIO interfaces"| node_hardware
node_hardware -->|"provides joint state"| node_joint_states
node_hardware -->|"provides sensor state"| node_sensor_broadcasters
node_hardware -->|"provides wrench state"| node_force_torque
node_hardware -->|"provides interface state"| node_other_broadcasters
node_joint_states -->|"publishes"| node_ros_outputs
node_sensor_broadcasters -->|"publishes"| node_ros_outputs
node_force_torque -->|"publishes"| node_ros_outputs
node_other_broadcasters -->|"publishes"| node_ros_outputs
node_hardware -->|"supplies wheel feedback"| node_diff_drive
node_hardware -->|"supplies wheel feedback"| node_mecanum
node_hardware -->|"supplies wheel feedback"| node_omni
node_hardware -->|"supplies joint feedback"| node_tricycle
node_hardware -->|"supplies joint state"| node_trajectory
node_hardware -->|"supplies joint state"| node_gripper

click node_diff_drive "https://github.com/ros-controls/ros2_controllers/blob/master/diff_drive_controller/src/diff_drive_controller.cpp"
click node_mecanum "https://github.com/ros-controls/ros2_controllers/blob/master/mecanum_drive_controller/src/mecanum_drive_controller.cpp"
click node_omni "https://github.com/ros-controls/ros2_controllers/blob/master/omni_wheel_drive_controller/src/omni_wheel_drive_controller.cpp"
click node_tricycle "https://github.com/ros-controls/ros2_controllers/blob/master/tricycle_controller/src/tricycle_controller.cpp"
click node_steering "https://github.com/ros-controls/ros2_controllers/blob/master/steering_controllers_library/src/steering_controllers_library.cpp"
click node_trajectory "https://github.com/ros-controls/ros2_controllers/blob/master/joint_trajectory_controller/src/joint_trajectory_controller.cpp"
click node_trajectory_ui "https://github.com/ros-controls/ros2_controllers/blob/master/rqt_joint_trajectory_controller/rqt_joint_trajectory_controller/joint_trajectory_controller.py"
click node_gripper "https://github.com/ros-controls/ros2_controllers/blob/master/parallel_gripper_controller/include/parallel_gripper_controller/parallel_gripper_action_controller_impl.hpp"
click node_pid "https://github.com/ros-controls/ros2_controllers/blob/master/pid_controller/src/pid_controller.cpp"
click node_admittance "https://github.com/ros-controls/ros2_controllers/blob/master/admittance_controller/src/admittance_controller.cpp"
click node_motion_primitives "https://github.com/ros-controls/ros2_controllers/blob/master/motion_primitives_controllers/src/motion_primitives_forward_controller.cpp"
click node_forward "https://github.com/ros-controls/ros2_controllers/blob/master/forward_command_controller/src/forward_command_controller.cpp"
click node_gpio "https://github.com/ros-controls/ros2_controllers/blob/master/gpio_controllers/src/gpio_command_controller.cpp"
click node_joint_states "https://github.com/ros-controls/ros2_controllers/blob/master/joint_state_broadcaster/src/joint_state_broadcaster.cpp"
click node_sensor_broadcasters "https://github.com/ros-controls/ros2_controllers/blob/master/imu_sensor_broadcaster/src/imu_sensor_broadcaster.cpp"
click node_force_torque "https://github.com/ros-controls/ros2_controllers/blob/master/force_torque_sensor_broadcaster/src/force_torque_sensor_broadcaster.cpp"
click node_other_broadcasters "https://github.com/ros-controls/ros2_controllers/blob/master/state_interfaces_broadcaster/src/state_interfaces_broadcaster.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_diff_drive,node_mecanum,node_omni,node_tricycle,node_steering,node_ros_user toneBlue
class node_trajectory,node_gripper,node_pid,node_admittance,node_motion_primitives toneAmber
class node_joint_states,node_sensor_broadcasters,node_force_torque,node_other_broadcasters toneMint
class node_forward,node_gpio toneRose
class node_trajectory_ui,node_hardware,node_base_command,node_ros_outputs toneIndigo
```

## Components

### Mobile bases

- [Diff drive](https://github.com/ros-controls/ros2_controllers/blob/master/diff_drive_controller/src/diff_drive_controller.cpp): `diff_drive_controller/src/diff_drive_controller.cpp`
- [Mecanum drive](https://github.com/ros-controls/ros2_controllers/blob/master/mecanum_drive_controller/src/mecanum_drive_controller.cpp): `mecanum_drive_controller/src/mecanum_drive_controller.cpp`
- [Omni wheel drive](https://github.com/ros-controls/ros2_controllers/blob/master/omni_wheel_drive_controller/src/omni_wheel_drive_controller.cpp): `omni_wheel_drive_controller/src/omni_wheel_drive_controller.cpp`
- [Tricycle drive](https://github.com/ros-controls/ros2_controllers/blob/master/tricycle_controller/src/tricycle_controller.cpp): `tricycle_controller/src/tricycle_controller.cpp`
- [Steering controllers](https://github.com/ros-controls/ros2_controllers/blob/master/steering_controllers_library/src/steering_controllers_library.cpp): `steering_controllers_library/src/steering_controllers_library.cpp`

### Joint motion

- [Joint trajectories](https://github.com/ros-controls/ros2_controllers/blob/master/joint_trajectory_controller/src/joint_trajectory_controller.cpp): `joint_trajectory_controller/src/joint_trajectory_controller.cpp`
- [Gripper actions](https://github.com/ros-controls/ros2_controllers/blob/master/parallel_gripper_controller/include/parallel_gripper_controller/parallel_gripper_action_controller_impl.hpp): `parallel_gripper_controller/include/parallel_gripper_controller/parallel_gripper_action_controller_impl.hpp`
- [PID control](https://github.com/ros-controls/ros2_controllers/blob/master/pid_controller/src/pid_controller.cpp): `pid_controller/src/pid_controller.cpp`
- [Admittance control](https://github.com/ros-controls/ros2_controllers/blob/master/admittance_controller/src/admittance_controller.cpp): `admittance_controller/src/admittance_controller.cpp`
- [Motion primitives](https://github.com/ros-controls/ros2_controllers/blob/master/motion_primitives_controllers/src/motion_primitives_forward_controller.cpp): `motion_primitives_controllers/src/motion_primitives_forward_controller.cpp`

### State and sensing

- [Joint states](https://github.com/ros-controls/ros2_controllers/blob/master/joint_state_broadcaster/src/joint_state_broadcaster.cpp): `joint_state_broadcaster/src/joint_state_broadcaster.cpp`
- [Sensor broadcasters](https://github.com/ros-controls/ros2_controllers/blob/master/imu_sensor_broadcaster/src/imu_sensor_broadcaster.cpp): `imu_sensor_broadcaster/src/imu_sensor_broadcaster.cpp`
- [Force torque](https://github.com/ros-controls/ros2_controllers/blob/master/force_torque_sensor_broadcaster/src/force_torque_sensor_broadcaster.cpp): `force_torque_sensor_broadcaster/src/force_torque_sensor_broadcaster.cpp`
- [Other state broadcasters](https://github.com/ros-controls/ros2_controllers/blob/master/state_interfaces_broadcaster/src/state_interfaces_broadcaster.cpp): `state_interfaces_broadcaster/src/state_interfaces_broadcaster.cpp`

### Auxiliary control

- [Forward commands](https://github.com/ros-controls/ros2_controllers/blob/master/forward_command_controller/src/forward_command_controller.cpp): `forward_command_controller/src/forward_command_controller.cpp`
- [GPIO commands](https://github.com/ros-controls/ros2_controllers/blob/master/gpio_controllers/src/gpio_command_controller.cpp): `gpio_controllers/src/gpio_command_controller.cpp`

### Operator tools

- [Trajectory UI](https://github.com/ros-controls/ros2_controllers/blob/master/rqt_joint_trajectory_controller/rqt_joint_trajectory_controller/joint_trajectory_controller.py): `rqt_joint_trajectory_controller/rqt_joint_trajectory_controller/joint_trajectory_controller.py`

### Other components

- **ROS clients**
- **Robot hardware**
- **Base velocity command**
- **ROS state topics**

## Connections

- ROS clients → Base velocity command: sends commands
- Base velocity command → Diff drive: subscribes
- Base velocity command → Mecanum drive: subscribes
- Base velocity command → Omni wheel drive: subscribes
- Base velocity command → Tricycle drive: subscribes
- Diff drive → Robot hardware: writes wheel commands
- Mecanum drive → Robot hardware: writes wheel commands
- Omni wheel drive → Robot hardware: writes wheel commands
- Tricycle drive → Robot hardware: writes joint commands
- ROS clients → Joint trajectories: sends trajectories
- Trajectory UI → Joint trajectories: publishes trajectories
- Joint trajectories → Robot hardware: writes joint commands
- ROS clients → Gripper actions: sends action goals
- Gripper actions → Robot hardware: writes gripper commands
- ROS clients → PID control: sends references
- PID control → Robot hardware: writes commands
- ROS clients → Admittance control: sends references
- Admittance control → Robot hardware: writes commands
- ROS clients → Motion primitives: sends action goals
- Motion primitives → Robot hardware: writes motion commands
- ROS clients → Forward commands: sends commands
- Forward commands → Robot hardware: writes interfaces
- ROS clients → GPIO commands: sends commands
- GPIO commands → Robot hardware: writes GPIO interfaces
- Robot hardware → Joint states: provides joint state
- Robot hardware → Sensor broadcasters: provides sensor state
- Robot hardware → Force torque: provides wrench state
- Robot hardware → Other state broadcasters: provides interface state
- Joint states → ROS state topics: publishes
- Sensor broadcasters → ROS state topics: publishes
- Force torque → ROS state topics: publishes
- Other state broadcasters → ROS state topics: publishes
- Robot hardware → Diff drive: supplies wheel feedback
- Robot hardware → Mecanum drive: supplies wheel feedback
- Robot hardware → Omni wheel drive: supplies wheel feedback
- Robot hardware → Tricycle drive: supplies joint feedback
- Robot hardware → Joint trajectories: supplies joint state
- Robot hardware → Gripper actions: supplies joint state