unitree-g1-mujoco

Unitree G1 MuJoCo model for LeRobot

The default model has two Dex1-1 parallel grippers and three published cameras. The articulated Dex3 hands and the bare no-hand robot are also selectable, and their URDF, MJCF and meshes remain included. This is the model repository loaded dynamically by LeRobot through env.py.

The existing make_env() entry point, 29 body motor commands, body state DDS topics, simulation stepping and ZMQ image message format are preserved. MuJoCo loads assets/scene_33dof.xml, which includes the gripper MJCF derived from the supplied URDF. The portable URDF is also included at assets/g1_29dof_with_dex1_1.urdf; runtime cameras and actuators are defined in MJCF.

Choose the end effectors

End effectors are named after the hardware. config.yaml defaults to END_EFFECTOR: dex1. Scene, finger counts, effort limits and the published camera list all follow that selection automatically.

dummy is the bare robot with nothing attached to the wrists, so it publishes only head_camera. The earlier names grippers, hands and none are still accepted as aliases for dex1, dex3 and dummy.

Direct users of this repository can also call:

from env import make_env

if __name__ == "__main__":
    env = make_env(end_effector="dex3")  # Omit the argument for dex1.
    try:
        env.reset()
        while True:
            env.step()  # Body commands continue to arrive over DDS.
    finally:
        env.close()

The original assets/scene_43dof.xml, assets/g1_29dof_with_hand.xml, assets/g1_body29_hand14.urdf and no-hand model are retained unchanged.

Cameras

All three streams are enabled by default on tcp://127.0.0.1:5555, with 640 × 480 images and the existing approximately 30 Hz publishing setting.

Each stream is advertised through the same top-level JPEG key and nested images / timestamps entries as head_camera. The existing view_cameras_live.py discovers the names from those messages. They are also listed in env.camera_configs, env.camera_names and env.metadata["cameras"]. The wrist cameras move with their respective wrists, with 95° vertical field of view and the approximate extrinsics from the HIW-500 model builder.

LeRobot's ZMQ cameras require explicit client configuration, just as the head camera does. Pass this dictionary as UnitreeG1Config(..., cameras=cameras):

from lerobot.cameras.zmq.configuration_zmq import ZMQCameraConfig

cameras = {
    name: ZMQCameraConfig(
        server_address="127.0.0.1", port=5555, camera_name=name,
        width=640, height=480, fps=30,
    )
    for name in ("head_camera", "left_wrist_cam", "right_wrist_cam")
}

An equivalent camera configuration is in lerobot_cameras.json. make_env(cameras=["head_camera"]) selects a subset; publish_images=False disables publishing. onscreen=False disables the viewer for headless use.

Gripper control

Dex1 fingers use force actuators, driven by the existing bridge's external PD controller. They start open at 0.0245 m. To preserve the simulator's hand transport, the first two motor entries on rt/dex3/left/cmd and rt/dex3/right/cmd command fingers 1 and 2, with matching state topics. Gripper q is in metres and tau is in newtons; each finger is limited to 20 N. Command both fingers to the same position for symmetric opening or closing. Original hand mode retains all seven rotational command entries per side.

The simulation lower limit is -0.023 m, following HIW-500's mesh closure trim. The source and portable URDF retain the official -0.020 m lower limit. Run python build_gripper_model.py --official-limits to use that limit in MJCF too; it leaves approximately 5.88 mm between the supplied finger pads. This model update does not add finger actions to LeRobot's 29-body-motor UnitreeG1 action schema.

Development and checks

Install the existing Unitree SDK2 / CycloneDDS prerequisites, then python -m pip install -r requirements.txt. Regenerate the variants with python build_gripper_model.py.

MUJOCO_GL=egl python -m unittest discover -s tests -v
MUJOCO_GL=egl python tests/smoke_live.py
MUJOCO_GL=egl python tests/smoke_live.py --end-effector dex3

The regression suite uses real MuJoCo for both variants, motor/observation mapping, force-controlled closure, wrist camera motion, rendering and camera publisher shared-memory buffers. It isolates DDS with a test double. smoke_live.py additionally requires the real Gymnasium, Unitree SDK2 and ZMQ/OpenCV dependencies and checks the live environment and transports. See VALIDATION.md for what was executed for this update.

Sources

• Base model/runtime: lerobot/unitree-g1-mujoco.
• Dex1-1 URDF, meshes and wrist-camera geometry: Hxxxz0/HIW-500-controoler.
• LeRobot loading and camera configuration checked against main at b6ec006.

The original Dex1 source URDF, Apache 2.0 license and attribution notice are in reference/hiw500/. Unitree mesh assets retain their upstream terms.