MuJoCo for SO-100 Simulation: Building the Model, Reading the Gap

An SO-100 costs roughly 110 to 150 EUR in parts, and every one of those parts is a 3D print held together by M2 screws. That is the first reason to build a MuJoCo model of it: a simulator does not snap a shoulder bracket when your controller overshoots. The second is that some questions are faster to ask in a simulator. Can the wrist reach that corner of the table with the gripper pointing down? What happens if the teleoperation stream drops for 200 ms? Which joint sags first under a 150 g payload?

This page is about the specific case: putting an SO-100 or SO-101 into MuJoCo. Which published MJCF to start from, what those files actually claim about the Feetech STS3215 servos, where those numbers came from and where they are wrong, and the point at which a simulated policy stops helping with the kind of LeRobot workflow this platform runs. Every file quoted below was opened on 24 August 2026, and the sag numbers further down are measurements taken from the published model, not estimates.

Two published MJCF models, and they do not agree

There is no single canonical file. TheRobotStudio's SO-ARM100 repository has a Simulation folder with two subdirectories. Simulation/SO100 contains so100.urdf, a rerun file and 13 STL meshes, and no MJCF at all. Simulation/SO101 has the real thing: so101_new_calib.xml, so101_old_calib.xml, matching URDFs, a scene.xml and a small joints_properties.xml. If you own an SO-100 rather than an SO-101, the MJCF you want is in MuJoCo Menagerie under trs_so_arm100, contributed separately and derived from an older SO-100 URDF.

The two calibrations in the vendor repo matter before you load anything. so101_new_calib.xml puts each joint's virtual zero at the middle of its range. so101_old_calib.xml puts zero where the arm is fully extended horizontally. Same arm, same degrees of freedom, offset joint coordinates. Replay recorded angles into the wrong one and the arm moves smoothly and is wrong everywhere, which is much harder to notice than a crash.

Get the model on screen in about five minutes

1. 1
   Install the bindings

   MuJoCo ships as a self-contained Python wheel. The current release is 3.12.0, published 20 August 2026. The Menagerie SO-100 model declares a floor of 3.1.6.

   bash

   python -m venv .venv && source .venv/bin/activate
   pip install mujoco
   python -c "import mujoco; print(mujoco.__version__)"

2. 2
   Fetch the model

   Menagerie is large and you need one directory out of it. A sparse clone keeps it to a few megabytes.

   bash

   git clone --depth 1 --filter=blob:none --sparse \
       https://github.com/google-deepmind/mujoco_menagerie.git
   cd mujoco_menagerie && git sparse-checkout set trs_so_arm100
   ls trs_so_arm100
   # assets  CHANGELOG.md  LICENSE  README.md  scene.xml  so_arm100.png  so_arm100.xml

3. 3
   Look at it

   Load scene.xml, not so_arm100.xml. The scene adds the ground plane, skybox and light; without a floor geom the arm has nothing to push against.

   bash

   python -m mujoco.viewer --mjcf=trs_so_arm100/scene.xml

4. 4
   Step it from Python

   The managed viewer blocks. For anything scripted you want mj_step in your own loop, and on macOS viewer.launch_passive must run under the mjpython launcher that the wheel installs.

   bash

   python drive_arm.py            # Linux / Windows
   mjpython drive_arm.py          # macOS, only for launch_passive

import mujoco
import numpy as np

m = mujoco.MjModel.from_xml_path("trs_so_arm100/scene.xml")
d = mujoco.MjData(m)

print("timestep", m.opt.timestep)   # 0.002 s -> 500 Hz, MuJoCo's default
print("nq", m.nq, "nu", m.nu)       # 6 joint coordinates, 6 position actuators
print("integrator", m.opt.integrator)   # 0 = Euler, the default

# keyframe 0 is "home", keyframe 1 is "rest"
mujoco.mj_resetDataKeyframe(m, d, 0)
d.ctrl[:] = d.qpos[:m.nu]           # command the pose we are already in

for _ in range(500):                # 500 * 0.002 s = 1.0 s of simulated time
    mujoco.mj_step(m, d)

