SO-101 · MuJoCo · lerobot plugin

lerobot_env_so101

A pick-cube environment for the SO-101 arm where every action dimension does something. Four dimensions, no dead inputs, and a gripper command that means what it says. Runs as a plain gymnasium environment; lerobot is optional.

Get started API reference PyPI

pip install lerobot-env-so101

The action space, drawn to scale

-10+1

dxdelta

dydelta

dzdelta

graspabsolute

The vertical rule marks zero. For a position delta it sits at the centre of the range; for grasp the same zero is the left edge, because it is an absolute target — 0 is fully closed, not "unchanged". That asymmetry is the whole action space: Box([-1, -1, -1, 0], 1.0, (4,), float32).

The upstream gym-hil port this came from declared three more dimensions that the IK solver silently discarded:

drxdead

drydead

drzdead

SO-101's 5-DOF arm cannot track a 6-DOF Cartesian pose, so a policy could spend capacity learning to depend on inputs that had zero effect on the simulation. Verified rather than assumed: perturbing each of the four remaining dimensions moves the state — 0 of 4 dead. See Action space.

What it looks like

A hand-written controller driving a reach→gripper-close motion — not a successful pick-and-lift. A top-down grasp is not yet reachable with the position-only IK; see Limitations.

Two more things the upstream port got wrong

• The gripper was an increment. grasp=0 used to mean "leave it alone"; it now means "fully closed", mapped onto the actuator's native radian range. This is a breaking change as of v0.2.0.
• Sparse-mode success ignored the gripper. Upstream computes a strict success check, then replaces it with a lift-only test in sparse mode. Measured here before the fix: the gripper 0.092 m from the block (threshold 0.05 m), block lifted 0.20 m, reported as success. A block knocked upward counted as a pick.

Both are detailed in What changed vs. the upstream port.

Where to go next

If you want to	Read
Run your first episode	Getting started
Use it from lerobot's CLI or a policy	Using it with lerobot
Understand what the 4 action dimensions do	Action space
Debug a crash or a surprising result	Limitations and troubleshooting
Look up a class or argument	API reference

License and attribution

Apache-2.0. The SO-101 MJCF/URDF and the original control code were authored by Paul Loh (github.com/lohpaul9) and ported from lohpaul9/gym-hil; the base gym-hil project structure is Copyright 2024 The HuggingFace Inc. team. Full attribution is in Using it with lerobot.