What we are going to learn

1. Learn how to export a robot model from OnShape to URDF so that we can integrate it with ROS2

List of resources used in this post

1. Use this rosject: https://app.theconstructsim.com/l/5ee7cc96/
2. The Construct: https://app.theconstructsim.com/
3. ROS2 Courses –▸
   1. URDF for Robot Modeling in ROS2: https://app.theconstructsim.com/courses/83/
   2. ROS2 Basics in 5 Days (Python): https://app.theconstructsim.com/Course/132
   3. ROS2 Basics in 5 Days (C++): https://app.theconstructsim.com/Course/133
4. OnShape: https://www.onshape.com/en/

Do you want to master robotics? Robotics Developer Master Class: https://www.theconstruct.ai/robotics-developer/

Overview

ROS2 (Robot Operating System version 2) is widely used in robotics, and it uses robot models in a format called URDF (Unified Robotics Description Format).

OnShape is a 3D CAD (3-dimensional computer-aided design) tool that allows anyone to easily create 3D models using only a Web Browser.

In this post, we are going to learn how to export models from OnShape to URDF, so that the model can be used in ROS2 programs.

ROS Inside!

ROS Inside

Before anything else, if you want to use the logo above on your own robot or computer, feel free to download it, print it, and attach it to your robot. It is really free. Find it in the link below:

ROS Inside logo

Creating an OnShape account

Alright, since we are going to export a model from OnShape, the first thing that you need is an OnShape account.

Feel free to create an account at: https://www.onshape.com/en/

On OnShape you can create your own design, or use any existing design already provided by OnShape.

In order to follow this tutorial, we need to have ROS2 installed in our system, and ideally a ros2_ws (ROS2 Workspace). To make your life easier, we have already prepared a rosject for that: https://app.theconstructsim.com/l/5ee7cc96/.

Just by copying the rosject (clicking the link above), you will have a setup already prepared for you.

After the rosject has been successfully copied to your own area, you should see a Run button. Just click that button to launch the rosject (below you have a rosject example).

How to Export a 3D Robot Model to ROS2 | Onshape CAD to URDF – Run rosject (example of the RUN button)

After pressing the Run button, you should have the rosject loaded. Now, let’s head to the next section to get some real practice.

Installing the onshape-to-robot package

In order to install a package (and interact with ROS2), we need a terminal.

Let’s open a terminal by clicking the Open a new terminal button.

 

Open a new Terminal

 

In order to install onshape-to-robot, please run the following command in the terminal:

sudo pip install onshape-to-robot

the following output should be produced:

cd

python -m venv onshape_venv

Then, “enable” the virtual env:

source onshape_venv/bin/activate

Now you can install onshape-to-robot in this virtual environment:

pip install onshape-to-robot

Install dependencies

To make the export from OnShape to URDF work, we also need to add openscad and meshlab. We can instal theml with the following commands:

sudo add-apt-repository ppa:openscad/releases

sudo apt-get update

sudo apt-get install openscad -y

sudo apt-get install meshlab -y

Add the OnShapeKeys to the `keys. sh` file

After installing the dependencies, the next step is to get the API keys from OnShape.

The reason why we need this is because the onshape-to-robot needs to authenticate to OnShape to have access to the model that we are going to export.

In order to get those keys, you have to go to https://dev-portal.onshape.com/keys  and click on the Create new API key button.

After clicking that button, for the purpose of this video, you can just select all the permissions, and then click Create API key.

Then you will be presented with the keys, something similar to what we have below:

How to Export a 3D Robot Model to ROS2 – Onshape CAD to URDF

Make sure you copy that information in a safe place because the Secret Key won’t be shown again once you click the Close button.

Now, let’s create a keys.sh file with these secrets:

mkdir -pv ~/ros2_ws
cd ~/ros2_ws
touch keys.sh

Then you can open that file and paste the following content to it (these are the keys that we just created):

export ONSHAPE_API=https://cad.onshape.com
export ONSHAPE_ACCESS_KEY=5D7TA69e4CiVC82sOFTXJRWM
export ONSHAPE_SECRET_KEY=2uA7a5DHwNFrsHAA9IliZIIwD2Wxud0LhxOms55kLiQHeYl5

You could have created that file also using the Code Editor.

It is worth mentioning that if you want to use the Code Editor, also known as IDE (Integrated Development Environment), you just have to open it as indicated in the image below:

Open the IDE – Code Editor

 

Now, let’s source that file so that the ONSHAPE variables are available in our terminal:

cd ~/ros2_ws
source keys.sh

Now we should be able to see those environment variables:

echo $ONSHAPE_API 

echo $ONSHAPE_ACCESS_KEY 

echo $ONSHAPE_SECRET_KEY

Creating a ROS2 package where our URDF will be exported to

If you are using the rosject that we shared at the beginning of this post, the ROS2 package is already created.

We are going to write here the steps for creating the package, just in case you want to do the project from scratch yourself.

This is how the package was created. We first enter the src folder of the ros2_ws (ROS2 Workspace):.

cd ~/ros2_ws/src

Then we created a packaged named quadruped_description that depends on urdf and xacro packages:

ros2 pkg create --build-type ament_cmake quadruped_description --dependencies urdf xacro

Then we entered into the quadruped_description folder, and created some other useful folders there. The folders we are going to create are quadruped, rviz and launch:

cd quadruped_description

Let’s first create the quadruped folder:

mkdir quadruped

Now let’s create a config.json file inside that folder. That file will be used by the onshape-to-robot tool:

touch quadruped/config.json

