ROS2 Control LEAPP Runtime

The ROS2 Control LEAPP Runtime allows running a LEAPP bundle as a ROS 2 controller plugin inside the ros2_control update loop.

Note

This runtime supports LEAPP bundles with a single node exported with backend: onnx. For multi-model bundles (for example, VLAs), use the ROS2 Node LEAPP Runtime.

Architecture

The InferenceController is a ROS 2 controller plugin that wraps the core isaac_deploy_core::InferenceController. On each update() tick it:

1. Reads hardware state via StateInterfaceAdapter

2. Converts topic messages via the converter registry

3. Delegates to the core controller for inference

4. Writes results to hardware via CommandInterfaceAdapter

graph TD A["Hardware Interface - Read"] --> B["StateInterfaceAdapter → NamedTensors"] subgraph InferenceController B --> C["InputBuilder (preprocess: reorder, history, reshape)"] C --> D["InferenceRunner (Triton)"] D --> E["OutputBuilder (postprocess)"] E --> F["CommandInterfaceAdapter → Hardware Commands"] end F --> G["Hardware Interface - Write"]

Key Components

StateInterfaceAdapter

Creates tensors from hardware state interfaces (joint positions, velocities, IMU data). Each input term in the bundle configuration YAML whose semantic kind has a registered state interface converter is automatically read from hardware.

Converter Registry

Creates tensors from ROS topic messages (velocity commands, reference motions). Input terms whose semantic kind does not have a registered state interface converter are treated as topic inputs. The controller subscribes to the appropriate ROS topic and uses a MessageToTensorConverter to produce tensors.

CommandInterfaceAdapter

Converts output tensors back into hardware command interfaces (position targets, stiffness, damping). Each output term with a registered command interface converter writes directly to ros2_control command interfaces.

Controller Chaining

The inference controller can be used standalone but is normally chained through a safety controller:

inference_controller → safety_controller → hardware

This is configured via the command_prefix and command_suffix parameters on the inference controller. For example, with command_prefix: safety_controller and command_suffix: _raw, position commands are written to safety_controller/left_hip_pitch_joint/position_raw.

Parameters

Parameter	Type	Default	Description
config_path	string	""	Path to the LEAPP bundle configuration YAML (required).
model_path	string	""	Override model path from the bundle configuration YAML. If empty, uses the path in that file.
decimation	int	4	Run inference every N control cycles.
command_prefix	string	""	Prefix for command interface names (for controller chaining).
command_suffix	string	""	Suffix for command interface names (for controller chaining).

InferenceController Debug Topics

The InferenceController can optionally publish flattened model inputs and the selected output tensor for debugging or validation. These topics are disabled by default.

Debug topic parameters

Parameter	Type	Default	Description
publish_debug_topics	bool	false	Publishes ~/debug_observation and ~/debug_action when enabled.
debug_action_output_name	string	arm_action	Name of the model output tensor to publish on ~/debug_action.
log_debug_to_console	bool	false	Logs debug observation and action tensors to the controller logger when enabled.

Debug topics

Topic	Type	Description
~/debug_observation	std_msgs/msg/Float64MultiArray	Flattened model input tensors after the controller has built the inference inputs.
~/debug_action	std_msgs/msg/Float64MultiArray	Flattened values from the configured model output tensor.

SafetyController Command Introspection

The SafetyController can optionally publish the blend-scaled joint-position delta that it applies between the measured state and the inference command. This topic is disabled by default.

Command introspection parameters

Parameter	Type	Default	Description
publish_scaled_joint_delta	bool	false	Publishes ~/scaled_joint_delta when enabled.
scaled_joint_delta_topic	string	~/scaled_joint_delta	Topic used for the scaled joint-position delta.

Command introspection topics

Topic	Type	Description
~/scaled_joint_delta	sensor_msgs/msg/JointState	Per-joint delta computed as blend_ratio * (command_position - current_position).