How to Export Microduck Robot Models from Onshape: A Complete Guide

Microduck robot models are exported from Onshape using the open-source onshape-to-robot converter, which generates MJCF XML files and configuration JSONs that optionally pass through a backlash injection script before loading into MuJoCo.

The pollen-robotics/microduck_rl repository maintains its physical robot descriptions as MJCF (MuJoCo XML) files derived directly from CAD assemblies hosted on Onshape. This pipeline ensures that mechanical changes in the CAD model propagate automatically into the reinforcement learning simulation environment.

The Onshape-to-MJCF Export Pipeline

The export process relies on the onshape-to-robot tool, an open-source converter that transforms Onshape assemblies into robotics-ready formats. According to the source code, the generated MJCF files contain XML comments indicating their origin, such as <!-- Generated using onshape-to-robot -->, along with direct links to the original Onshape documents.

Generating the MJCF Robot Description

The converter produces .xml files that define bodies, joints, and actuators for the MuJoCo physics engine. For example, src/mjlab_microduck/robot/microduck/robot_walk.xml contains the complete kinematic tree generated from the Onshape assembly. This file serves as the primary robot description loaded by RL environments in the repository.

Configuration JSON for Traceability

Alongside each MJCF file sits a corresponding config_mjcf_*.json that stores export metadata. The JSON includes the Onshape document URL for full traceability:

{
  "url": "https://cad.onshape.com/documents/804927696f06d877f3f1803e/w/5b75db19292e71970de02dee/e/ef6e972847fec8d82570b35e"
}

This configuration file resides at src/mjlab_microduck/robot/microduck/config_mjcf_walk.json and controls post-processing steps executed after the initial export.

Injecting Gearbox Backlash into Exported Models

Many Microduck environments require simulation of mechanical play in gearboxes. The repository handles this through a post-export script rather than modifying the CAD model directly.

The add_backlash.py script, located at src/mjlab_microduck/robot/microduck/add_backlash.py, executes as the final post_import_command in the configuration JSON. It parses the MJCF, identifies every actuated joint with the class chosen_actuator, and inserts a passive hinge joint named passive_<joint>_backlash with a small range representing mechanical tolerances.

To apply backlash to an exported model:

python3 src/mjlab_microduck/robot/microduck/add_backlash.py \
    src/mjlab_microduck/robot/microduck/robot_allcollisions_backlash.xml \
    --backlash-deg 2.0

The default value of 2.0 degrees represents peak-to-peak play, creating physically realistic compliance without altering the original Onshape geometry.

Key Files in the Export Workflow

Understanding the file structure clarifies how the pipeline maintains synchronization between CAD and simulation:

• README.md – Documents the onshape-to-robot dependency and provides the converter repository link.
• src/mjlab_microduck/robot/microduck/config_mjcf_*.json – Stores Onshape URLs and defines post-import commands like add_backlash.py.
• src/mjlab_microduck/robot/microduck/*.xml – MJCF robot descriptions containing the generation comment and Onshape provenance.
• src/mjlab_microduck/robot/microduck/add_backlash.py – Python script that augments MJCF files with passive backlash joints.
• src/mjlab_microduck/tasks/*.py – RL task definitions that load the processed MJCF files into MuJoCo.

Summary

• Microduck robot models are exported from Onshape using the onshape-to-robot converter, producing MJCF XML files.
• Each export generates a companion JSON configuration file storing the Onshape URL and post-processing instructions.
• The add_backlash.py script optionally injects passive hinge joints to simulate gearbox backlash before the model enters the RL pipeline.
• Generated files contain XML comments linking back to the original Onshape document, ensuring full design traceability.

Frequently Asked Questions

What is the onshape-to-robot tool?

The onshape-to-robot tool is an open-source converter that extracts assembly trees, part geometries, and mate relations from Onshape CAD documents and serializes them into robotics formats like MJCF or URDF. In the microduck_rl repository, this tool generates the XML headers found in the robot description files.

How does the backlash injection modify the exported model?

The add_backlash.py script parses the MJCF file to locate actuated joints, then inserts additional passive hinge joints with small position limits immediately after each actuator. These passive joints introduce compliance that mimics real gearbox play without requiring changes to the original Onshape assembly or the base MJCF structure.

Where is the original Onshape document URL preserved?

The Onshape document URL is stored in the url field of the config_mjcf_*.json files located in src/mjlab_microduck/robot/microduck/. Additionally, the generated MJCF XML files contain HTML comments indicating the Onshape source document for immediate traceability when viewing the raw XML.

Can I export the Microduck model without adding backlash?

Yes. Backlash injection is optional and controlled by the post_import_command field in the configuration JSON. You can generate a clean MJCF export by omitting the add_backlash.py command from the JSON configuration or by running the onshape-to-robot tool directly without the post-processing step.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}