Controllers Overview#

Kangaroo uses ros2_control as its hardware abstraction and controller management framework. This page explains the architecture and how it is applied to Kangaroo, before diving into the individual controllers documented in this section.

ros2_control Architecture#

ros2_control separates robot software into three layers that communicate through a shared in-memory data bus called the hardware resource interface:

┌─────────────────────────────────────────────────────┐
│                  Controller Manager                  │
│  loads, starts, stops, and switches controllers      │
└───────────────┬─────────────────────────────────────┘
                │  command / state interfaces
┌───────────────▼─────────────────────────────────────┐
│              Resource Manager                        │
│  owns the hardware interface data bus                │
└───────────────┬─────────────────────────────────────┘
                │  read() / write()
┌───────────────▼─────────────────────────────────────┐
│           Hardware Interface Plugin                  │
│  talks to the actual hardware or simulator           │
└─────────────────────────────────────────────────────┘

Key Components#

Controller Manager#

The controller_manager node is the central orchestrator. It loads controller plugins at runtime, manages their lifecycle (configure → activate → deactivate → cleanup), and enforces that only one controller claims each hardware interface at any given time.

Hardware Interface#

The hardware interface plugin implements the read() / write() cycle that bridges the ros2_control data bus to the real actuators (or simulator). Kangaroo’s hardware interface handles the EtherCAT communication to the actuator drives and exposes interfaces for two distinct component types: joints (joint-space values, after the transmission) and actuators (motor-side values, before the transmission).

Joint interfaces: joint-space quantities, transmission applied:

Interface type	Direction	Description
`position`	state	Current joint angle (rad)
`absolute_position`	state	joint angle projected from the absolute encoder (rad)
`velocity`	state	Current joint velocity (rad/s)
`effort`	state	Current joint torque (Nm)
`position`	command	Desired joint angle
`velocity`	command	Desired joint velocity
`effort`	command	Desired joint torque

Actuator interfaces: motor-side quantities, transmission bypassed:

Interface type	Direction	Description
`position`	state	Current actuator position (m)
`absolute_position`	state	Actuator position from the absolute encoder (m)
`velocity`	state	Current actuator velocity (m/s)
`effort`	state	Current actuator force (N)
`current`	state	Actual motor phase current (A)
`force`	state	Force from the internal load cell (N)
`position`	command	Desired actuator position (m)
`velocity`	command	Desired actuator velocity (m/s)
`effort`	command	Desired actuator force (N)
`current`	command	Desired motor current (A)

Controllers and Broadcasters#

Controllers are plugins that read information from the state interfaces and then write the commands to the command interfaces. They run in the same real-time control loop as the hardware interface. Multiple controllers can be active simultaneously as long as they claim disjoint sets of command interfaces. For example, joint_trajectory_controller, actuator_pid_controllers, forward_command_controller, pid_controllers etc.

Broadcasters are the set of controller plugins that only claim a set of state interfaces and use the information to manipulate and publish the information. For example, joint_state_broadcaster, imu_sensor_broadcaster, force_torque_sensor_broadcaster.

How ros2_control is Used in Kangaroo#

At startup the following sequence takes place:

The hardware interface plugins connects to the actuator drives over EtherCAT and initialises all the sensors and actuators.
The pid_command_controller runs once to upload the per-actuator PID gains for every control mode (position, velocity, current): see Actuator PID Controller.
The Controller Manager loads the set of controllers/broadcasters dynamically launched via different pal modules.
The operator (or launch file) activates the appropriate controller for the current task.

Controllers can be switched at runtime without restarting the robot using the Controller Manager service API or the ros2 control CLI:

# List all loaded controllers and their state
ros2 control list_controllers

# Switch active controllers
ros2 control switch_controllers \
  --activate  <controller_to_start> \
  --deactivate <controller_to_stop>

Different Interfaces on the Robot#

Kangaroo exposes hardware interfaces through the ros2_control resource manager. Each interface is addressed as <component>/<interface_name>. There are two categories: command interfaces (written by controllers to drive actuators) and state interfaces (read-only feedback from sensors and actuators).

Use ros2 control list_hardware_interfaces on the robot to see the live status of every interface.

The lower-body hardware is organized into the following components:

Component pattern	Count	Description
`leg_left_N_actuator` / `leg_right_N_actuator`	6 per side	Leg linear actuators (N = 1–5, length), covering hip yaw, hip roll, hip pitch, ankle pitch, ankle roll, and leg length
`leg_left_N_joint` / `leg_right_N_joint`	6 per side	Joint-space view of the same leg linear actuators (after transmission)
`leg_left_femur_joint` / `leg_right_femur_joint`	1 per side	Derived femur joint position from the parallel linkage mechanism (state only)
`leg_left_knee_joint` / `leg_right_knee_joint`	1 per side	Derived knee joint position from the parallel linkage mechanism (state only)
`pelvis_1_actuator` / `pelvis_2_actuator`	2	Pelvis roll and pitch actuators
`pelvis_1_joint` / `pelvis_2_joint`	2	Joint-space view of the pelvis actuators
`torso_imu_sensor`	1	IMU mounted on the torso
`robot/is_safe`	1	Global safety flag

