# Introduction to URDF¶

In this exercise, we will explore how to describe a robot in the URDF format.

## Motivation¶

Many of the coolest and most useful capabilities of ROS and its community involve things like collision checking and dynamic path planning. It’s frequently useful to have a code-independent, human-readable way to describe the geometry of robots and their cells. Think of it like a textual CAD description: “part-one is 1 meter left of part-two and has the following triangle-mesh for display purposes.” The Unified Robot Description Format (URDF) is the most popular of these formats today. This module will walk you through creating a simple robot cell that we’ll expand upon and use for practical purposes later.

## Reference Example¶

Building a Visual Robot Model with URDF from Scratch

## Scan-N-Plan Application: Problem Statement¶

We have the software skeleton of our Scan-N-Plan application, so let’s take the next step and add some physical context. The geometry we describe in this exercise will be used to:

1. Perform collision checking

2. Understand robot kinematics

3. Perform transformation math Your goal is to describe a workcell that features:

4. An origin frame called `world`

5. A separate frame with “table” geometry (a flat rectangular prism)

6. A frame (geometry optional) called `camera_frame` that is oriented such that its Z axis is flipped relative to the Z axis of `world`

## Scan-N-Plan Application: Guidance¶

Note: If you have not completed the previous tutorials, copy myworkcell_core and myworkcell_support packages from ~/industrial-training/exercises/2.3/ros2/src and git clone https://github.com/ros-industrial/fake_ar_publisher.git into your current workspace src folder.

1. It’s customary to put describing files that aren’t code into their own “support” package. URDFs typically go into their own subfolder ‘’urdf/’’. See the abb_irb2400_support package. Add a `urdf` sub-folder to your application support package.

2. Create a new `workcell.urdf` file inside the `myworkcell_support/urdf/` folder and insert the following XML skeleton:

```<?xml version="1.0" ?>
<robot name="myworkcell" xmlns:xacro="http://ros.org/wiki/xacro">
</robot>
```
3. Add the required links. See the irb2400_macro.xacro example from an ABB2400. Remember that all URDF tags must be placed between the `<robot> ... </robot>` tags.

1. Add the `world` frame as a “virtual link” (no geometry).

```<link name="world"/>
```
2. Add the `table` frame, and be sure to specify both collision & visual geometry tags. See the `box` type in the XML specification.

```<link name="table">
<visual>
<geometry>
<box size="1.0 1.0 0.05"/>
</geometry>
</visual>
<collision>
<geometry>
<box size="1.0 1.0 0.05"/>
</geometry>
</collision>
```
3. Add the `camera_frame` frame as another virtual link (no geometry).

```<link name="camera_frame"/>
```
4. Connect your links with a pair of fixed joints Use an `rpy` tag in the `world_to_camera` joint to set its orientation as described in the introduction.

```<joint name="world_to_table" type="fixed">
<origin xyz="0 0 0.5" rpy="0 0 0"/>
</joint>

<joint name="world_to_camera" type="fixed">
<origin xyz="-0.25 -0.5 1.25" rpy="0 3.14159 0"/>
</joint>
```
4. Add the urdf folder to the installation rule in your `CMakeLists.txt` so it gets installed where the launch file expects it to be.

```install(DIRECTORY launch urdf DESTINATION share/\${PROJECT_NAME}/)
```
5. It helps to visualize your URDF as you add links, to verify things look as expected. Run a node that publishes the robot state based on your URDF.

```ros2 run robot_state_publisher robot_state_publisher --ros-args -p robot_description:="`cat ~/ros2_ws/src/myworkcell_support/urdf/workcell.urdf`"
```

Note the syntax used to specify a starting parameter value to the node (`--ros-args -p param_name:=param_value`). Also the use of `cat file.urdf` to pass the file contents as a string.

Now run the visualization tool Rviz in a separate terminal.

```rviz2
```
6. The default RViz setup only shows a minimal amount of info. You can add various Display elements to customize the display to show exactly what is needed. Inside RViz add a RobotModel display and a TF display using the button in the lower left. Expand the settings for the added RobotModel display and select `/robot_description` for the field labeled Description Topic. Also make sure in the Global Options that Fixed Frame is set to `world`. Consider saving this configuration (File -> Save Config) to the default RViz config file, so you don’t need to repeat these setup steps again later.

## Challenge Exercise¶

• Try adding legs to the table. How does this affect the collision geometry?