Appendix A: Connecting SolidWorks to URDF

A.1Overview of the pipeline: from assembly to RViz

A common mistake is to assume SolidWorks connects directly and live to ROS 2. It doesn't work that way. The real path is a multi-stage pipeline: you prepare a mechanical assembly in SolidWorks, an add-in (the Exporter) converts it into URDF and Mesh files, and then you place those files inside a normal ROS 2 package — exactly what you learned in Chapter 4 about the structure of ARCHO's body URDF.

The goal of this appendix is simply to get ARCHO's mechanical model into a URDF that ROS 2 can understand and to see it displayed correctly in RViz. Once the model looks right in RViz, we move on to Gazebo and ros2_control (Chapters 7 and 8) — not before.

A.2What exactly is URDF?

URDF stands for Unified Robot Description Format: a text-based XML file that tells ROS what parts the robot is made of, which part is connected to which, where the joints are, what the rotation or motion axis of each joint is, what the mass and center of mass of each part is, and what the visual appearance and physical collision shape of the parts look like.

For example, the Link tree of ARCHO — the same two-wheeled robot introduced in Chapter 1 — looks like this:

And every connection is defined by an independent Joint:

base_link
   ├── left_wheel_joint  → left_wheel_link
   ├── right_wheel_joint → right_wheel_link
   ├── lidar_joint       → lidar_link
   └── camera_joint      → camera_link

A.3The right way to think: from mechanism to Exporter tree

Before opening the Exporter, take a step back. SolidWorks tells you "this part is the chassis, this is the wheel, this is the bolt, this is the motor, this is the gearbox, this is the spring..." — that is, it sees the assembly in terms of part count. But ROS never asks "how many parts do you have?" ROS only has one question:

Step one: solve the mechanism on paper before touching the Exporter

Never go straight into the URDF Exporter. First ask yourself: what stays fixed? What rotates? What moves up and down? What moves as one unit with something else?

For example, consider a simple robot with a chassis, motor, gearbox, shaft, wheel, and camera. Suppose the motor and gearbox housing are bolted together, the gearbox output shaft rotates, the wheel is locked onto the shaft, and the camera is fixed to the body. From ROS's point of view, this is grouped as follows:

Chassis + Camera      → one Link (or Fixed Links)
Motor + Gearbox housing → one Link
Shaft + Wheel           → one Link

Why do the shaft and wheel become one Link? Because the shaft doesn't move relative to the wheel — both rotate together.

The Golden Rule of Links

For example, Wheel + Hub + Shaft, if all locked together, become one wheel_link. But Wheel and Gearbox Housing move relative to each other, so they cannot be one Link.

The Golden Rule of Joints

A Joint is not a physical part. wheel_joint, arm_joint, suspension_joint, and camera_joint are none of them parts in SolidWorks; a Joint only says "how does this Link move relative to that Link." For example:

gearbox_link
↓ wheel_joint
wheel_link

Meaning wheel_link rotates relative to gearbox_link.

Four joint types that cover 90% of projects

Why springs are confusing

A spring is not a rigid body — it shortens, lengthens, and deforms; but a standard URDF is built around rigid bodies. So you need to separate two things:

Conceptual tree versus the actual Exporter tree — a note that once caused a real error

Suppose you have a project with a body, a gearbox, and a wheel, and the actual motion is: body ↓suspension gearbox ↓rotation wheel. The conceptual URDF tree (just for understanding the system) looks like this:

base_link
└── suspension_joint
    └── gearbox_link
        └── wheel_joint
            └── wheel_link

❌ Wrong:
base_link
└── suspension_joint
    └── gearbox_link

✅ Correct:
base_link
└── gearbox_link

How does the Exporter understand the Parent/Child relationship?

Suppose you build this Tree in the Exporter:

base_link
└── gearbox_link
    └── wheel_link