print(np.degrees(d.qpos[:m.nu]).round(2))
# [  0.   -89.53  90.27  89.95 -89.95   0.  ]
# commanded -90 at the shoulder, settled at -89.53: half a degree of droop
print("actuator torque", d.actuator_force.round(3))
# [-0.  -0.37  -0.277  0.  0.  -0.]

What MuJoCo gets right about this arm

MuJoCo stands for Multi-Joint dynamics with Contact. It simulates in generalized coordinates with a convex, optimization-based contact model, which is a good match for a six-joint serial arm. The parts of the SO-100 that really are rigid bodies on hinges simulate well. The parts that are a plastic gearbox with a P controller inside do not. Sorting your questions into those two buckets is most of the skill.

• Reachability and workspace: where the end effector can go and in which orientations.
• Joint limits. The 2025-06-09 Menagerie changelog entry reads "adjusted joint limits to match real robot's physical constraints". A trajectory that clips a limit in sim clips it on the bench too, the same class of problem as a joint that stops early.
• Static gravity load: which pose sags, and roughly what torque each joint holds. Link masses in both models come from CAD.
• Controller stability: whether your gains ring, whether 30 Hz is enough, whether a setpoint step saturates the actuator. You can watch actuator_force clip against forcerange directly.
• Timing arithmetic. At the default 0.002 s timestep, one second is 500 physics steps, so a 30 Hz command loop is one setpoint every 16.7 steps. Getting that ratio wrong is how "it works in sim" turns out to mean "it works at 500 Hz".
• Contact debugging. The bundled simulate utility draws contact points and force vectors, the fastest way to see why a grasp slips.

What it gets wrong about these servos

The torque limits are the 12 V number

This one will quietly invalidate an afternoon. The sts3215 default class in so101_new_calib.xml sets forcerange="-2.94 2.94". A kilogram-force centimetre is 0.0980665 N.m, so 30 kg.cm is 2.942 N.m. Seeed sells exactly such a part: the ST3215-C047, a 12 V servo with a 1:345 gearbox and 30 kg.cm stall torque. The arms here use the 7.4 V ST3215-C001, same 1:345 gearbox, rated 19.5 kg.cm stall and 5 kg.cm continuous. The match to 2.94 is exact, so the inference is hard to avoid, though no one in either repo states the provenance outright.

So the simulated arm is allowed 1.5 to 1.8 times the peak torque the real 7.4 V arm has, and six to seven times the torque it can hold without cooking. Stall torque is not an operating point; it is where the rotor stops and the winding heats. A policy that lifts by leaning on peak shoulder torque will lift once on the bench, then sag, then trip overload protection. That looks exactly like an arm that twitches and then sags, and people blame the power supply first.

What the inflated limit actually costs you

The gap is easy to overstate, so it is worth measuring. Loading the Menagerie model, commanding a reaching pose (shoulder at -68.8 degrees, elbow and wrist at 34.4) and letting it settle for four simulated seconds gives the numbers below. Rerunning with forcerange clamped to each candidate limit isolates what the wrong datasheet changes.

Backlash is declared and never wired up

so101_new_calib.xml contains a default class named backlash, commented as plus or minus 0.5 degrees, with a joint range of plus or minus 0.008726646 rad. Grep the file for uses and there are none: the string class="backlash" appears once, in the definition itself. Not one joint, not one geom references it. Somebody started following MuJoCo's documented backlash recipe and stopped. The recipe itself is short.

<body>
  <!-- driven joint: the actuator targets this one -->
  <joint name="elbow_flex" type="hinge" pos="0 0 0" axis="0 0 1" armature="0.028"/>
  <!-- backlash joint: free within a small range, no actuator -->
  <joint name="elbow_flex_lash" type="hinge" pos="0 0 0" axis="0 0 1"
         class="backlash"/>
  ...
</body>

<actuator>
  <position class="sts3215" name="elbow_flex" joint="elbow_flex"
            forcerange="-3.35 3.35" ctrlrange="-1.69 1.69"/>
</actuator>

