Adding a New Robot

sim create takes a robot from OnShape and produces two ready-to-build ROS 2 packages - no manual URDF editing or package scaffolding required.

Via GitHub Actions (recommended)

You do not need any credentials or local setup. The Create new robot workflow runs on CI and opens a PR with the generated packages.

1. Go to Actions and then to Create new robot
2. Click Run workflow and fill in the inputs:
   • Mode: create
   • Robot name: unique, lowercase, no spaces (e.g. arm)
   • OnShape URL: the full document URL from OnShape
   • Fix robot to world: yes for stationary robots (arms, turrets), no for mobile
3. Wait for the workflow to finish, then review and merge the generated PR

Via Dev Container (developers only)

Running sim create locally requires your GitHub username to be listed in authorized_users.jsonc. If you’re not listed, ask a repo admin to add you. There are also some local package requirements:

note

The container mounts your ssh keys, as this method uses your GitHub ssh key. Make sure it is set up.

Host terminal

sim auth

Then you can create the robot using:

Inside devcontainer

sim create <robot_name> <onshape_url>

Tip

This sim will work with any Onshape API key and secret as long as you put them in the cli/onshape.env file under ONSHAPE_API_KEY and ONSHAPE_API_SECRET (in standard env format). The above is just for TrickFire specific robots.

Flags

Flag	Description
--attach-to-world	Fix base_link to the Gazebo world (stationary robots)
--no-attach-to-world	Explicitly skip - for mobile robots
--no-reduce	Skip STL mesh decimation (larger files, higher detail)
--output-dir <path>	Write packages somewhere other than robot-sim/

Updating an existing robot

When the OnShape CAD changes, pull in the new geometry without touching your bringup config.

Via CI (recommended): Actions → Create new robot → mode: update

Locally:

Inside devcontainer

sim update arm

This replaces only arm_description/urdf/arm.urdf and arm_description/meshes/. Everything else - your control xacro edits, launch file, controller YAML, RViz config - is left untouched.

Troubleshooting

Missing joints: Joints must be defined as mates in the OnShape assembly. Check the OnShape model if joints don’t appear in the generated controller YAML.

URDF errors after generation: See Robot Packages for details on what post-processing happens and how to inspect the raw OnShape output.

Large mesh files: sim create decimates STL triangle counts automatically. If meshes are still too large, simplify the geometry in OnShape before re-running.

sim auth fails with “no access”: Your GitHub username is not in authorized_users.jsonc, or it was added but CI hasn’t re-encrypted yet. Check the Re-encrypt Onshape credentials workflow run in Actions.