When you click on gearbox_link, you write Link Name: gearbox_link and Joint Name: suspension_joint. From these two lines alone, the Exporter understands Parent = base_link, Child = gearbox_link, Joint = suspension_joint. You repeat the same thing on wheel_link with Joint Name: wheel_joint and Joint Type: Continuous so the Exporter understands gearbox_link ↓wheel_joint wheel_link.

What does a Component mean?

Every Link needs to know which SolidWorks parts belong to it. For example, gearbox_link might contain Gearbox_Housing.SLDPRT, Motor_Housing.SLDPRT, and Motor_Bracket.SLDPRT — since these three parts don't move relative to each other, you assign them all to the same Link. Likewise, for wheel_link you might assign Wheel.SLDPRT, Hub.SLDPRT, and Output_Shaft.SLDPRT.

The root Link and naming rules

Every URDF must have exactly one root — usually base_link — meaning everything eventually connects to it:

base_link
├── left_wheel_link
├── right_wheel_link
├── lidar_link
├── camera_link
└── arm_link

Establish a consistent naming convention from the start — it's not mandatory, but it's extremely useful:

Link  → ends in _link   (base_link, left_wheel_link, gearbox_link, camera_link, lidar_link)
Joint → ends in _joint  (left_wheel_joint, camera_joint, suspension_joint)

And don't reuse names — no two Links with the same name, no two Joints with the same name. The only exception is base_link itself, which, being the Root, has no Joint at all (its Joint Name stays empty); every other Link must have a Joint Name.

The Joint axis and Coordinate System

If a Joint is movable, ROS needs to know which axis it moves around: 1 0 0 for X, 0 1 0 for Y, 0 0 1 for Z. If a wheel shaft runs along Y, axis = 0 1 0 — but never assume out of habit that "a wheel is always the Y axis"; you must look at the actual model. As mentioned in the coordinate system section of this appendix, ROS prefers X = Forward, Y = Left, Z = Up, so before exporting, build a ROS_Coordinate_System in SolidWorks and put the origin somewhere logical, such as the center of the chassis or the center of the wheel axis.

Full example: from mechanism to the final Exporter tree

Suppose you have a new project with a Body, Motor, Gearbox, Output Shaft, Wheel, and Camera. The actual motion is: the Body is fixed relative to the Motor+Gearbox, the Motor/Gearbox rotates relative to the Output Shaft+Wheel, and the Body is fixed relative to the Camera. So the Links become:

base_link
gearbox_link
wheel_link
camera_link

And the actual tree inside the SolidWorks Exporter:

base_link
├── gearbox_link
│   └── wheel_link
└── camera_link

With the following settings on each Child Link:

gearbox_link → Joint Name: gearbox_mount_joint  | Joint Type: Fixed
wheel_link   → Joint Name: wheel_joint          | Joint Type: Continuous
camera_link  → Joint Name: camera_joint         | Joint Type: Fixed

Checklist before clicking Preview and Export

And the overall thought process for every new project should follow this same path:

CAD parts
↓
Which parts move together?
↓
Rigid Body Groups
↓
Links
↓
Motion between Links
↓
Joints
↓
Conceptual URDF Tree
↓
SolidWorks Tree = Links Only
↓
Assign Components
↓
Configure Joint on Child Link
↓
Preview
↓
Export URDF
↓
ROS 2 validation

This is exactly the logic we apply, step by step, on the real ARCHO example, throughout the rest of this appendix.

A.4Preparing the SolidWorks assembly

This is the most important part of the whole job. Most URDF problems don't come from the Exporter itself; they come from a messy SolidWorks assembly.

Suppose ARCHO's chassis assembly has these parts: chassis, cover, battery, electronics board, brackets, left wheel, right wheel, caster wheel, LiDAR, and camera. Since the chassis, cover, battery, board, and brackets never move relative to each other, they all become part of a single Link:

base_link
├── chassis
├── cover
├── battery
├── electronics
└── brackets

But the wheels and sensors need independent Links:

left_wheel_link
right_wheel_link
caster_link
lidar_link
camera_link