The body's rotation relative to its parent is the sum of the two joints. The armature on the driven joint is not optional: without it the joint-space inertia matrix is singular, because two coincident joints could accelerate in opposite directions without meeting any inertia. For how much lash to model, one published bench test measured 1.3 mm of play at an 86 mm lever, about 0.87 degrees, against a datasheet limit of 0.5. The same test put repeatability near 0.17 degrees, roughly two counts on the 4096-step 12-bit encoder. It ran on a 12 V STS3215, so its torque numbers do not apply here, but it shares the 1:345 metal gearbox with the 7.4 V part, and backlash is a gearbox property. The mechanical figures travel; the torque figures do not.

Three gain values, two of them in the same repo

The kp=50 against kp=998.22 split is the headline, but the vendor repo does not even agree with itself. so101_new_calib.xml carries a comment reading "Additional joints_properties.xml" and then inlines a copy of that file. The actual joints_properties.xml sitting next to it specifies kp=17.8, kv=0.0, forcerange=-3.35 3.35, while the inlined copy specifies kp=998.22, kv=2.731, forcerange=-2.94 2.94. Same directory, same servo, gains three orders of magnitude apart. Whichever you inherit depends on which file you load, and only the MJCF is actually loaded by scene.xml. Treat all three numbers as somebody's starting guess.

The gripper is a hinge here and a percentage in LeRobot

The SO-101 simulation README states it plainly: in LeRobot the gripper is a linear joint where 0 is fully closed and 100 is fully open, and that mapping is not yet reflected in the current URDF and MuJoCo files. In the MJCF it is a hinge, ctrlrange -0.17453 to 1.74533 rad on the SO-101 and -0.174 to 1.75 on the Menagerie SO-100. Pipe recorded gripper commands straight into d.ctrl and the jaw drives to a limit and stays there. Two lines to fix once you know, a long afternoon if you do not, and the same family as a gripper that does not close on real hardware.

One default class for six different loads

Both models apply one set of joint parameters to all six joints. armature is reflected rotor inertia and scales with the square of the gear ratio, so it differs per joint whenever the gearing does. On the SO-101 follower all six servos are 1:345, so a shared value is defensible. The leader is not uniform: Hugging Face's assembly guide lists 1:191 for shoulder pan and elbow flex, 1:345 for shoulder lift, and 1:147 for wrist flex, wrist roll and gripper. Friction is worse, since stiction in a plastic gearbox depends on load, temperature and runtime. A single frictionloss of 0.052 or 0.1 is a placeholder, and no policy trained against a placeholder inherits anything about the real thing.

Fitting the model to your own arm

None of this makes the model useless. It means the published parameters are a starting point and the fitting is your job. MuJoCo's own overview lists system identification as one of the things the engine is for. On a six-joint arm it is not exotic: drive a known input, record the real response, replay the same input in simulation, search a handful of parameters until the curves overlap. You already have the tooling if you are doing dataset recording, because a step response is a very boring episode.

1. 1
   Record a step response per joint

   Hold five joints, step the sixth by 20 to 30 degrees, log commanded and measured positions at your control rate. Two directions, two payloads: empty and a known mass in the jaw. The desktop client used for recording already logs joint states alongside the camera streams.

   bash

   # the point is a clean single-joint step and a log with t, ctrl[j], qpos[j]
   python record_step.py --joint shoulder_lift --amplitude-deg 25 --repeats 5

2. 2
   Replay the identical command sequence in MuJoCo

   Freeze the other joints at the pose you held on the bench and feed the recorded ctrl array in at the same rate, holding each command for the right number of physics steps.

   python

   steps_per_cmd = round((1.0 / cmd_hz) / m.opt.timestep)   # 30 Hz -> 17 steps
   sim = []
   for u in ctrl_log:
       d.ctrl[j] = u
       for _ in range(steps_per_cmd):
           mujoco.mj_step(m, d)
       sim.append(d.qpos[j])

