How to Create a Simulated Mobile Robot in ROS 2 Using URDF

In this tutorial, I will show you how to create a simulated mobile robot using the Universal Robot Description Format (URDF), the standard ROS format for robot modeling. This tutorial is the first tutorial in my Ultimate Guide to the ROS 2 Navigation Stack (also known as Nav2). Here is what you will create:

2-basic-mobile-robot-rviz

Roboticists like to simulate robots before building them in order to test out different algorithms. You can imagine the cost of making mistakes with a physical robot can be high (e.g. crashing a mobile robot into a wall at high speed means lost money).

You can get the entire code for this project here.

Let’s get started!

Prerequisites

  • ROS 2 Foxy Fitzroy installed on Ubuntu Linux 20.04
    • If you are using another ROS 2 distribution, you will need to replace ‘foxy’ with the name of your distribution everywhere I mention ‘foxy’ in this tutorial. 
    • I highly recommend you get the newest version of ROS 2. If you are using a newer version of ROS 2, you can still follow all the steps in this tutorial. Everything will work just fine.
  • You have already created a ROS 2 workspace. The name of our workspace is “dev_ws”, which stands for “development workspace.” 

What is URDF?

A URDF (Universal Robot Description Format) file is an XML file that describes what a robot should look like in real life. It contains the complete physical description of the robot. Building the body of the robot is the first step when getting started with Nav2.

The body of a robot consists of two components:

  1. Links
  2. Joints

Links are the rigid pieces of a robot. They are the “bones”. 

Links are connected to each other by joints. Joints are the pieces of the robot that move, enabling motion between connected links.

Consider the human arm below as an example. The shoulder, elbow, and wrist are joints. The upper arm, forearm and palm of the hand are links.

link_joint

For a robotic arm, links and joints look like this.

link-joint-robotic-arm

You can see that a robotic arm is made of rigid pieces (links) and non-rigid pieces (joints). Servo motors at the joints cause the links of a robotic arm to move.

For a mobile robot with LIDAR, links and joints look like this:

mobile-robot-joints-links

The wheel joints are revolute joints. Revolute joints cause rotational motion. The wheel joints in the photo connect the wheel link to the base link.

Fixed joints have no motion at all. You can see that the LIDAR is connected to the base of the robot via a fixed joint (i.e. this could be a simple screw that connects the LIDAR to the base of the robot).

You can also have prismatic joints. The SCARA robot in this post has a prismatic joint. Prismatic joints cause linear motion between links (as opposed to rotational motion).

Install the ROS 2 Navigation Stack (Nav2)

Now that you know what a URDF file is, let’s get to work.

Right now, I want you to complete this tutorial to install the ROS 2 Navigation Stack. Once you complete that tutorial, return to this page.

Don’t worry, setting up the ROS 2 Navigation Stack doesn’t take very long. Make sure to complete the entire tutorial before you come back here.

Install Important ROS 2 Packages

Now we need to install some important ROS 2 packages that we will use in this tutorial. Open a new terminal window, and type the following commands, one right after the other.

sudo apt install ros-foxy-joint-state-publisher-gui
sudo apt install ros-foxy-xacro

The format of the commands above is:

sudo apt install ros-<ros2-distro>-joint-state-publisher-gui
sudo apt install ros-<ros2-distro>-xacro

You will need to replace <ros2-distro> with the ROS 2 distribution you are using. In this case, I am using ROS 2 Foxy Fitzroy, which is ‘foxy’ for short.

Create a ROS 2 Package

Let’s create a ROS 2 package inside our workspace.

In a new terminal window, move to the src (source) folder of your workspace.

cd ~/dev_ws/src

Now create the package using the following command.

ros2 pkg create --build-type ament_cmake basic_mobile_robot

Create Extra Folders

Move inside the package.

cd ~/dev_ws/src/basic_mobile_robot

Create some extra folders with the following names.

mkdir config launch maps meshes models params rviz worlds

Type the following command to verify the folders were created.

dir
1-create-folders-with-names

Now build the package by typing the following command:

cd ~/dev_ws
colcon build

Let’s add a script to our bashrc file which enables us to use the following command to move to the package from any directory inside our terminal window.

colcon_cd basic_mobile_robot

Where ‘cd’ means “change directory”.

Note that in ROS 1, we typed roscd to change directories. In ROS 2, we use the colcon_cd command instead of roscd.

Open a terminal window, and type the following commands, one right after the other:

echo "source /usr/share/colcon_cd/function/colcon_cd.sh" >> ~/.bashrc
echo "export _colcon_cd_root=~/dev_ws" >> ~/.bashrc

Now open a new terminal window.

To go directly to the basic_mobile_robot ROS 2 package, type:

colcon_cd basic_mobile_robot

This command above will get you straight to the basic_mobile_robot package from within any directory in your Linux system. The format is:

colcon_cd [ROS 2 package name]

Create the URDF File

In this section, we will build our mobile robot step-by-step. Our robot will be defined in a Universal Robot Descriptor File (URDF), the XML file that represents a robot model.

Open a new terminal window, and type:

colcon_cd basic_mobile_robot
cd models

Make sure you have the Gedit text editor installed.

sudo apt-get install gedit

Create a new file named basic_mobile_bot_v1.urdf.

gedit basic_mobile_bot_v1.urdf

Inside this file, we define what our robot will look like (i.e. visual properties), how the robot will behave when it bumps into stuff (i.e. collision properties), and its mass (i.e. inertial properties). 

Type this code inside the URDF file.

Save and close the file.

All robots are made up of links and joints. If you go through the URDF file, you will see that we have defined each link and each joint of our two-wheeled robot. 

The links of the mobile robot include the robot base (often called “chassis”), the two drive wheels, the front caster wheel, the IMU, and the GPS. We also have a virtual link known as the base footprint. The base footprint (as shown on this post) is the link directly under the center of the robot.

Each link of the robot is connected by a joint. The only two joints that move are the revolute joints for the left and right wheels that rotate, causing the wheel links to turn.

I use xacro in this file, which stands for XML macro language. Xacro helps avoid clutter in the URDF file by enabling us to define string constants that we can reuse throughout the URDF file (e.g. “wheel_radius”).

To learn more about URDF files, check out the official documentation

Now go to the meshes folder.

cd ~/dev_ws/src/basic_mobile_robot/meshes

Add the following STL files to your meshes folder. A mesh is a file that allows your robot to look more realistic (rather than just using basic shapes like boxes and spheres).

Rather than use the STL files I provided, you can use a program like SolidWorks to generate your own STL files. You can also use a program called Blender to create DAE files. URDF files support meshes in either STL or DAE format.

Add Dependencies

Let’s add some packages that our project will depend on. Go to the package.xml file.

cd ~/dev_ws/src/basic_mobile_robot
gedit package.xml

After the <buildtool_depend> tag, add the following lines:

<exec_depend>joint_state_publisher</exec_depend>
<exec_depend>robot_state_publisher</exec_depend>
<exec_depend>rviz</exec_depend>
<exec_depend>xacro</exec_depend>

Save the file, and close it.

We will be using the Joint State Publisher and the Robot State Publisher. We will also be using RViz to visualize our robot model.

Create the Launch File

Let’s create a launch file. This launch file will be used by ROS 2 to load the necessary nodes for our package. 

colcon_cd basic_mobile_robot
cd launch
cd ~/dev_ws/src/basic_mobile_robot/launch/
gedit basic_mobile_bot_v1.launch.py

Copy and paste this code into the file.

Save the file, and close it.

If you go through the launch file, you will see that we first set the path to the important files and folders our robot needs in order to launch properly.

After we set the paths to the files and folders, we set our LaunchConfiguration variables. You can think of these variables as our options for how we want to launch our robot simulation. 

For example, imagine we want to launch our robot using the ROS 2 launch file, but we want to make sure that RViz (the robot visualization tool provided by ROS) remains turned OFF. We can create a flag called ‘use_rviz’. When we set ‘use_rviz’ to True, RViz launches, and when we set it to False, RViz does not launch.

In order for us to be able to set the value of this flag from a terminal window (i.e. outside the launch file), we have to do two things:

  1. Turn the string ‘use_rviz’ into a LaunchConfiguration variable since we can’t assign boolean values like True and False to a string like ‘use_rviz’. By using the LaunchConfiguration command, use_rviz == ‘use_rviz’.
  2. We also need to set the default value for this flag so that our system knows what to do if we don’t set its value from a terminal window as an argument when we launch our launch file. The DeclareLaunchArgument command sets the default value of the string ‘use_rviz’, which is True in the case of our launch file…and therefore, the LaunchConfiguration variable use_rviz also has a default value of True.

After we set and declare our launch arguments, we launch our ROS 2 nodes (e.g. the robot state publisher, RViz, etc.)

Add the RViz Configuration File

Let’s add a configuration file that will initialize RViz with the proper settings so we can view the robot as soon as RViz launches.

Open a new terminal window. Type:

colcon_cd basic_mobile_robot
cd rviz
gedit urdf_config.rviz

Add this code.

Save the file, and close it.

Build the Package

Now we need to build the package. Open a new terminal window, and type:

cd ~/dev_ws/src/basic_mobile_robot/
gedit CMakeLists.txt

Add the following snippet to CMakeLists.txt file above the if(BUILD_TESTING) line.

