# How Microduck Robot Models Are Defined in MJCF Format

> Learn how Microduck robot models are defined in MJCF format using Onshape CAD data and JSON configuration. Generate MJCF XML files for MuJoCo simulation.

- Repository: [Pollen Robotics/microduck_rl](https://github.com/pollen-robotics/microduck_rl)
- Tags: how-to-guide
- Published: 2026-09-02

---

**Microduck robot models are generated from Onshape CAD data via JSON configuration files that configure the onshape-to-robot exporter, producing MJCF XML files containing hierarchical body definitions, actuator classes, and sensor specifications for MuJoCo simulation.**

The `pollen-robotics/microduck_rl` repository defines Microduck robot models using MuJoCo's MJCF (MuJoCo XML) format to enable physics-based reinforcement learning. Rather than authoring these files manually, the project uses an automated pipeline that converts Onshape CAD assemblies into simulation-ready XML through structured JSON configurations. This approach ensures that geometric changes in CAD propagate correctly to the simulation while maintaining precise control over collision properties, joint behavior, and sensor placement.

## The MJCF Generation Pipeline

Microduck MJCF files are created using the **onshape-to-robot** exporter, which processes JSON configuration files stored in `src/mjlab_microduck/robot/microduck/`. These configurations bridge the gap between parametric CAD data and physics simulation by specifying how to translate Onshape assemblies into MuJoCo-compatible XML.

### JSON Configuration Files

The pipeline is driven by two primary configuration files:

- **[`config_mjcf_walk.json`](https://github.com/pollen-robotics/microduck_rl/blob/main/config_mjcf_walk.json)** – Generates the walking model ([`robot_walk.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/robot_walk.xml)) optimized for locomotion tasks
- **[`config_mjcf_allcollisions.json`](https://github.com/pollen-robotics/microduck_rl/blob/main/config_mjcf_allcollisions.json)** – Generates a model ([`robot_allcollisions.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/robot_allcollisions.xml)) with comprehensive collision mesh data

Each JSON file acts as a manifest that tells the exporter which Onshape document to pull, how to simplify the geometry, and which supplemental XML fragments to inject into the final MJCF.

### Export Process

When the exporter runs, it retrieves the specified CAD assembly from Onshape, converts the geometry to STL meshes, and assembles the kinematic tree. The resulting structure is then combined with hand-written XML snippets to produce the final MJCF file that MuJoCo loads.

## JSON Configuration Structure

The configuration files in `src/mjlab_microduck/robot/microduck/` contain specific fields that control every aspect of the MJCF generation:

- **Source CAD URL** – A link to the Onshape document containing the robot geometry
- **Output format** – Always set to `"mujoco"` to ensure MJCF output
- **Robot name and output filename** – Defines the model identifier (e.g., `"microduck"`) and target file (e.g., `"robot_walk"`)
- **Simplification options** – Parameters like `simplify_stls` and `max_stl_size` control mesh decimation for performance
- **Ignore rules** – A mapping of part name patterns marked as `"collision"` or kept as visual-only geometry (e.g., `!sole_left` retains the left foot as a visual mesh)
- **Additional XML snippets** – References to [`joints_properties.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/joints_properties.xml), [`sensors.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/sensors.xml), and [`additional.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/additional.xml) that get concatenated into the final output
- **Post-import commands** – A series of `sed` commands that modify the generated XML, including positioning the trunk, renaming foot collision bodies, fixing inheritance ranges, and injecting camera elements
- **Joint properties** – Specifications for default actuator classes (`chosen_actuator`) and passive joint classes (`passive_joint`) that determine how the robot is controlled once loaded

## MJCF Composition and XML Snippets

The final MJCF files are assembled from multiple source documents that define specific simulation behaviors:

**[`joints_properties.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/joints_properties.xml)** defines actuator and passive joint classes used throughout the model. This file establishes the `chosen_actuator` class used for trainable joints and `passive_joint` classes for unactuated degrees of freedom.

**[`sensors.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/sensors.xml)** contains the sensor suite specifications, including IMU orientation, gyroscope, accelerometer, velocimeter, and subtree angular momentum sensors. These elements are injected into the MJCF's `<worldbody>` or `<sensor>` sections.

**[`additional.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/additional.xml)** provides miscellaneous MJCF additions such as collision groups, equality constraints, and default visual properties that are not generated automatically from the CAD data.

## Structure of Generated MJCF Files

The resulting MJCF files (e.g., [`robot_walk.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/robot_walk.xml) and [`robot_allcollisions.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/robot_allcollisions.xml)) contain several standardized sections:

**Global MJCF settings** – Compiler options, default visual classes, and timestep configurations that affect numerical stability.

**Joint class definitions** – Actuator classes (`chosen_actuator`, `perfect_actuator`) and passive classes (`passive_wheel`, `passive_joint`) that map to specific control modes in the training environment.

**Sensor definitions** – The complete sensor array specified in [`sensors.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/sensors.xml), enabling state estimation for reinforcement learning policies.

**Collision handling** – A `<default class="self_collision_only">` block defines geometry used exclusively for self-collision detection, while explicit `<exclude>` tags (typically commented out) can suppress unwanted contact pairs between specific body pairs.

**Body hierarchy** – The full kinematic chain starting from the trunk, branching to hips and legs (trunk → hips → legs → feet) and the neck-head assembly. Each joint references one of the predefined classes from the joint-property map, ensuring consistent damping and actuation limits.

## Loading Microduck MJCF Models in Python

Once generated, the MJCF files can be loaded directly through MuJoCo's Python API for standalone simulation:

```python
import mujoco
from mujoco import viewer

# Load the walking robot MJCF generated by the exporter

model_path = "src/mjlab_microduck/robot/microduck/robot_walk.xml"
model = mujoco.MjModel.from_xml_path(model_path)

# Create a simulation instance

sim = mujoco.MjSim(model)

# Simple step loop that prints trunk height

for i in range(100):
    sim.step()
    qpos = sim.data.qpos.copy()
    print(f"Step {i}: trunk_z={qpos[2]:.3f}")

# Optional visualisation

viewer.launch(model, sim)

```

## Integration with Training Environments

For reinforcement learning, the MJCF models are consumed by the RSL-RL training environment through configuration factories:

```python
from mjlab_microduck.tasks.microduck_velocity_env_cfg import make_microduck_velocity_env_cfg

# Build the environment configuration for the walking robot

cfg = make_microduck_velocity_env_cfg(play=False, rough=False)

# The config automatically points to the MJCF model defined in

# src/mjlab_microduck/robot/microduck/robot_walk.xml

env = cfg.make()
obs = env.reset()

```

This integration allows PPO agents to control the robot through the defined actuators while respecting the collision and sensor specifications embedded in the MJCF.

## Summary

- Microduck MJCF files are generated from Onshape CAD using the onshape-to-robot exporter and JSON configuration files located in `src/mjlab_microduck/robot/microduck/`.
- The **JSON configurations** specify source URLs, mesh simplification rules, ignore patterns for visual-only parts, and references to supplemental XML files.
- Three XML snippets—[`joints_properties.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/joints_properties.xml), [`sensors.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/sensors.xml), and [`additional.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/additional.xml)—are concatenated into the final MJCF to define joint classes, IMU sensors, and collision groups.
- Generated files like [`robot_walk.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/robot_walk.xml) contain complete MuJoCo models with hierarchical body definitions, actuator classes (`chosen_actuator`), and self-collision geometry.
- The models are loaded via `mujoco.MjModel.from_xml_path()` for standalone simulation or integrated into RSL-RL training environments for reinforcement learning.

## Frequently Asked Questions

### What is the difference between robot_walk.xml and robot_allcollisions.xml?

The [`robot_walk.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/robot_walk.xml) file is optimized for locomotion tasks with selective collision meshes and simplified geometry to improve simulation speed. In contrast, [`robot_allcollisions.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/robot_allcollisions.xml) contains comprehensive collision data for all robot parts, making it suitable for tasks requiring precise contact detection across the entire body surface but potentially slower to simulate.

### How do I modify the robot's collision properties?

Collision properties are controlled through the `ignore` rules in the JSON configuration files and the `<default class="self_collision_only">` section in the generated MJCF. To change collision behavior, edit [`config_mjcf_walk.json`](https://github.com/pollen-robotics/microduck_rl/blob/main/config_mjcf_walk.json) or [`config_mjcf_allcollisions.json`](https://github.com/pollen-robotics/microduck_rl/blob/main/config_mjcf_allcollisions.json) to adjust which STL files are marked as collision geometry, then regenerate the XML using the onshape-to-robot exporter.

### Can I use a different CAD source for the MJCF generation?

Yes. You can modify the **Source CAD URL** field in the JSON configuration files to point to a different Onshape document. However, the part naming conventions must remain consistent because the exporter relies on specific name patterns (like `!sole_left`) to apply ignore rules and joint assignments correctly.

### How are joint actuators configured in the Microduck MJCF?

Joint actuators are configured through the [`joints_properties.xml`](https://github.com/pollen-robotics/microduck_rl/blob/main/joints_properties.xml) snippet referenced in the JSON configuration. This file defines the `chosen_actuator` class assigned to trainable joints and `passive_joint` classes for unactuated degrees of freedom. When MuJoCo loads the MJCF, it instantiates actuators according to these class definitions, allowing reinforcement learning policies to interface with the robot through standardized control signals.