3. 3
   Search the four parameters that matter

   kp, kv or dampratio, joint damping, frictionloss. A coarse grid usually gets inside a degree. Fit rise time and steady-state offset separately: frictionloss shows up as a dead band around the setpoint, damping shows up in the overshoot.

   python

   import itertools
   grid = itertools.product(
       [50, 100, 200, 400, 800],      # kp
       [0.0, 0.5, 1.0, 2.0, 3.0],     # kv
       [0.0, 0.3, 0.6, 1.0],          # joint damping
       [0.0, 0.02, 0.05, 0.1],        # frictionloss
   )
   best = min(grid, key=lambda p: rmse(replay(*p), bench_trace))

4. 4
   Fix forcerange, then sanity check against gravity

   Set forcerange to something you can defend (1.91 N.m for the physical ceiling, 0.49 for what the arm holds all day), park it horizontally with a known mass in the jaw, and compare steady-state sag. This is the test that catches a torque limit from the wrong datasheet; a low-load step response will not. Use the same pose as your data collection setup so the numbers compare.

   python

   m.actuator_forcerange[:] = [[-1.91, 1.91]] * m.nu
   m.actuator_forcelimited[:] = 1
   
   mujoco.mj_resetDataKeyframe(m, d, 0)
   d.ctrl[:] = target_pose
   for _ in range(4000):        # 8 s, well past settling
       mujoco.mj_step(m, d)
   print(np.degrees(d.qpos[:m.nu] - target_pose).round(2),
         "| peak torque", d.actuator_force.round(3))

Where a sim policy stops helping

This is the part that matters most if you arrived at MuJoCo from the VLA side. The five policies you can train here are all imitation learning policies. GR00T N1.7 and N1.5 are roughly 3 B parameter foundation models with a diffusion action head; on N1.7 about 40 M of those parameters train during fine-tuning. Pi0.5 is a flow-matching VLA on a PaliGemma backbone. SmolVLA is about 450 M. ACT is about 80 M and trains from scratch, with no base model at all. Every one of them consumes recorded episodes: joint states, camera frames, a task string. The numbers sit side by side on the policies page.

MuJoCo renders with OpenGL. It hands you an image with clean edges, no motion blur, no rolling shutter, no auto-exposure hunting when the gripper shadow crosses the table, and none of the sensor noise a cheap webcam produces. Domain randomization exists as a technique precisely because of this gap: Tobin and colleagues showed in 2017 that randomizing textures, lighting and camera pose can carry a detector across to real images. It works, and it is a training-time cost paid in addition to the fine-tune, not instead of it. If you are collecting demonstrations for a fine-tune, the honest advice is in the data collection guide: record real episodes.

If parallel simulation is what you need, look past plain MuJoCo. MuJoCo Playground, published February 2025, builds on MJX and reports training policies in minutes on a single GPU across quadrupeds, humanoids, dexterous hands and arms. The 10x single-scene penalty above is specific to the JAX implementation; the docs say the newer Warp implementation resolves several of those bottlenecks on NVIDIA hardware. The LeRobot sim2real project trains RL policies in ManiSkill and SAPIEN instead, with a zero-shot RGB tutorial that picks up cubes with an SO-100. For the NVIDIA stack, compare Isaac Lab and Isaac Gym. MuJoCo's strength is a fast, accurate, editable single-scene model you can read in a text editor: the right tool for understanding one arm, the wrong one for generating a million rollouts.

Two routes to a working policy

# 1. simulation side
pip install mujoco
git clone --depth 1 --filter=blob:none --sparse \
    https://github.com/google-deepmind/mujoco_menagerie.git
cd mujoco_menagerie && git sparse-checkout set trs_so_arm100
python -m mujoco.viewer --mjcf=trs_so_arm100/scene.xml

# SO-101 owners want the vendor files instead
git clone --depth 1 https://github.com/TheRobotStudio/SO-ARM100.git
python -m mujoco.viewer --mjcf=SO-ARM100/Simulation/SO101/scene.xml

# 2. hardware side, entirely separate
pip install -e ".[feetech]"        # LeRobot with the Feetech SDK
lerobot-find-port
lerobot-setup-motors --robot.type=so101_follower --robot.port=/dev/ttyACM0
lerobot-calibrate   --robot.type=so101_follower \
                    --robot.port=/dev/ttyACM0 \
                    --robot.id=my_follower

Frequently asked questions