The suggested assembly structure in SolidWorks looks roughly like this:

archo_assembly.SLDASM
│
├── base_subassembly.SLDASM
│   ├── chassis.SLDPRT
│   ├── top_cover.SLDPRT
│   ├── battery.SLDPRT
│   ├── motor_mount_left.SLDPRT
│   └── motor_mount_right.SLDPRT
│
├── left_wheel.SLDPRT
├── right_wheel.SLDPRT
├── caster.SLDPRT
├── lidar.SLDPRT
└── camera.SLDPRT

Fixing the chassis, floating the wheels

In SolidWorks, the main chassis must be Fixed. Right-click the chassis in the FeatureManager and select:

Right Click → Fix

You should see an (f) marker next to the chassis, e.g. (f) base_chassis. The wheels must not be Fixed — if they are, right-click them and select Float. The correct structure looks like this:

(f) base_chassis
(-) left_wheel
(-) right_wheel
(-) caster

Proper Mates for each wheel

The Exporter uses the assembly structure, Mates, and your selections to build the Joints. Every wheel needs at least these two Mates:

• Concentric Mate — aligns the wheel axis with the motor or shaft axis: Mate → Concentric
• Coincident or Distance Mate — sets the wheel's lateral position: Mate → Coincident or Mate → Distance

A.5The ROS coordinate system and Coordinate System

ROS uses a standard coordinate convention: X forward, Y left, Z up.

Top view:
             +X
         front of robot
              ↑
              |
 +Y  ←  [ ARCHO ]  →  -Y
              |
              ↓
             -X

Side view:
       +Z
        ↑
        |
        |
        └────→ +X

If your SolidWorks model's coordinate system doesn't match this convention, ARCHO may appear lying down, upside down, or facing the wrong direction in RViz, or the wheels may rotate about the wrong axis.

To fix this at the root, build a dedicated coordinate system in SolidWorks:

Insert
→ Reference Geometry
→ Coordinate System

Name it, for example, ROS_Coordinate_System and set the axes like this:

X = Forward
Y = Left
Z = Up

Preferably place the origin at one of these points: the geometric center of the chassis, the midpoint between the two wheel axes, on the ground plane below the robot's center, or the center of the base plate.

In a real assembly, you typically repeat this not just once, but for every Link and every Joint separately — a Coordinate System for the chassis, one for each wheel, one for each Caster. The result ends up looking like this: dozens of small Triads, each sitting exactly where a Joint will later be located:

A.6Material, mass, and inertia

A URDF isn't just a 3D picture; for physical simulation it also needs dynamic properties. SolidWorks can compute mass, center of mass, moments of inertia, and the inertia tensor from each part's Material and geometry.

For every part or Subassembly, define a real Material:

Right Click on Material
→ Edit Material

For example Aluminum 6061, ABS, Steel, or Rubber — whichever is closest to the real part. Then check:

Evaluate
→ Mass Properties

You should see sensible numbers for Mass, Center of Mass, Principal Axes, and Moments of Inertia. The Exporter can transfer this information directly into the <inertial> tag in URDF.

The Configure Link Properties page — where mass becomes a number

After you've defined all the Joints, the Exporter shows you one more page: Configure Link Properties. This is no longer about motion; it's about how heavy each Link is, where its mass is concentrated, and what color we see it in.

This page has two main sections; let's go through each one separately.

Top section: Inertial — the same thing we discussed a few lines ago

If you've defined the Material correctly, the Exporter pulls these numbers straight from the CAD — you no longer need to guess:

These six numbers together form the Link's inertia matrix and go directly into the <inertial> tag in URDF — the same tag we'll see again a few lines later in the full sample URDF.

Bottom section: Visual and Collision Meshes

A.7Installing the SolidWorks URDF Exporter

The classic, well-known tool is the SolidWorks to URDF Exporter project from the ROS organization. This tool converts a SolidWorks assembly into URDF, Mesh files, and the initial structure of a ROS package.