install(
  DIRECTORY config launch maps meshes models params rviz src worlds
  DESTINATION share/${PROJECT_NAME}
)

Save the file and close it.

Build the project.

cd ~/dev_ws/
colcon build

In the future, if you would like to build the basic_mobile_robot package only, you can type:

colcon build --packages-select basic_mobile_robot

Launch the Robot in RViz

Open a new terminal, and launch the robot.

cd ~/dev_ws/
ros2 launch basic_mobile_robot basic_mobile_bot_v1.launch.py

——

By the way, if you want to see the available arguments you can pass to the launch file from the terminal window, type:

ros2 launch -s basic_mobile_robot basic_mobile_bot_v1.launch.py
1b-pass-launch-arguments

And if you want to set the value of an argument (e.g. launch the robot without RViz), you can do something like this (this is a single command):

ros2 launch basic_mobile_robot basic_mobile_bot_v1.launch.py use_rviz:='False'

——

Here is the output after we launch the robot in RViz:

2-basic-mobile-robot-rviz-1
2-basic-mobile-robot-rviz-2

The joint state publisher GUI has sliders that enable you to move the wheels.

3-joint-state-publisher

If something goes wrong with the launch, close everything down, restart Linux, and launch again.

Check whether you have properly set up the collision properties by enabling Collision Enabled under RobotModel on the left pane.

4-collision-enabled-1

You can see in the image that I have modeled the base_link as a box for collisions. I could have just as easily used the STL model itself (which was used for visualization) as the collision geometry, but I decided to go with the simpler box representation to give me more flexibility to alter the collision areas if necessary. Also, Gazebo (a popular robotics simulator) recommends using simpler collision geometry to increase performance.

View the Coordinate Frames

Let’s see the coordinate frames. We first need to install the necessary software.

sudo apt install ros-foxy-tf2-tools

Again, if you have a different distribution of ROS 2, you will need to repalace ‘foxy’ in the command above with the name of your distribution.

Check out the coordinate frames.

ros2 run tf2_tools view_frames.py

In the current working directory, you will have a file called frames.pdf. Open that file.

evince frames.pdf

Here is what my coordinate transform (i.e. tf) tree looks like:

5-frames-pdf

If we want to see the coordinate transformation from one link to another, we can type the following command. For example, what is the position and orientation of the front caster wheel relative to the base_link of the robot?

The syntax is:

ros2 run tf2_ros tf2_echo <parent frame> <child frame>

We open a terminal window, and type:

ros2 run tf2_ros tf2_echo base_link front_caster

Here is the output. With respect to the base_link reference frame, the front caster wheel is located at (x=0.217 meters, y=0 meters, and z=-0.1 meters). 

6-tf2-ros-base-link-front-caster

The rotation value is in quaternion format. You can see that the rotation values are all 0s, indicating that the orientation of both coordinate frames is equivalent (i.e. the x, y, and z axes of both coordinate frames point in the same direction).

7-base-link-front-caster-wheel
8-base-link-front-caster-wheel

Remember that, by convention:

  • x-axis is red
  • y-axis is green
  • z-axis is blue 

To see an image of the architecture of our ROS system, open a new terminal window, and type the following command:

rqt_graph

Select the “Nodes/Topics (all)” option in the upper-left part of the screen, and then click the refresh arrow right next to it.

9-refresh-arrow

You can see how the joint state publisher GUI manipulates the joint states (i.e. the angle of each wheel joint). This data feeds into the robot state publisher. The robot state publisher publishes the coordinate frame relationships to tf, and the updated robot model feeds into RViz, the robot model visualization program.

10-rosgraph

That’s it! 

When you’re done, press CTRL+C in all terminal windows to shut everything down.

In the next tutorial, we will set up the odometry for our robot so that we can make the robot move and answer questions like “where is my robot located as it moves around in the world?”. Stay tuned!

Robot State Publisher vs. Joint State Publisher

In this post, I will explain the difference between the Robot State Publisher and the Joint State Publisher ROS packages. 

In order to understand the difference between the packages, it is important you first understand that every robot is made up of two components:

  1. Joints
  2. Links

Links and Joints in Robotics

Links are the rigid pieces of a robot. They are the “bones”. 

Links are connected to each other by joints. Joints are the pieces of the robot that move, enabling motion between connected links.

Consider the human arm below as an example. The shoulder, elbow, and wrist are joints. The upper arm, forearm and palm of the hand are links.

link_joint

For a robotic arm, links and joints look like this.

link-joint-robotic-arm

You can see that a robotic arm is made of rigid pieces (links) and non-rigid pieces (joints). Servo motors at the joints cause the links of a robotic arm to move.

For a mobile robot with LIDAR, links and joints look like this:

