How to bring your own embodiment#

Isaac ROS Deploy uses ros2_control to interface with robot hardware. This guide shows how to create the required package skeletons, add the SystemInterface implementations for the real and simulated robot, and add the corresponding launch and configuration files.

Prerequisites#

Before you begin, make sure you have:

A URDF description of the robot
A simulator asset (USD or MJCF) for each simulation platform that you plan to support
A C++ robot SDK for the real hardware

1. Create the package layout#

Create three packages for the new robot using the following split:

<robot>_description: Owns URDF or xacro descriptions and simulator assets.
<robot>_ros2_control: Owns the real-hardware SystemInterface plugin.
<robot>_bringup: Owns controller configuration, policy groups, and launch files.

2. Define the ROS 2 Control interfaces#

Next, determine which ROS 2 Control state and command interfaces the new embodiment should expose. Use the same interfaces for the real and simulated SystemInterface implementations.

For each target platform, add a ros2_control xacro to the <robot>_description package. Each xacro must define:

The platform-specific hardware plugin and its parameters
The command and state interfaces for each joint
The state interfaces for each IMU or other sensor

3. Add each target platform#

Implement only the tabs needed by the new robot.

You don’t need to implement a new SystemInterface for MuJoCo. Reuse mujoco_ros2_control and its MujocoSystemInterface, and configure it with the robot’s MJCF model. Provide:

A MuJoCo MJCF model.
A mujoco_pid.yaml parameter file. Pass this file to the controller manager. When a controller claims the position, kp, and kd interfaces, MujocoSystemInterface uses the commanded gains instead of the values under pid_gains. The file can also configure optional MuJoCo plugins, such as a virtual gantry.
A ros2_control xacro that selects MujocoSystemInterface and declares the shared interface contract from step 2.

The result is a robot description that the controller manager can load with the MuJoCo hardware plugin.

To interface with real hardware, implement a new C++ class derived from hardware_interface::SystemInterface in <robot>_ros2_control:

Implement lifecycle, interface export, read(), write(), and command-mode switching for the robot SDK.
Map URDF joint names to vendor SDK motor indices. Do not rely on the controller and SDK using the same joint order.
Register the class with pluginlib and reference that plugin from the real-hardware ros2_control xacro.

The upstream ros2_control guide explains how to write a hardware component.

4. Configure controllers and policy groups#

Add two files to <robot>_bringup:

controller_manager.yaml: Declares controller plugins, joints, gains, and controller-specific parameters.
controller_groups.yaml: Groups the controllers that run together. A policy group identifies the LEAPP bundle, source-to-topic mappings, command-interface prefix and suffix, and controller activation order.

Define the robot-specific joints, controllers, and safety thresholds explicitly rather than copying values from another embodiment unchanged.

5. Validate one layer at a time#

Validate the integration in this order on every supported platform:

The robot description expands without xacro or URDF errors.
The controller manager loads the selected hardware plugin.
State interfaces update with the expected joint and sensor names.
A simple test controller can claim and write the expected command interfaces.
The configured controller group loads with the LEAPP runtime selected for the policy.

Start with simulation. Move to real hardware only after the description, interface names, controller configuration, and policy tensor ordering match the simulation integration.