MuJoCo ros2_control Simulation

This package contains a ros2_control system interface for the MuJoCo Simulator. It was originally written for simulating robot hardware in NASA Johnson’s iMETRO facility.

The system interface wraps MuJoCo’s Simulate App to provide included functionality. Because the app is not bundled as a library, we compile it directly from a local install of MuJoCo.

Parts of this library are also based on the MoveIt mujoco_ros2_control package.

URDF Model Conversion

MuJoCo does not support the full feature set of xacro/URDFs in the ROS 2 ecosystem. Users are required to convert any existing robot description files to an MJCF format. We provide a highly experimental tool to automate URDF conversion — refer to the URDF to MJCF conversion documentation for details.

Hardware Interface Setup

The MuJoCo hardware interface is shipped as a ros2_control plugin. Specify it in your URDF and point to a valid MJCF:

<ros2_control name="MujocoSystem" type="system">
  <hardware>
    <plugin>mujoco_ros2_control/MujocoSystemInterface</plugin>
    <param name="mujoco_model">$(find my_description)/description/scene.xml</param>
  </hardware>
  ...

A custom ros2_control node is required due to compatibility requirements:

control_node = Node(
    package="mujoco_ros2_control",
    executable="ros2_control_node",
    output="both",
    parameters=[
        {"use_sim_time": True},
        controller_parameters,
    ],
)

For the full plugin parameter reference, joint control modes, gripper/mimic joint setup, sensors (FTS, IMU), cameras, and lidar configuration, see the hardware interface documentation.

Simulation Topics and Services

The simulator exposes ROS 2 topics and services for interacting with the simulation at runtime (pause, reset, step-by-step control, etc.). See the simulation topics and services documentation for details.

Test Robot System

While examples are limited, we maintain a functional example 2-dof robot system in the demos space (see mujoco_ros2_control_demos package). We generally recommend looking there for examples and recommended workflows.

Development

More information is provided in the developers guide.

Further Documentation

Changelog for package mujoco_ros2_control

0.1.0 (2026-08-18)

• Add a pre-step callback to the simulation (#282)
• Fix control mode selection (#281)
• Support intvelocity actuators (#271)
• Add base twist plugin for commanding the mobile base (#254)
• Refine reset world overrides functionality (#263)
• Support joint overrides in reset world service (#256)
• Support multiple sets of state interfaces from multiple sensor tags with same name (#258)
• [Fix] Don't overwrite transmission-driven joint states in the direct-copy fallback (#259)
• [doc] Fix undefined label errors (#260)
• Add support for Magnetometer sensor (#257)
• [Feature] modify elements of geom attribute (#244)
• Add missing dependencies (#250)
• [CI] Fix dependency declarations for bloom (#226)
• Fix transmissions integration working with multiple actuators (#241)
• Add service to set the free joint body state (#233)
• Fix links in interface docs, use auto label generator like the upstream (#238)
• Fix state passed into pose sensors (#231)
• Fix controller manager rate collapse by decoupling control and physics locks (#224)
• Use updated ament_index_cpp interfaces, re-add rolling (#229)
• Add a 3-D Lidar Extension (#205)
• Add support for "site" transmission type (#154)
• Add support for pose sensors (#220)
• Fix deprecations in ament_index_cpp (#145)
• Fix race condition on sim-display overlay text (#222)
• Display the sim real time factor on the native viewer (#189)
• Refactor Rangefinder base Lidar as a Plugin (#214)
• Refactor RGB-D Cameras to a Plugin (#211)
• Add 'lyrical' to ros_distro matrix in CI workflow (#213)
• Fix scipy for openblas missing dependency (#212)
• Isolate flakey functional tests and update pixi (#204)
• Support/cameras rendering/headless (#197)
• Fix glfw initialization on headless run (#200)
• Add changes for mujoco vendor bump (#202)
• Control and plugin data input cleanup (#191)
• Migrate documentation to rst format for control.ros.org (#188)
• Refactor the core mujoco simulation to be in its own container (#175)
• Handle topic model loading failures with nullptr instead of exit (#183)
• Improve LiDAR validation in URDF-to-MJCF conversion (#182)
• Fix Sphinx xref_missing reference (#186)
• Handle duplicate mesh file names in the conversion tool (#171)
• Contributors: Christian Rauch, Christoph Fröhlich, Erik Holum, Julia Jia, Lang Qinglin, Marq Rasmussen, Ortisa, Sai Kishor Kothakota, Sebastian Castro, Tianlin Zhang, Daniel Costanzi, msavchen-nasa

0.0.3 (2026-05-01)

• Add more useful plugins for the mujoco_ros2_control (#165)
• Explicit scipy version for numpy >2.0 compatibility (#177)
• Use pkg install dir for requirements in conversion script (#170)

File truncated at 100 lines see the full file