And create the launch and rviz folders:

mkdir launch rviz

Now let’s open that quadruped/config.json file using the Code Editor and paste the following content to it:

{
  "documentId": "33b91de06ddc91b068fcf725",
  "outputFormat": "urdf",
  "packageName": "quadruped_description/quadruped",
  "robotName": "quadruped_robot",
  "assemblyName": "quadruped_v1"
}

This is the minimal information we need to make this export work.

The first field, documentId is the ID of the file that you have created. This is the ID that was used when creating this video. For your own projects, you are going to have a different ID. This ID appears in the URL of your project, as we can see below:

OnShape Document ID – ROS2

Alright, let me put here again the content of the config.json file to be better fo understand it:

{
"documentId": "33b91de06ddc91b068fcf725",
"outputFormat": "urdf",
"packageName": "quadruped_description/quadruped",
"robotName": "quadruped_robot",
"assemblyName": "quadruped_v1"
}

The packageName points to the folder that we created, where the config.json file is located, and it is the place where our files will be exported.

The robotName defines the name of the robot that will be exported.

The assemblyName is the name of our model on OnShape. In the previous image, in the bottom part of the image you can see on the 6th tab our model name: quadruped_v1

Prepare our CMakeLists.txt to export the folders we just created

The next thing we need is to modify our ~/ros2_ws/src/quadruped_description/CMakeLists.txt file so that the folders that we just created can be “installed” when we build our package.

The final content of that quadruped_description/CMakeLists.txt file is:

cmake_minimum_required(VERSION 3.8)
project(quadruped_description)

if(CMAKE_COMPILER_IS_GNUCXX OR CMAKE_CXX_COMPILER_ID MATCHES "Clang")
  add_compile_options(-Wall -Wextra -Wpedantic)
endif()

# find dependencies
find_package(ament_cmake REQUIRED)
find_package(urdf REQUIRED)
find_package(xacro REQUIRED)

if(BUILD_TESTING)
  find_package(ament_lint_auto REQUIRED)
  ament_lint_auto_find_test_dependencies()
endif()

install(
  DIRECTORY
    rviz
    launch
        quadruped
  DESTINATION
    share/${PROJECT_NAME}/
)

ament_package()

Finally, run onshape-to-robot command

Ok, now the time has come to finally run the command that converts our model from OnShape to URDF.

For that, let’s first enter to the right folder:

cd ~/ros2_ws/src/quadruped_description

Then, let’s run the following command (bear in mind that in this rosject we already ran that command. We are putting the commands here basically for documentation reasons):

onshape-to-robot quadruped

In the command above, we are essentially running onshare-to-command and telling it to go to the quadruped folder and read the config.json file there.

If everything goes well, now, instead of only the config.json file, we should have many files in that quadruped folder.

In that quadruped folder you should also find a robot.urdf file.

The only modification that you need to do on that file is to add the following content in the first line, so that the Code Editor can properly highlight the syntax:

<?xml version="1.0"?>

Creating .launch and .rviz files to be able to see our model in RViz.

Again, these commands were already executed when we first created the rosject that we shared with you at the beginning of this post.

These are the commands we used to create the launch files:

cd ~/ros2_ws/src/quadruped_description

touch launch/quadruped.launch.py

touch launch/start_rviz.launch.py

touch rviz/quadruped.rviz

To see the content of those files, just open them using the Code Editor.

Seeing our robot with ROS2

To see our robot model in ROS2, we first need to build our workspace:

cd ~/ros2_ws/

source install/setup.bash

build the workspace:

colcon build --packages-select quadruped_description

Source setup.bash so that ROS2 knows how to find our package:

source install/setup.bash

Now, let’s launch quadruped.launch.py :

cd ~/ros2_ws/

source install/setup.bash

ros2 launch quadruped_description quadruped.launch.py

Now in a second terminal, let’s run RViz:

cd ~/ros2_ws/

source install/setup.bash

ros2 launch quadruped_description start_rviz.launch.py

After launching RViz, after waiting for a few seconds for RViz to show, you will see that the model is not well presented. We can’t see the joints properly.

Let’s publish Fake Joint States to see the model properly.

For that, let’s run the following commands in a third terminal:

cd ~/ros2_ws/

source install/setup.bash

ros2 run joint_state_publisher_gui joint_state_publisher_gui

If you go to the Graphical Tools again and click Joint State Publisher, you should be able to see the robot model properly:

Joint State Publisher – Export a 3D Robot Model to ROS2 – Onshape CAD to URDF

 

Congratulations. You have now learned how to export a 3D model from OnShape to URDF.

If you want to learn more about URDF, have a look at the course below:

• URDF for Robot Modeling in ROS2: https://app.theconstructsim.com/courses/83/

We hope this post was really helpful to you. If you want a live version of this post with more details, please check the video in the next section.

Youtube video

So this is the post for today. Remember that we have the live version of this post on YouTube. If you liked the content, please consider subscribing to our YouTube channel. We are publishing new content ~every day.

Keep pushing your ROS Learning.

Related Courses & Training

If you want to learn more about ROS and ROS2, we recommend the following courses:

• • ROS2 Basics in 5 Days Humble (Python): https://app.theconstructsim.com/Course/132
  • ROS2 Basics in 5 Days Humble (C++): https://app.theconstructsim.com/Course/133
  • Open-RMF / Fleet Management Training: https://www.theconstruct.ai/robot-fleet-management-ros2-open-rmf-training/

Get ROS2 Industrial Ready- Hands-On Training by The Construct cover.png