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.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)
• Documentation on Generating MJCFs (#167)
• Use requirements.txt to install python dependencies (#151)
• Allow freejoint without name (#163)
• Replace stream logging with compiled log statements (#160)
• Increase timeout on sim being ready to 10s (#161)
• improve debug logs (#159)
• Search delimiter from back to support joint names with '/' (#158)
• Use right arrow key to advance the simulation instead of S key (#150)
• [Feature] Add ability to run the simulation progress by steps upon pause (#139)
• disable site visuals by default in the visualizer and cameras (#149)
• Contributors: Christian Rauch, Emily Sheetz, Erik Holum, Nathan Dunkelberger, Sai Kishor Kothakota, Óscar Martínez Martínez, Mathias Lüdtke

0.0.2 (2026-03-17)

• Update internal links for myst-parser readthedocs (#148)
• Fix reset simulation service for robots using PID control (#140)
• throw on failing init of mujoco_ros2_control_plugins (#136)
• Cleanup duplicate files (#146)
• Export mujoco_ros2_control_plugins (#138)
• [URDF->MJCF] fixed path for urdf with test (#127)
• Set MuJoCo install include dirs (#135)
• [Feature] MuJoCo ros2 control plugins (#133)
• Use pixi-build-ros as the backend for pixi builds (#130)
• Rename default node to mujoco_ros2_control_node (#132)
• Changes necessary to also work for MuJoCo 3.5.0 (#123)
• Update license name to SPDX standard (#129)
• Add minor fixes to the conversion methods (#125)
• Update RPATH of the mujoco_vendor libraries (#122)
• Improve testing for URDF->MJCF tooling (#119)
• Add git dependency (#121)
• Contributors: Christoph Fröhlich, Erik Holum, Julia Jia, Ortisa, Sai Kishor Kothakota, Nathan Dunkelberger, Jordan Palacios

0.0.1 (2026-02-24)

• Update documentation of URDF <-> MJCF tool (#117)
• Add proper logging for the mimic joints (#118)
• Fix mardown link checker CI + fix local references (#114)
• Updates docs and comments (#113)
• Cleanup of Docs and Dev Guides (#111)
• Update other ROS Controls maintainers (#112)
• Update README.md across repository (#110)
• Conditioning visual fixes on if there are images or not for daes (#109)
• Cleanup the non-vendor mujoco install (#105)
• Feature: Add [--no-fuse]{.title-ref} arg to preserve body hierarchy (#93)
• Add [mujoco_vendor]{.title-ref} integration (#6)
• Containerize pixi in CI (#99)
• Add ResetWorld service to reset to a specific defined keyframe (#95)

File truncated at 100 lines see the full file