mobile-robot-joints-links

The wheel joints are revolute joints. Revolute joints cause rotational motion. The wheel joints in the photo connect the wheel link to the base link.

Fixed joints have no motion at all. You can see that the LIDAR is connected to the base of the robot via a fixed joint (i.e. this could be a simple screw that connects the LIDAR to the base of the robot).

You can also have prismatic joints. The SCARA robot in this post has a prismatic joint. Prismatic joints cause linear motion between links (as opposed to rotational motion).

Difference Between the Robot State Publisher and the Joint State Publisher

Whenever we want a robot to complete a specific task (e.g. move a certain distance in an environment, pick up an object, etc.), we have to have a way to know the position and velocity of each joint at all times. The Joint State Publisher does exactly this.

The Joint State Publisher package keeps track of the position (i.e. angle in radians for a servo motor or displacement in meters for a linear actuator) and velocity of each joint of a robot and publishes these values to the ROS system as sensor_msgs/JointState messages.

The Robot State Publisher then takes two main inputs:

  1. The sensor_msgs/JointState messages from the Joint State Publisher. 
  2. A model of the robot in URDF file format.

The Robot State Publisher takes that information, outputs the position and orientation of each coordinate frame of the robot, and publishes this data to the tf2 package

The tf2 package is responsible for keeping track of the position and orientation of all coordinate frames of a robot over time. At any given time, you can query the tf2 package to find out the position and orientation of any coordinate frame (i.e. “child frame”) relative to another coordinate frame (i.e. “parent” frame).

For example, if we are using ROS 2 and want to know the position and orientation of the LIDAR link relative to the base of the robot, we would use the following command:

ros2 run tf2_ros tf2_echo base_link lidar_link

The syntax is:

ros2 run tf2_ros tf2_echo <parent frame> <child frame>

Joint State Publisher: Simulation vs. Real World

When you are creating robots in simulation using a tool like Gazebo, you are going to want to use the joint state publisher Gazebo plugin to publish the position and orientation of the joints (i.e. publish the sensor_msgs/JointState messages).

In a real-world robotics project, you will want to write your own joint state publisher. You can find examples of how to do this here, here, and here.

How to Download a ROS Package from GitHub

Let’s say you see a ROS package on GitHub that you’d like to bring into your workspace.

For example, I would like to download the rviz_plugin_tutorials package available on this page on GitHub.

Option 1: Using the Command Line

ROS 1 Package

Open a new terminal window.

Type:

cd ~/catkin_ws/src

Clone the repository:

git clone -b <branch> <address>

For example, if you are looking to download the rviz_plugin_tutorials package available here, you would type the following command (this is a single command all on one line):

git clone -b noetic-devel https://github.com/ros-visualization/visualization_tutorials.git

You could also leave out the ROS branch specification, and type:

git clone <address>

For example:

git clone https://github.com/ros-visualization/visualization_tutorials.git

Then open up a new terminal window, and type:

cd ~/catkin_ws
catkin_make

That’s it!

ROS 2 Package

For a ROS 2 package, you would type the following (assuming the name of your ROS 2 workspace is dev_ws):

cd ~/dev_ws/src
git clone -b foxy-devel https://github.com/ros-visualization/visualization_tutorials.git

Open a new terminal window, and type:

cd ~/dev_ws

Install dependencies:

rosdep install --from-paths src --ignore-src -r -y

To build the packages, type:

colcon build --symlink-install

If that command doesn’t work, try the following command:

colcon build

Option 2: Downloading Manually from GitHub

First, you need to download the files to your computer.

Go to this page and download all the files. I like to download it to my Desktop.

Click the green “Code” button to download a ZIP file of the repository.

Open up the zip file, and go to the rviz_plugin_tutorials folder. The rviz_plugin_tutorials package is the package we need.

Right-click on that folder, and click “Extract”.

Move that folder to your catkin_ws/src folder. I just dragged the folder to my catkin_ws/src folder on my computer, just as I would drag and drop any folder on a Mac or Windows computer.

Open up a terminal window, and type:

cd ~/catkin_ws/src
dir

You should see the rviz_plugin_tutorials package (i.e. a folder) in there.

Now you need to run this command so that your ROS environment knows about the rviz_plugin_tutorials package we just added. Open a new terminal window, and type:

cd ~/catkin_ws/
catkin_make

Open a new terminal window, and type:

rospack find rviz_plugin_tutorials

You should see the path of your new ROS package.

50-path-of-new-ros-packageJPG

To see if our package depends on other packages, type these commands. Ignore any error messages you see in the terminal:

rosdep update
rosdep check rviz_plugin_tutorials

You should see a message that says “All system dependencies have been satisfied.”

51-all-dependencies-satisfiedJPG