# openai/robot_controllers architecture

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

- Interactive diagram: https://gitdiagram.com/openai/robot_controllers
- Repository: https://github.com/openai/robot_controllers

## Overview

1. **Repository purpose**
   - This is a ROS-based robot control framework, split into three packages: a controller implementation package, a controller interface/manager package, and a small messages package.
   - The design is aimed at robot-agnostic higher-level control, with the actual real-time joint loop expected to live in hardware or lower-level firmware.

2. **Top-level architecture**
   - The repository is organized around a clear boundary between:
     - **controller implementations** (`robot_controllers`)
     - **controller lifecycle and abstraction layer** (`robot_controllers_interface`)
     - **ROS message/action types for controller state** (`robot_controllers_msgs`)
   - This separation lets controllers be loaded and managed without tightly coupling them to the transport or to specific hardware types.

3. **Controller implementation package: `robot_controllers`**
   - This package contains the concrete control behaviors: cartesian pose, cartesian twist, cartesian wrench, differential drive, follow joint trajectory, gravity compensation, parallel gripper, point head, scaled mimic, and PID support.
   - It also includes trajectory utilities such as spline sampling, suggesting trajectory execution is a core shared concern across controllers.
   - The package exposes C++ headers in `include/` and implementations in `src/`, with a small Python binding/module stub present under `src/robot_controllers`.

4. **What the controllers do**
   - The controller classes appear to represent high-level commands over different robot subsystems:
     - arm motion in Cartesian space
     - joint trajectory following
     - mobile base differential drive
     - gripper and head control
     - compensation and scaling behaviors
   - These are not just algorithmic utilities; they are the executable control behaviors that act on robot state and output commands.

5. **Trajectory and limiting logic**
   - The presence of `trajectory.h`, `trajectory_spline_sampler.h`, and `follow_joint_trajectory.cpp` indicates that trajectory generation/execution is handled inside the controller layer.
   - `diff_drive_limiter` and its message type suggest command limiting and parameterization are first-class parts of the motion stack, likely used to bound velocity/acceleration for the base.

6. **Controller interface package: `robot_controllers_interface`**
   - This package defines the abstractions used to talk to controllers: `Controller`, `Handle`, `JointHandle`, and higher-level management via `ControllerLoader` and `ControllerManager`.
   - It is the architectural glue that likely supports “stacking” controllers and switching between them.
   - The `scripts/` directory provides command-line entry points to start, stop, and query controller state, indicating runtime management is exposed as ROS tooling.

7. **Lifecycle and runtime management**
   - The interface package is the main control-plane boundary: it handles controller loading, state inspection, and activation/deactivation.
   - That implies a split between:
     - **control plane**: loader/manager/scripts
     - **data plane**: the controller classes themselves, which compute commands
   - This is important for architecture diagrams because controller execution is not directly embedded in a monolithic node; it is managed through a dedicated interface layer.

8. **Messages package: `robot_controllers_msgs`**
   - This package contains the ROS API for controller management and configuration.
   - `ControllerState.msg` and `QueryControllerStates.action` define the external state/query contract.
   - `DiffDriveLimiterParams.msg` is a parameter transport type, showing that at least some controller behavior is configurable through ROS messages rather than compile-time settings.

9. **Language and build model**
   - The codebase is primarily **C++ ROS/catkin**:
     - headers in `include/`
     - source in `src/`
     - package manifests and `CMakeLists.txt` in each package
   - There is also a small Python layer for ROS scripts and module initialization, but the architectural center is C++.

10. **Testing**
    - Tests are focused on controller logic and trajectory behavior, with explicit unit tests for `diff_drive_limiter` and `trajectory` components.
    - That suggests the most important correctness boundary is in motion generation and limiting, not in UI or web-facing logic.

11. **External/system assumptions**
    - The README explicitly notes that this framework is **not designed for real-time constraints** and assumes low-level joint control is handled in hardware, as on Fetch/Freight.
    - So the repo sits above the hard real-time layer, coordinating high-level motion while leaving servo-level control elsewhere.

12. **How to diagram the system**
    - A good architecture diagram should show:
      - ROS clients/operators invoking controller-management scripts or actions
      - `robot_controllers_interface` as the manager/loader layer
      - `robot_controllers` as the library of concrete controller implementations
      - `robot_controllers_msgs` as the shared ROS contract
      - robot hardware/firmware below, providing the real-time actuation and joint feedback expected by the controllers