The _actuator interfaces expose raw motor-side quantities (current, internal force sensor, PID gains applied on the drive), while the _joint interfaces expose the corresponding joint-space values after the gearbox and transmission.

Command Interfaces#

Command interfaces are claimed exclusively by an active controller. An interface marked [claimed] is in use; [unclaimed] is available.

Per leg linear actuators (leg_{left|right}_{1-5|length}_actuator):

Interface	Description
`position`	Target actuator position (m)
`velocity`	Target actuator velocity (m/s)
`effort`	Target actuator effort (N)
`current`	Target motor current (A)
`force`	Target force from the internal force sensor loop (N)
`mode`	Control mode selector (position / velocity / current / force)
`position_offset`	Additive offset applied on top of the position command
`force_offset`	Additive offset applied on top of the force command
`position.proportional`	P gain for the on-drive position PID
`position.integral`	I gain for the on-drive position PID
`position.derivative`	D gain for the on-drive position PID
`position.feedforward`	Feedforward term for the on-drive position PID
`velocity.proportional`	P gain for the on-drive velocity PID
`velocity.integral`	I gain for the on-drive velocity PID
`velocity.derivative`	D gain for the on-drive velocity PID
`velocity.feedforward`	Feedforward term for the on-drive velocity PID
`current.proportional`	P gain for the on-drive current PID
`current.integral`	I gain for the on-drive current PID
`current.derivative`	D gain for the on-drive current PID
`current.feedforward`	Feedforward term for the on-drive current PID
`force.proportional`	P gain for the on-drive force PID
`force.integral`	I gain for the on-drive force PID
`force.derivative`	D gain for the on-drive force PID
`force.feedforward`	Feedforward term for the on-drive force PID
`input.0`	Raw encoder input channel (present but not used)
`impedance.stiffness`	Stiffness gain for impedance control
`impedance.damping`	Damping gain for impedance control

Per leg joint (leg_{left|right}_{1-5|length}_joint):

Interface	Description
`position`	Target joint position (rad or m)
`velocity`	Target joint velocity (rad/s or m/s)
`effort`	Target joint effort (Nm or N)
`torque`/`force`	Target joint torque/force (Nm or N)

Pelvis actuators (pelvis_{1|2}_actuator) expose the same interface set as leg actuators. The corresponding pelvis_{1|2}_joint expose position, velocity, and effort.

Safety interface:

Interface	Description
`robot/is_safe`	Boolean flag (`true` = safe, `false` = fault); controllers can write `false` to signal an unsafe condition to the hardware interface

State Interfaces#

State interfaces are read-only and can be claimed by any number of controllers/broadcasters simultaneously.

Per leg rotary actuator and leg-length actuator (leg_{left|right}_{1-5|length}_actuator):

Interface	Description
`position`	Current actuator position (rad or m)
`absolute_position`	Crank/joint position referenced to the absolute encoder (rad or m)
`velocity`	Current actuator velocity (rad/s or m/s)
`effort`	Current actuator effort/torque (Nm or N)
`current`	Actual motor phase current (A)
`force`	Force measured by the internal load cell / force sensor (N)
`force_offset`	Current force offset applied by the drive (N)
`mode`	Active control mode reported by the drive
`position_offset`	Active position offset reported by the drive
`temperature_board`	Drive electronics board temperature (°C)
`temperature_motor`	Motor winding temperature (°C)
`position.proportional` / `position.integral` / `position.derivative` / `position.feedforward`	Active position PID gains echoed back from the drive
`velocity.proportional` / `velocity.integral` / `velocity.derivative` / `velocity.feedforward`	Active velocity PID gains echoed back from the drive
`current.proportional` / `current.integral` / `current.derivative` / `current.feedforward`	Active current PID gains echoed back from the drive
`force.proportional` / `force.integral` / `force.derivative` / `force.feedforward`	Active force PID gains echoed back from the drive
`input.0`	Raw encoder input channel (present but not used)
`impedance.stiffness`	Stiffness gain for impedance control echoed back from the drive
`impedance.damping`	Damping gain for impedance control echoed back from the drive

Per leg joint (leg_{left|right}_{1-5|length}_joint):

Interface	Description
`position`	Current joint position (rad or m)
`absolute_position`	Joint position from the absolute encoder perspective (rad or m)
`velocity`	Current joint velocity (rad/s or m/s)
`effort`	Current joint effort (Nm or N)

Derived parallel-linkage joints (state only: no command interfaces):

Interface	Description
`leg_{left\|right}_femur_joint/position`	Femur joint angle computed from the parallel four-bar linkage (rad)
`leg_{left\|right}_femur_joint/velocity`	Femur joint velocity (rad/s)
`leg_{left\|right}_femur_joint/effort`	Femur joint effort (Nm)
`leg_{left\|right}_knee_joint/position`	Knee joint angle computed from the parallel four-bar linkage (rad)
`leg_{left\|right}_knee_joint/velocity`	Knee joint velocity (rad/s)
`leg_{left\|right}_knee_joint/effort`	Knee joint effort (Nm)

