******
URDF
******

Introduction
================

This tutorial explains how one can describe the links and joints of a robot using URDF
(`http://wiki.ros.org/urdf <http://wiki.ros.org/urdf>`__). The description may then be
used to visualize and simulate the robot, it’s sensors and their properties.
**Use the Desktop P.C. for this Tutorial**.

-  Lines beginning with $ are terminal commands.

   -  To open a new terminal → use the shortcut ``Ctrl + Alt + T``.

   -  To open a new tab inside an existing terminal → use the shortcut ``Ctrl + Shift +T``.

   -  To kill a process in a terminal → use the shortcut ``Ctrl + C``.

-  Lines beginning with # indicate the syntax of the commands.

-  Code is separated in boxes.

-  Code is case sensitive.

Requirements
==============

We will need the additional package joint_state_publisher,
which is not yet available as binary in ROS2 Foxy. So
we will compile it from source:

.. code-block:: bash

   $ cd ~/robot_ws/src

   $ git clone -b ros2 https://github.com/ros/joint_state_publisher

   $ cd ..

   $ colcon build

   $ source ~/robot_ws/install/setup.bash

Also the package xacro is missing, which is necessary:

.. code-block:: bash

   $ sudo apt install ros-foxy-xacro


Create the Turtlebot3 model
=============================

The **U**\nified **R**\obot **D**\escription **F**\ormat is an XML based file format used
in ROS to describe the robot’s mechanical configuration and physical properties. URDF can
be used in RViz and Gazebo to visualize and simulate robots.

Create a new package **tb3_description** in your *robot_ws* workspace. inside
the package create a folder meshes and download the following CAD files in this
folder:

:download:`tb3_waffle_base </_resources/code/tutorials/misc/meshes/waffle_custom_base.stl>`
:download:`left_tire </_resources/code/tutorials/misc/meshes/left_tire.stl>`
:download:`right_tire </_resources/code/tutorials/misc/meshes/right_tire.stl>`
:download:`webcam </_resources/code/tutorials/misc/meshes/webcam.stl>`
:download:`laser </_resources/code/tutorials/misc/meshes/hokuyo.dae>`

These files will be used for the geometrical description of our robot model
to visualize the specific parts.

Create another folder *urdf* in this package and place here the
:download:`turtlebot3_waffle_base.urdf.xacro </_resources/code/tutorials/misc/turtlebot3_waffle_base.urdf.xacro>`
and :download:`common_properties.xacro </_resources/code/tutorials/misc/common_properties.xacro>`
files.

The *turtlebot3_waffle_base.urdf.xacro* is the main file wherein we will be building the
turtlebot3 model.

All definitions for the joints, links, plugins, etc. should be defined within
the outermost *<robot>* tags. Currently, the base or the chassis of the turtlebot3 includes a
*base_link* and it’s projection on the ground, referred to as *base_footprint*.

Xacros(`XML Macros <http://wiki.ros.org/xacro>`__) are commonly used to organize URDF files and
include among other things, constant values, macros and other xacro files. This file demonstrates
the use of one such xacro to include another file containing common constants.

The link tags may include the visual, collision and inertial properties of robot links.
The joint tags specify joint properties between various links. The gazebo tags are used to specify
additional details and features that are used for gazebo simulations.

.. hint::
   Make sure that the path to all mesh files matches your actual setup/packages.
   You can use this :download:`setup.py </_resources/code/tutorials/misc/urdf/setup.py>` file.

Create a file *wheel.urdf.xacro* in the urdf folder to describe the front wheels for the model:

.. literalinclude:: /_resources/code/tutorials/misc/wheel.urdf.xacro
   :language: xml
   :lines: 1-
   :caption: wheel.urdf.xacro

Now in order to include this file into the robot description, add the following line
as shown to *turtlebot3_waffle_base.urdf.xacro*.

.. code-block:: xml

    <!-- Turtlebot3 platform include files -->
    <xacro:include filename="$(find tb3_description)/urdf/wheel.urdf.xacro"/>  

Finally we use macros to replicate the code for each wheel with
**alignment** and **origin** values as the variables:

.. code-block:: xml

    <!-- Turtlebot3 wheel macros -->

    <xacro:turtlebot3_wheel alignment="left">
      <origin xyz="0.0 0.144 0.023" rpy="${-M_PI*0.5} 0 0"/>
    </xacro:turtlebot3_wheel>

    <xacro:turtlebot3_wheel alignment="right">
      <origin xyz="0.0 -0.144 0.023" rpy="${-M_PI*0.5} 0 0"/>
    </xacro:turtlebot3_wheel>

As you would have already noticed, the collision geometry of a link is generally a simplified
version of the visual element in order to reduce the computation load.

Similarly, add the casters to support the rear of the turtlebot via a *caster.urdf.xacro*:

.. literalinclude:: /_resources/code/tutorials/misc/caster.urdf.xacro
   :language: xml
   :lines: 1-
   :caption: caster.urdf.xacro

The corresponding include xacro:

.. code-block:: xml

    <!-- Turtlebot3 platform include files -->
    <xacro:include filename="$(find tb3_description)/urdf/caster.urdf.xacro"/>  

The macros for each caster with **alignment** and **origin** values as the variables:

.. code-block:: xml

    <!-- Turtlebot3 caster macros -->

    <xacro:turtlebot3_caster alignment="left">
      <origin xyz="-0.21 0.064 -0.004" rpy="0 0 0"/>
    </xacro:turtlebot3_caster>

    <xacro:turtlebot3_caster alignment="right">
      <origin xyz="-0.21 -0.064 -0.004" rpy="0 0 0"/>
    </xacro:turtlebot3_caster>

Using URDF to publish links
===============================

The **robot_state_publisher** package allows you to read the robot’s links and fixed joints
from the URDF and publishes the links as transforms. Additionally the the
**joint_state_publisher** subscribes to the topic */robot_description* for all non fixed joint
types. This topic is published by the **robot_state_publisher**. This can then be used
to visualize the robot in RViz as described in the urdf file.

Exercise
-----------

Create a launch file in the package **tb3_description** called *tb3_description.launch.py*.

.. literalinclude:: /_resources/code/tutorials/launch/tb3_description.launch.py
   :language: python
   :lines: 1-
   :caption: tb3_description.launch.py

Now launch the file and run RViz and add a **RobotModel** and **TF**. Switch the FixedFrame
to *base_footprint* to visualize the Turtlebot3.

.. hint::
   Set the description topic to */robot_description*
   and the QoS policies to *System default*

Instead of separately creating the static transforms as described in Tutorial1: ROS2 TF2 (simplistic),
you may utilize the already described urdf to display the robot.

Adding sensors to the platform
=================================

Now let us extend the robot model by adding the following:

**Camera**: Create a *camera.urdf.xacro* file in the urdf folder of **tb3_description**.

.. literalinclude:: /_resources/code/tutorials/misc/camera.urdf.xacro
   :language: xml
   :lines: 1-27,65
   :caption: camera.urdf.xacro

**IMU**: Create a *imu.urdf.xacro* file in the urdf folder of **tb3_description**.

.. literalinclude:: /_resources/code/tutorials/misc/imu.urdf.xacro
   :language: xml
   :lines: 1-8,38
   :caption: imu.urdf.xacro

**LASER Scanner**: Create a **laser.urdf.xacro** file in the urdf folder of **tb3_description**.

.. literalinclude:: /_resources/code/tutorials/misc/laser.urdf.xacro
   :language: xml
   :lines: 1-26,58
   :caption: laser.urdf.xacro

The include xacro for the sensors:

.. code-block:: xml

    <!-- sensors -->

    <xacro:include filename="$(find tb3_description)/urdf/camera.urdf.xacro"/>
    <xacro:include filename="$(find tb3_description)/urdf/imu.urdf.xacro"/>
    <xacro:include filename="$(find tb3_description)/urdf/laser.urdf.xacro"/>

Restart *tb3_description.launch.py* to view the newly added frames and meshes in RViz.

.. Exercise
----------

.. Once the urdf model is set up, copy your package **tb3_description** onto your
.. On-board computer as this will be required at later stages.