After installing the Exporter:

1. Open SolidWorks.
2. Go to Tools → Add-Ins.
3. Find the SolidWorks to URDF Exporter option.
4. Enable both the Active Add-ins and Start Up checkboxes.

After this step, the Export command should appear at the bottom of the Tools menu: Tools → Export as URDF.

A.8Defining Links, Joints, and axes

Open ARCHO's main assembly and go to Tools → Export as URDF. A URDF Exporter window opens with an empty tree on the left — the place where Links will appear one by one. To know where you're headed, first look at a real example of a completed tree:

When you expand each row of this tree, the Exporter shows you two small buttons: one for adding a new child Link, and one for defining Components (which SolidWorks parts belong inside this Link). We now go through this process step by step for ARCHO.

Base Link

The first Link must be the robot's base part: base_link. Select all the fixed chassis parts for it — the body, cover, fixed brackets, battery, computer, electronics boards, and any motors that have a fixed housing.

In the Exporter, enter the Link name precisely and without spaces; use only lowercase English letters, digits, and underscores:

Left and right wheels

Create a Child Link for base_link named left_wheel_link and set:

Parent Link: base_link
Child Link: left_wheel_link
Joint Name: left_wheel_joint

You have two common choices for the Joint type:

For ARCHO's wheel, select Joint Type: Continuous.

Define the right wheel exactly like the left one:

Parent Link: base_link
Child Link: right_wheel_link
Joint Name: right_wheel_joint
Joint Type: continuous
Axis: 0 1 0

The tree so far looks like this:

base_link
├── left_wheel_joint
│   └── left_wheel_link
└── right_wheel_joint
    └── right_wheel_link

What's going on inside the Configure Joint Properties page?

When you double-click a Joint in the tree, the Exporter takes you to a more detailed page — where you actually define exactly where this joint is, which axis it moves around, and how much power it has. The first time you see this page it can look a bit crowded, but each section answers one simple question:

Let's read this page like a map, section by section:

Sensors — LiDAR and camera

If the LiDAR is bolted to the body and doesn't move, you have two options. The first is to keep the LiDAR model inside the chassis Mesh — simple, but you won't have an independent TF frame for the LiDAR later. The second, more professional option is to create an independent Link with a Fixed Joint:

Parent: base_link
Child: lidar_link
Joint: lidar_joint
Type: fixed

Which looks like this in URDF:

<joint name="lidar_joint" type="fixed">
  <parent link="base_link"/>
  <child link="lidar_link"/>
  <origin xyz="0.25 0 0.35" rpy="0 0 0"/>
</joint>

Do the same for the camera: camera_link, camera_joint, type fixed. The final Link tree:

base_link
├── left_wheel_link
├── right_wheel_link
├── caster_link
├── lidar_link
└── camera_link

Caster Wheel

For initial testing, the simplest and most stable choice is to connect the Caster with a Fixed Joint (caster_joint, type="fixed"). The fully physical model — with two independent motions, caster_swivel_joint and caster_wheel_joint — is more complex in Gazebo and sometimes unstable, so we save it for later.

A.9Collision versus Visual

Every Link usually has two separate geometry models: Visual, which the user sees, and Collision, which the physics engine uses for collisions. Visual can be detailed and beautiful; Collision is better kept simple.

For example, the chassis Visual can be a complex STL:

<visual>
  <geometry>
    <mesh filename="package://archo_description/meshes/base_link.stl"/>
  </geometry>
</visual>

But the Collision is better as a simple shape like a Box:

<collision>
  <geometry>
    <box size="0.60 0.45 0.20"/>
  </geometry>
</collision>

The same logic applies to Mesh quality; very high quality increases file size and slows down RViz and Gazebo. For ARCHO, a medium- or good-quality Visual Mesh and a simple or simplified Collision shape is enough.

A.10Exporting and transferring files to WSL