Pelvis actuators and joints follow the same state interface layout as leg actuators and joints respectively.

IMU sensor (torso_imu_sensor):

Interface	Description
`orientation.x` / `.y` / `.z` / `.w`	Torso orientation as a quaternion
`angular_velocity.x` / `.y` / `.z`	Angular velocity in the torso frame (rad/s)
`linear_acceleration.x` / `.y` / `.z`	Linear acceleration in the torso frame (m/s²)

Safety interface:

Interface	Description
`robot/is_safe`	Boolean flag reporting the current safety status (`true` = safe, `false` = fault)

Transmissions#

Transmissions play a crucial role in robotics by converting motion and force between actuators and joints. In Kangaroo, custom transmissions are implemented to handle complex kinematic relationships, particularly for leg mechanisms. They map the motion from the high-speed, low-torque actuators to the desired joint movements, often involving mechanical linkages that provide mechanical advantage or convert linear motion to rotary motion, or vice-versa.

The transmissions map the following interfaces between the actuator space and the joint space:

Interface	Direction	Description
`position`	Bidirectional	Maps actuator position (m) to joint position (rad) and vice-versa
`velocity`	Bidirectional	Maps actuator velocity (m/s) to joint velocity (rad/s) and vice-versa
`effort`	Bidirectional	Maps actuator force (N) to joint torque (Nm) and vice-versa
`force`	Bidirectional	Maps actuator force sensor readings (N) to joint torque (Nm) and vice-versa
`absolute_position`	Actuator → Joint	Maps absolute encoder position from actuator to joint

Some transmissions, such as HipXYTransmission and AnkleXYTransmission, are differential transmissions: they combine the motion of two actuators to produce two output joint motions, and vice-versa. Among these, the AnkleXYTransmission is the most complex, as it additionally incorporates the states of the femur and knee derived from the parallel linkage to solve the forward kinematics of the ankle mechanism.

Transmission Type	Actuators Involved	Corresponding Joints (Commandable)	Read-only/Derived Components
HipZTransmission	Hip Actuator 1	Hip Yaw (Jont 1)	-
HipXYTransmission	Hip Actuator 2, Hip Actuator 3	Hip Pitch (Joint 2), Hip Roll (Joint 3)	-
LegLengthTransmission	Leg Length Actuator	Leg Length	-
LegLengthStateTransmission	Leg Length Actuator	-	Femur, Knee
AnkleXYTransmission	Ankle Actuator 4, Ankle Actuator 5, Leg Length Actuator(read-only)	Ankle Pitch (Joint 4) , Ankle Roll (Joint 5)	-

Claiming Command Interfaces: Rules and Restrictions#

Command interfaces for a given joint or actuator are mutually exclusive: only one control type can be active at a time. For instance, if leg_left_1_actuator is already commanded via its position interface, attempting to additionally claim velocity or effort will fail. The same rule applies to joint interfaces.

A joint interface and its corresponding actuator interface cannot be claimed simultaneously, nor can one be claimed while the other is already active. This restriction applies only to the position, velocity, effort, and force/torque interfaces, not to gain interfaces.
Joints and actuators that share a transmission must be claimed together. Claiming only one side of a transmission pair will cause the controller switch to fail.

The diagram below illustrates how the command path differs depending on which interface type is claimed:

Joint interface:    Joint Command ──► Transmission ──► Actuator (hardware)

Actuator interface: Actuator Command ──────────────────► Actuator (hardware)
                                   (transmission skipped)

When a joint interface is claimed, the command passes through the transmission layer, which maps joint-space values to actuator-space values. When an actuator interface is claimed directly, the transmission is bypassed entirely and the command is sent straight to the hardware.

The table below shows which actuator control mode is activated based on the combination of command interfaces claimed:

Claimed interface(s)	Actuator control mode	Notes
`position`	Position	`rad` for rotary joints converted to `m` for linear actuators
`velocity`	Velocity	`rad/sec` for rotary joints converted to `m/sec` for linear actuators
`effort`	Current	Nm (joint) / N (actuator) converted to A
`current`	Current	Direct current command in A
`force`	Force	Force-loop on internal force sensor
`torque`	Force	Nm converted to N via transmission
`position` + `velocity`	Impedance (current)	Stiffness/damping control, output in current
`position` + `velocity` + `impedance_force.feed_forward`	Impedance (force)	Impedance with feed-forward force term

Available Controllers#

The table below summarises every controller available on Kangaroo and its primary use case.

Controller	Use Case
Joint Trajectory Controller	Execute pre-planned joint trajectories (MoveIt, playback)
PlayMotion	Replay named motions stored in the parameter server
Whole Body Controller (WBC)	Hierarchical task-space control with joint-limit awareness
Actuator PID Controller	Upload per-actuator PID gains at startup
Torque Controller	Direct joint torque / effort commanding
Gravity Compensation	Compensate for gravity to allow compliant backdrivable operation
Force Reconstruction (Wrench Estimator)	Reconstruct the external foot wrench from actuator forces via the full model, no FT sensor required

Controllers Overview

Contents