No More Manual URDFs! Automate Robot Modeling with Onshape-to-Robot

Introduction

Creating accurate and functional URDF (Unified Robot Description Format) files is crucial for simulating and controlling robots in ROS (Robot Operating System). However, manually writing URDF files can be tedious and error-prone, especially for complex robotic systems.

Onshape-to-Robot is a powerful tool that automates URDF generation from Onshape CAD models, significantly simplifying the process. This article provides a detailed guide on using Onshape-to-Robot to convert your Onshape designs into URDF files efficiently.

For demonstration, we will be using a simple assembly from Onshape below, You can access the final design here

Prerequisites

Before proceeding, ensure you have the following:

1. An Onshape Account (Sign up here)

2. A Robot Model in Onshape (assembled with proper joints and rigid bodies)

3. Python 3.7+ installed

4. Pybullet (Optional) (pip install pybullet) if you need to quickly simulate your robot

Step 1: Install Onshape-to-Robot

The first step is to install the onshape-to-robot on your PC. Open a terminal and run:

pip install onshape-to-robot

Step 2: Prepare Your Onshape Model

For a successful URDF conversion, your Onshape assembly must be structured correctly:

• Rigid Bodies: Each link (e.g., a robot arm segment) should be a separate part or subassembly.

• Joints: Use Onshape’s mates (e.g., revolute, slider, fixed) to define kinematic relationships.

• Coordinate Systems: Ensure proper alignment of axes to match ROS conventions (Z-up).

• Naming Convention, each of your joints in the Assembly Mate_features should start with dof_ i.e for your robot arm joint, the name would be dof_robot_arm

Step 3: Configure Onshape-to-Robot API Credentials and Configs

Create a folder, i.e robot_car , in the folder, create two files config.json and .env to specify your Onshape configuration and API key, API Secret and Onshape API, respectively:

in your config.json file; paste the content below and edit to your require

{
    "url": "your onshape document url", 
    "output_format": "urdf" // supports other formats, mjcf, sdf and others
}

in your .env Paste the content below:

ONSHAPE_API=https://cad.onshape.com
ONSHAPE_ACCESS_KEY="Your Onshape access key"
ONSHAPE_SECRET_KEY="Your Onshape secret key"

Note: You can get your keys from https://dev-portal.onshape.com/keys

Step 4: Generate the URDF File

Run the conversion command:

# you can replace "my_robot" with the name of the folder where you have your config file
onshape-to-robot .

The output will be similar to below, and new files (robot.urdf) and folders assets will be added to your original folder.

Step 5: Verify and Optimize the URDF

Check URDF Validity

Use check_urdf (from urdfdom-tools):

sudo apt install urdfdom-tools
check_urdf robot.urdf

If errors appear, adjust mates in Onshape or modify the config file. Also, ensure all parts in the assembly have a material property.

Conclusion

Onshape-to-Robot is an excellent tool for automating URDF generation, saving time and reducing errors. By following this guide, you can efficiently convert Onshape models and Assembly into ROS-compatible URDF files for simulation and control.

Next Steps

• We will integrate the URDF into Gazebo or PyBullet

• Develop ROS controllers for your robot

• Optimize dynamics for realistic simulations

For more details, check the official documentation.

Happy robotics development! 🚀