Main entry points: [`robot_controllers_interface/include/robot_controllers_interface/controller.h`](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_interface/include/robot_controllers_interface/controller.h) (Controller API), [`robot_controllers/include/robot_controllers/diff_drive_base.h`](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/diff_drive_base.h) (Diff drive), [`robot_controllers/include/robot_controllers/follow_joint_trajectory.h`](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/follow_joint_trajectory.h) (Joint trajectory), [`robot_controllers_interface/include/robot_controllers_interface/controller_manager.h`](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_interface/include/robot_controllers_interface/controller_manager.h) (Controller manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_msgs["ROS contracts"]
  node_node_msgs_state["Controller state<br/>ROS msg"]
  node_node_msgs_query["State query<br/>ROS action"]
  node_node_msgs_limit["Limiter params<br/>ROS msg"]
end

subgraph group_grp_iface["Controller interface"]
  node_node_scripts["CLI tools<br/>ros scripts"]
  node_node_manager["Controller manager<br/>lifecycle manager"]
  node_node_loader["Controller loader<br/>plugin loader"]
  node_node_controller_api["Controller API<br/>base interfaces<br/>[controller.h]"]
  node_node_handles["Handles<br/>[handle.h]"]
end

subgraph group_grp_ctrl["Controller implementations"]
  node_node_pose["Cartesian pose<br/>arm controller<br/>[cartesian_pose.h]"]
  node_node_twist["Cartesian twist<br/>arm controller<br/>[cartesian_twist.h]"]
  node_node_wrench["Cartesian wrench<br/>arm controller<br/>[cartesian_wrench.h]"]
  node_node_diffdrive["Diff drive<br/>base controller<br/>[diff_drive_base.h]"]
  node_node_traj_follow["Joint trajectory<br/>trajectory controller"]
  node_node_gravity["Gravity comp<br/>compensation controller"]
  node_node_gripper["Parallel gripper<br/>end-effector controller<br/>[parallel_gripper.h]"]
  node_node_head["Point head<br/>head controller<br/>[point_head.h]"]
  node_node_mimic["Scaled mimic<br/>coordination controller<br/>[scaled_mimic.h]"]
  node_node_pid["PID support<br/>control primitive<br/>[pid.h]"]
  node_node_trajectory["Trajectory utils<br/>trajectory core<br/>[trajectory.h]"]
  node_node_sampler["Spline sampler<br/>trajectory utility"]
end

subgraph group_grp_ext["External runtime"]
  node_node_operator(("ROS clients<br/>operator/tooling"))
  node_node_hardware[("Joint hardware<br/>real-time layer")]
end

node_node_operator -->|"invoke"| node_node_scripts
node_node_scripts -->|"manage"| node_node_manager
node_node_manager -->|"load"| node_node_loader
node_node_loader -->|"bind"| node_node_controller_api
node_node_manager -->|"publish"| node_node_msgs_state
node_node_scripts -->|"query"| node_node_msgs_query
node_node_manager -->|"serve"| node_node_msgs_query
node_node_diffdrive -->|"configure"| node_node_msgs_limit
node_node_diffdrive -->|"uses"| node_node_pid
node_node_traj_follow -->|"executes"| node_node_trajectory
node_node_traj_follow -->|"samples"| node_node_sampler
node_node_pose -->|"implements"| node_node_controller_api
node_node_twist -->|"implements"| node_node_controller_api
node_node_wrench -->|"implements"| node_node_controller_api
node_node_diffdrive -->|"implements"| node_node_controller_api
node_node_traj_follow -->|"implements"| node_node_controller_api
node_node_gravity -->|"implements"| node_node_controller_api
node_node_gripper -->|"implements"| node_node_controller_api
node_node_head -->|"implements"| node_node_controller_api
node_node_mimic -->|"implements"| node_node_controller_api
node_node_pose -->|"command"| node_node_hardware
node_node_twist -->|"command"| node_node_hardware
node_node_wrench -->|"command"| node_node_hardware
node_node_diffdrive -->|"command"| node_node_hardware
node_node_traj_follow -->|"command"| node_node_hardware
node_node_gripper -->|"command"| node_node_hardware
node_node_head -->|"command"| node_node_hardware
node_node_gravity -->|"compensate"| node_node_hardware

click node_node_scripts "https://github.com/openai/robot_controllers/tree/indigo-devel/robot_controllers_interface/scripts"
click node_node_manager "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_interface/include/robot_controllers_interface/controller_manager.h"
click node_node_loader "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_interface/include/robot_controllers_interface/controller_loader.h"
click node_node_controller_api "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_interface/include/robot_controllers_interface/controller.h"
click node_node_handles "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_interface/include/robot_controllers_interface/handle.h"
click node_node_msgs_state "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_msgs/msg/ControllerState.msg"
click node_node_msgs_query "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_msgs/action/QueryControllerStates.action"
click node_node_msgs_limit "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_msgs/msg/DiffDriveLimiterParams.msg"
click node_node_pose "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/cartesian_pose.h"
click node_node_twist "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/cartesian_twist.h"
click node_node_wrench "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/cartesian_wrench.h"
click node_node_diffdrive "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/diff_drive_base.h"
click node_node_traj_follow "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/follow_joint_trajectory.h"
click node_node_gravity "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/gravity_compensation.h"
click node_node_gripper "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/parallel_gripper.h"
click node_node_head "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/point_head.h"
click node_node_mimic "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/scaled_mimic.h"
click node_node_pid "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/pid.h"
click node_node_trajectory "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/trajectory.h"
click node_node_sampler "https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/trajectory_spline_sampler.h"

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_node_msgs_state,node_node_msgs_query,node_node_msgs_limit toneBlue
class node_node_scripts,node_node_manager,node_node_loader,node_node_controller_api,node_node_handles toneAmber
class node_node_pose,node_node_twist,node_node_wrench,node_node_diffdrive,node_node_traj_follow,node_node_gravity,node_node_gripper,node_node_head,node_node_mimic,node_node_pid,node_node_trajectory,node_node_sampler toneMint
class node_node_operator,node_node_hardware toneRose
```

## Components

### ROS contracts

Shared message and action types for controller state and parameters.

- [Controller state](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_msgs/msg/ControllerState.msg): ROS msg · Published controller status and query results. · `robot_controllers_msgs/msg/ControllerState.msg`
- [State query](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_msgs/action/QueryControllerStates.action): ROS action · Action interface for requesting controller state information. · `robot_controllers_msgs/action/QueryControllerStates.action`
- [Limiter params](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_msgs/msg/DiffDriveLimiterParams.msg): ROS msg · Parameter transport for diff-drive limiting behavior. · `robot_controllers_msgs/msg/DiffDriveLimiterParams.msg`

### Controller interface

Lifecycle, loading, and runtime management of controllers.

- [CLI tools](https://github.com/openai/robot_controllers/tree/indigo-devel/robot_controllers_interface/scripts): ros scripts · Start, stop, and inspect controller state through ROS entry points. · `robot_controllers_interface/scripts`
- [Controller manager](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_interface/include/robot_controllers_interface/controller_manager.h): lifecycle manager · Coordinates controller activation, deactivation, and state transitions. · `robot_controllers_interface/include/robot_controllers_interface/controller_manager.h`
- [Controller loader](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_interface/include/robot_controllers_interface/controller_loader.h): plugin loader · Loads controller implementations into the management layer. · `robot_controllers_interface/include/robot_controllers_interface/controller_loader.h`
- [Controller API](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_interface/include/robot_controllers_interface/controller.h): base interfaces · Core abstractions for controllers and their handle-based access. · `robot_controllers_interface/include/robot_controllers_interface/controller.h`
- [Handles](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers_interface/include/robot_controllers_interface/handle.h): access handles · Generic and joint-specific access points used by controllers. · `robot_controllers_interface/include/robot_controllers_interface/handle.h`

### Controller implementations

Concrete motion and behavior controllers plus shared trajectory and limiting logic.

- [Cartesian pose](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/cartesian_pose.h): arm controller · High-level Cartesian position/orientation control. · `robot_controllers/include/robot_controllers/cartesian_pose.h`
- [Cartesian twist](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/cartesian_twist.h): arm controller · High-level Cartesian velocity control. · `robot_controllers/include/robot_controllers/cartesian_twist.h`
- [Cartesian wrench](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/cartesian_wrench.h): arm controller · High-level Cartesian force/torque control. · `robot_controllers/include/robot_controllers/cartesian_wrench.h`
- [Diff drive](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/diff_drive_base.h): base controller · Mobile base controller for differential motion commands. · `robot_controllers/include/robot_controllers/diff_drive_base.h`
- [Joint trajectory](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/follow_joint_trajectory.h): trajectory controller · Executes follow-joint-trajectory behavior over robot joints. · `robot_controllers/include/robot_controllers/follow_joint_trajectory.h`
- [Gravity comp](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/gravity_compensation.h): compensation controller · Applies gravity compensation to the controlled mechanism. · `robot_controllers/include/robot_controllers/gravity_compensation.h`
- [Parallel gripper](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/parallel_gripper.h): end-effector controller · Controls a parallel gripper open/close action. · `robot_controllers/include/robot_controllers/parallel_gripper.h`
- [Point head](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/point_head.h): head controller · Points the robot head toward a target. · `robot_controllers/include/robot_controllers/point_head.h`
- [Scaled mimic](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/scaled_mimic.h): coordination controller · Scales and mirrors commands across coupled joints or actuators. · `robot_controllers/include/robot_controllers/scaled_mimic.h`
- [PID support](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/pid.h): control primitive · Reusable PID control logic shared by controllers. · `robot_controllers/include/robot_controllers/pid.h`
- [Trajectory utils](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/trajectory.h): trajectory core · Trajectory representation and execution support shared by controllers. · `robot_controllers/include/robot_controllers/trajectory.h`
- [Spline sampler](https://github.com/openai/robot_controllers/blob/indigo-devel/robot_controllers/include/robot_controllers/trajectory_spline_sampler.h): trajectory utility · Samples spline trajectories for smooth motion execution. · `robot_controllers/include/robot_controllers/trajectory_spline_sampler.h`

### External runtime

Operator entry points and lower-level robot execution assumed outside this repo.

- **ROS clients**: operator/tooling · External nodes or operators that invoke controller management and query state.
- **Joint hardware**: real-time layer · Lower-level firmware or hardware providing real-time joint control and feedback.

## Connections

- ROS clients → CLI tools: invoke · Operators use the ROS command-line tools to manage controllers.
- CLI tools → Controller manager: manage · Scripts call into the controller manager lifecycle API.
- Controller manager → Controller loader: load · The manager asks the loader to instantiate controller implementations.
- Controller loader → Controller API: bind · Loaded controllers are bound to the common controller interfaces.
- Controller manager → Controller state: publish · Manager exposes controller status through shared state messages.
- CLI tools → State query: query · CLI tooling can request controller state through an action interface.
- Controller manager → State query: serve · The manager answers controller state queries.
- Diff drive → Limiter params: configure · Diff-drive control uses limiter parameters from ROS messages.
- Diff drive → PID support: uses · Base control reuses shared PID support where needed.
- Joint trajectory → Trajectory utils: executes · Joint trajectory control relies on shared trajectory logic.
- Joint trajectory → Spline sampler: samples · Trajectory execution uses spline sampling for smooth setpoints.
- Cartesian pose → Controller API: implements · Concrete controllers implement the common controller contracts.
- Cartesian twist → Controller API: implements · Concrete controllers implement the common controller contracts.
- Cartesian wrench → Controller API: implements · Concrete controllers implement the common controller contracts.
- Diff drive → Controller API: implements · Concrete controllers implement the common controller contracts.
- Joint trajectory → Controller API: implements · Concrete controllers implement the common controller contracts.
- Gravity comp → Controller API: implements · Concrete controllers implement the common controller contracts.
- Parallel gripper → Controller API: implements · Concrete controllers implement the common controller contracts.
- Point head → Controller API: implements · Concrete controllers implement the common controller contracts.
- Scaled mimic → Controller API: implements · Concrete controllers implement the common controller contracts.
- Cartesian pose → Joint hardware: command · High-level commands ultimately target lower-level actuation.
- Cartesian twist → Joint hardware: command · High-level commands ultimately target lower-level actuation.
- Cartesian wrench → Joint hardware: command · High-level commands ultimately target lower-level actuation.
- Diff drive → Joint hardware: command · Base commands are forwarded to the underlying actuation layer.
- Joint trajectory → Joint hardware: command · Trajectory execution emits joint commands to the hardware layer.
- Parallel gripper → Joint hardware: command · End-effector commands are sent to the underlying actuator layer.
- Point head → Joint hardware: command · Head pointing behavior emits commands to hardware.
- Gravity comp → Joint hardware: compensate · Gravity compensation is applied before final actuation.
