How openai/robot_controllers works
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: controller.h Controller API · diff_drive_base.h Diff drive · follow_joint_trajectory.h Joint trajectory · controller_manager.h Controller manager
Components 22
ROS contracts
Shared message and action types for controller state and parameters.
- Controller state · Published controller status and query results.
robot_controllers_msgs/msg/ControllerState.msg - State query · Action interface for requesting controller state information.
robot_controllers_msgs/action/QueryControllerStates.action - Limiter params · Parameter transport for diff-drive limiting behavior.
robot_controllers_msgs/msg/DiffDriveLimiterParams.msg
Controller interface
Lifecycle, loading, and runtime management of controllers.
- CLI tools · Start, stop, and inspect controller state through ROS entry points.
robot_controllers_interface/scripts - Controller manager · Coordinates controller activation, deactivation, and state transitions.
robot_controllers_interface/include/robot_controllers_interface/controller_manager.h - Controller loader · Loads controller implementations into the management layer.
robot_controllers_interface/include/robot_controllers_interface/controller_loader.h - Controller API · Core abstractions for controllers and their handle-based access.
robot_controllers_interface/include/robot_controllers_interface/controller.h - 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 · High-level Cartesian position/orientation control.
robot_controllers/include/robot_controllers/cartesian_pose.h - Cartesian twist · High-level Cartesian velocity control.
robot_controllers/include/robot_controllers/cartesian_twist.h - Cartesian wrench · High-level Cartesian force/torque control.
robot_controllers/include/robot_controllers/cartesian_wrench.h - Diff drive · Mobile base controller for differential motion commands.
robot_controllers/include/robot_controllers/diff_drive_base.h - Joint trajectory · Executes follow-joint-trajectory behavior over robot joints.
robot_controllers/include/robot_controllers/follow_joint_trajectory.h - Gravity comp · Applies gravity compensation to the controlled mechanism.
robot_controllers/include/robot_controllers/gravity_compensation.h - Parallel gripper · Controls a parallel gripper open/close action.
robot_controllers/include/robot_controllers/parallel_gripper.h - Point head · Points the robot head toward a target.
robot_controllers/include/robot_controllers/point_head.h - Scaled mimic · Scales and mirrors commands across coupled joints or actuators.
robot_controllers/include/robot_controllers/scaled_mimic.h - PID support · Reusable PID control logic shared by controllers.
robot_controllers/include/robot_controllers/pid.h - Trajectory utils · Trajectory representation and execution support shared by controllers.
robot_controllers/include/robot_controllers/trajectory.h - Spline sampler · 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 · External nodes or operators that invoke controller management and query state.
- Joint hardware · Lower-level firmware or hardware providing real-time joint control and feedback.
Connections 28
- 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.