Kontrol’Em — state-space control for ROS 2¶

Kontrol’Em is an end-to-end, ROS 2-native workflow for linear state-space control design on robots described by a URDF — from rigid-body model to synthesized controller to animated closed-loop response. It is, in spirit, a MoveIt Setup Assistant for state-space control: MoveIt targets motion planning; Kontrol’Em targets controller synthesis (LQR, LQG, H∞, PID) on plants linearized directly from the robot’s own URDF.

Note

Research software accompanying an undergraduate thesis. Simulation-validated on the included examples. Source: github.com/rahgirrafi/kontrolem · License: MIT.

In plain words¶

Some robots naturally fall over — think of balancing a broom on your hand. Keeping them steady takes constant, split-second corrections; that job is done by a piece of software called a controller. Kontrol’Em designs that controller for you from a description of your robot, lets you watch it work in your browser, and runs it on a real or simulated robot — no control-theory PhD required to get started.

New here? Follow this path

The big ideas, in plain words — 10 minutes, no math.
Tutorials — install it and make a robot balance itself, step by step.
Package guides & reference (below) — the deep detail on each tool.

The pipeline¶

 ┌─────────────────────┐   (A,B,C,D)   ┌────────────────────┐   K / K(s)   ┌──────────────────────┐
 │  urdf_state_space   │──────────────▶│ state_space_control│─────────────▶│ state_space_         │
 │  URDF → LTI plant   │   u_eq, q_eq  │  LQR·LQG·H∞·PID    │  controller  │ response_viz         │
 │  (Pinocchio,        │               │  plugin registry   │              │ RViz playback of the │
 │  analytic Jacobians)│               └────────────────────┘              │ closed-loop response │
 └─────────────────────┘                        ▲                          └──────────────────────┘
            │                                   │                                      ▲
            │            ┌──────────────────────┴────────────────────────┐             │
            └───────────▶│         state_space_setup_assistant           │─────────────┘
                         │  web wizard: load → validate → operating point│  RobotTrajectory
                         │  → linearize → design → benchmark → export    │  (.npz interchange)
                         └───────────────────────┬───────────────────────┘
                                                 │ <name>_ros2_control.yaml
                                                 ▼
                         ┌───────────────────────────────────────────────┐
                         │            kontrolem_controllers              │
                         │  chainable ros2_control plugins (C++): load    │
                         │  the exported gains, run LQR/LQG/H∞ realtime   │
                         │  on mock · Gazebo Fortress · Isaac Sim         │
                         └───────────────────────────────────────────────┘

Design happens offline in Python; deployment is a separate C++ runtime, kontrolem_controllers, that loads the exported bundle and runs the controller under ros2_control — validated in Gazebo Fortress and Isaac Sim on the same cart–double-inverted-pendulum.

Every module speaks one canonical interchange format, RobotTrajectory: producers write it (the linear closed-loop simulation today; nonlinear simulators, MuJoCo, rosbag / real-robot logs later), consumers read it (RViz playback, the wizard’s response step, benchmark playback). Adding a producer or a consumer touches no existing code — see Architecture.

Packages¶

Package	Role
urdf_state_space	URDF → linear state-space plant `(A,B,C,D)` by analytic linearization (Pinocchio `computeABADerivatives`), with gravity-compensation `u_eq`, actuation selection, exact ZOH discretization.
state_space_control	Controller-synthesis toolbox: LQR, LQG, H∞, PID behind a `@register` plugin registry; also home of the canonical trajectory format, the excitation registry, and the closed-loop simulator.
state_space_setup_assistant	MoveIt-Setup-Assistant-style web wizard: load → validate → operating point → linearize → design → response → benchmark → export.
state_space_response_viz	Source-agnostic RViz playback of `RobotTrajectory` files with play/pause/seek/speed transport control.
kontrolem_example_robots	Example URDFs — the cart double inverted pendulum used throughout these docs.
kontrolem_controllers	Runtime / deployment (C++): chainable `ros2_control` plugins that load the exported LQR/LQG/H∞ bundle and run it realtime on mock, Gazebo Fortress, and Isaac Sim hardware.

Where to start¶

Brand new to this? Read the big ideas in plain words, then do the tutorials.
Prefer a fast command-line tour? The Quickstart runs the whole pipeline in 5 minutes.
Want the design rationale? Architecture explains the canonical trajectory format and the clock × sampler × renderer playback model.
Building on top of it? Extending the framework shows how to add a controller, an excitation, or a renderer in one file each; the normative The RobotTrajectory format spec is what any new producer/consumer targets.
Ready to deploy on a robot? Runtime & deployment covers the C++ ros2_control runtime that runs the exported controller, with physics validation in Gazebo and Isaac.
Looking for a specific function? See the API reference.