Pick a simple path on Windows and avoid spaces, non-English characters, or special characters in the path:

Then run Export. The output typically looks like this:

archo_description/
├── CMakeLists.txt
├── package.xml
├── launch/
├── meshes/
│   ├── base_link.STL
│   ├── left_wheel_link.STL
│   ├── right_wheel_link.STL
│   ├── lidar_link.STL
│   └── camera_link.STL
├── textures/
└── urdf/
    └── archo.urdf

Transferring from Windows to WSL

If your Workspace is ~/ros2_ws and the Windows output is at C:\ros_exports\archo_description, in WSL this path corresponds to /mnt/c/ros_exports/archo_description.

Fixing the STL filenames

Linux is case-sensitive; base_link.STL and base_link.stl are two completely different files. It's best to lowercase all Meshes:

Then also fix the names inside the URDF from base_link.STL to base_link.stl.

A.11Building the ROS 2 package

CMakeLists.txt

cmake_minimum_required(VERSION 3.8)
project(archo_description)

find_package(ament_cmake REQUIRED)

install(
  DIRECTORY
    launch
    meshes
    urdf
  DESTINATION share/${PROJECT_NAME}
)

ament_package()

package.xml

<?xml version="1.0"?>
<package format="3">
  <name>archo_description</name>
  <version>0.0.1</version>

  <description>
    URDF description package for the ARCHO mobile robot.
  </description>

  <maintainer email="pouya@example.com">
    Pouya Mansournia
  </maintainer>

  <license>Apache-2.0</license>

  <buildtool_depend>ament_cmake</buildtool_depend>

  <exec_depend>robot_state_publisher</exec_depend>
  <exec_depend>joint_state_publisher</exec_depend>
  <exec_depend>joint_state_publisher_gui</exec_depend>
  <exec_depend>rviz2</exec_depend>
  <exec_depend>xacro</exec_depend>

  <export>
    <build_type>ament_cmake</build_type>
  </export>
</package>

Launch File for RViz

from pathlib import Path

from ament_index_python.packages import get_package_share_directory
from launch import LaunchDescription
from launch_ros.actions import Node


def generate_launch_description() -> LaunchDescription:
    package_name = "archo_description"
    urdf_file_name = "archo.urdf"

    package_share = Path(get_package_share_directory(package_name))
    urdf_path = package_share / "urdf" / urdf_file_name

    if not urdf_path.exists():
        raise FileNotFoundError(f"URDF file not found: {urdf_path}")

    robot_description = urdf_path.read_text(encoding="utf-8")

    return LaunchDescription(
        [
            Node(
                package="robot_state_publisher",
                executable="robot_state_publisher",
                name="robot_state_publisher",
                output="screen",
                parameters=[{"robot_description": robot_description}],
            ),
            Node(
                package="joint_state_publisher_gui",
                executable="joint_state_publisher_gui",
                name="joint_state_publisher_gui",
                output="screen",
            ),
            Node(
                package="rviz2",
                executable="rviz2",
                name="rviz2",
                output="screen",
            ),
        ]
    )

The official ROS 2 documentation uses robot_state_publisher to display a URDF; this Node converts the URDF model and Joint states into TF so tools like RViz can show the robot's structure.

Build

A.12Testing in RViz and checking TF

After this quick check, it's time for a more serious review. First check the URDF file before anything else:

Then run:

In RViz: set Fixed Frame to base_link, click Add, and add both the RobotModel and TF displays. If the model is correct, the chassis and wheels appear, the TF tree is complete, and the Joints can be changed using the Joint State Publisher.

If the model isn't visible but there's no error either, check these Topics:

The last command produces a frames.pdf file after a few seconds, which can be opened in Windows from WSL with explorer.exe frames.pdf, and it should show ARCHO's same five-branch tree.

A.13Common errors and how to fix them

A.14Full sample URDF

This sample is only for understanding the structure — the inertias and dimensions (chassis size, wheel radius) are illustrative, do not match the values from Chapter 4, and should not be used directly for the real ARCHO; before use, replace every number with your own robot's actual dimensions:

<?xml version="1.0"?>
<robot name="archo">

  <link name="base_link">
    <visual>
      <geometry>
        <mesh filename="package://archo_description/meshes/base_link.stl"/>
      </geometry>
    </visual>

    <collision>
      <geometry>
        <box size="0.60 0.45 0.20"/>
      </geometry>
    </collision>

    <inertial>
      <origin xyz="0 0 0"/>
      <mass value="20.0"/>
      <inertia
        ixx="0.40" ixy="0.0" ixz="0.0"
        iyy="0.65" iyz="0.0"
        izz="0.80"/>
    </inertial>
  </link>

  <link name="left_wheel_link">
    <visual>
      <geometry>
        <mesh filename="package://archo_description/meshes/left_wheel_link.stl"/>
      </geometry>
    </visual>

    <collision>
      <geometry>
        <cylinder radius="0.10" length="0.04"/>
      </geometry>
    </collision>

    <inertial>
      <mass value="0.8"/>
      <inertia
        ixx="0.004" ixy="0.0" ixz="0.0"
        iyy="0.004" iyz="0.0"
        izz="0.007"/>
    </inertial>
  </link>

  <joint name="left_wheel_joint" type="continuous">
    <parent link="base_link"/>
    <child link="left_wheel_link"/>
    <origin xyz="0 0.245 -0.10" rpy="0 0 0"/>
    <axis xyz="0 1 0"/>
  </joint>

  <link name="right_wheel_link">
    <visual>
      <geometry>
        <mesh filename="package://archo_description/meshes/right_wheel_link.stl"/>
      </geometry>
    </visual>

    <collision>
      <geometry>
        <cylinder radius="0.10" length="0.04"/>
      </geometry>
    </collision>

    <inertial>
      <mass value="0.8"/>
      <inertia
        ixx="0.004" ixy="0.0" ixz="0.0"
        iyy="0.004" iyz="0.0"
        izz="0.007"/>
    </inertial>
  </link>

  <joint name="right_wheel_joint" type="continuous">
    <parent link="base_link"/>
    <child link="right_wheel_link"/>
    <origin xyz="0 -0.245 -0.10" rpy="0 0 0"/>
    <axis xyz="0 1 0"/>
  </joint>

</robot>

A.15Summary, checklist, and exercise

Exporting from SolidWorks isn't the end of the job; it's a starting point. After exporting, these refinements are usually needed: fixing up Link and Joint names, converting URDF to Xacro (Chapter 4), simplifying Collisions, rechecking Inertia, adding base_footprint, adding Sensor Frames, adding ros2_control (Chapter 8), adding Gazebo plugins (Chapter 7), defining wheel radius and spacing, and a full test in RViz and then Gazebo before connecting to the real controller.

Glossary

URDF

Unified Robot Description Format — the XML file that describes a robot's mechanical structure for ROS.

Link

An independent rigid body in the URDF tree.

Joint

The connection between two Links that defines their relative motion type and axis.

Continuous Joint

A joint that rotates with no angular limit — suited to drive wheels.

Revolute Joint

A joint that only moves within a specific angular range.

Prismatic Joint

A joint that moves linearly instead of rotating — like a rail, jack, or lift.

Fixed Joint

A connection with no relative motion at all — used for sensors like LiDAR and cameras.

Mimic Joint

A state where one Joint's motion is computed directly from another Joint — like two fingers of a Gripper.

Visual

The geometry the user sees in RViz/Gazebo; can be detailed and complex.

Collision

The geometry the physics engine uses to compute collisions; should be simple.

Inertial

The URDF tag that defines each Link's mass, center of mass, and inertia tensor.

base_footprint

An auxiliary Link that sits on the ground plane, separate from base_link (which sits at the physical center of the chassis).

package://

The standard ROS path prefix for referencing files inside a package, such as Meshes.