How to Create URDF and Launch Files in ROS2 and Display Them in Rviz

In this Robot Operating System 2 (ROS2) tutorial we explain how to write a minimal working example of creating a URDF model as well as a launch file. We also explain how to display the created URDF model in Rviz and ROS2.

The main motivation for this tutorial is that you can hardly find online and on YouTube a concise and self-contained tutorial explaining how to write URDF and launch files in ROS2, and how to correctly display the URDF model in Rviz. There are a number of tutorials explaining this process in ROS version 1. However, there are no concise tutorials explaining how to do this in ROS version 2.   Consequently, for people who are completely new to ROS2, this process can be very difficult. To fill in this knowledge gap, we created this video tutorial. In order to provide a minimal working example, the URDF model developed in this tutorial is very simple. It is a single cylinder. You can easily develop more complex and realistic models by following the ideas presented in this tutorial.

The YouTube accompanying this video is given below.

The ROS2 modeling process consists of several steps that are explained below.

STEP 1: Check the Linux and ROS2 distributions

First, it is very important to verify that you have the correct versions (distributions) of Linux and ROS2 installed. Although you can probably implement the code presented in this tutorial in various Linux and ROS2 versions, this tutorial is based on Linux Ubuntu 22.04 and ROS2 Iron Irwini distribution. Consequently, we strongly suggest you install Ubuntu 22.04 and ROS2 Iron Irwini. The tutorial explaining how to install ROS2 Iron Irwini from scratch is given here.

To check the Linux version, open a new terminal, and type this:

cat /etc/os-release

The output should look like this:

PRETTY_NAME="Ubuntu 22.04.3 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"
VERSION="22.04.3 LTS (Jammy Jellyfish)"
VERSION_CODENAME=jammy
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://www.ubuntu.com/"
SUPPORT_URL="https://help.ubuntu.com/"
BUG_REPORT_URL="https://bugs.launchpad.net/ubuntu/"
PRIVACY_POLICY_URL="https://www.ubuntu.com/legal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=jammy

Next, let us check the ROS2 version. In the same terminal type

source /opt/ros/iron/setup.bash
printenv ROS_DISTRO

As the output, you should get

iron

The tutorial presented in the sequel should work also for other ROS2 distributions. However, instead of
“iron”, you should type the name of your distribution in the packages that explicitly require the ROS2 distribution name.

STEP 2: Install the necessary packages and programs

First, we need to source the ROS2 environment. That is, we need to create an underlay:

source /opt/ros/iron/setup.bash

Let us now install the necessary programs and ROS2 packages. First, let us install gedit editor. Note that gedit is not a ROS2 package

sudo apt-get update

sudo apt-get install gedit

Then, let us install the following ROS2 packages. We need joint-state publisher and joint-state-publisher-gui:

sudo apt install ros-iron-joint-state-publisher
sudo apt install ros-iron-joint-state-publisher-gui

Note that if you are using some other version of ROS2, then instead of “iron”, you should type the name of your ROS2 distribution. This is, this package is optional for this tutorial. However, it will be used in future tutorials.

sudo apt install ros-iron-xacro

Rviz 2 should be installed with ROS2, however, type this to double-check that rviz2 is properly installed

ros2 pkg prefix rviz2

You should get the path to the RViz2 source folder.

STEP 3: Create the workspace and package

Open a new terminal and source the underlay

source /opt/ros/iron/setup.bash

Create the workspace folder

mkdir -p ~/ws_urdf/src

Create the workspace, and build

cd ~/ws_urdf/
colcon build

Create the package

cd ~/ws_urdf/src
ros2 pkg create --build-type ament_cmake urdf_test

The package source files and folders will be in the folder ~/ws_urdf/src/urdf_test/. Consequently, let us navigate to that folder and let us create several subfolders

cd ~/ws_urdf/src/urdf_test/
mkdir launch urdf

The launch folder will contain the Python lunch file necessary to run the model in RViz. The URDF folder will contain the URDF source file of the model. Note that URDF stands for “Unified Robotics Description Format”. This is a file format that is used to specify the geometry of robots and some other properties.

Let us now build the complete workspace once more. To build the workspace and packages, you need to navigate to the source folder of the workspace:

cd ~/ws_urdf/
colcon build

STEP 4: Create the URDF and launch source files

Let us first create the URDF file:

cd ~/ws_urdf/src/urdf_test/urdf
gedit model.urdf

Then, type the following XML code

<?xml version="1.0"?>
<robot name="Robot1">
  <link name="base_link">
    <visual>
      <geometry>
        <cylinder length="1" radius="0.4"/>
      </geometry>
    </visual>
  </link>
</robot>

This file will create only a single object. This object is a cylinder with the radius of 0.4 and the length of 0.4. Next, we need to add the dependencies

cd ~/ws_urdf/src/urdf_test
gedit package.xml

Add these lines to “package.xml”

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

Next, let us create the launch file:

cd ~/ws_urdf/src/urdf_test/launch
gedit display.launch.py

Type the launch file given below:

import launch
from launch.substitutions import Command, LaunchConfiguration
import launch_ros
import os

def generate_launch_description():
    pkgPath = launch_ros.substitutions.FindPackageShare(package='urdf_test').find('urdf_test')
    urdfModelPath= os.path.join(pkgPath, 'urdf/model.urdf')
    
    with open(urdfModelPath,'r') as infp:
    	robot_desc = infp.read()
    
    params = {'robot_description': robot_desc}
    
    robot_state_publisher_node =launch_ros.actions.Node(
    package='robot_state_publisher',
	executable='robot_state_publisher',
    output='screen',
    parameters=[params])
    
    
    joint_state_publisher_node = launch_ros.actions.Node(
        package='joint_state_publisher',
        executable='joint_state_publisher',
        name='joint_state_publisher',
        parameters=[params],
        condition=launch.conditions.UnlessCondition(LaunchConfiguration('gui'))
    )
    joint_state_publisher_gui_node = launch_ros.actions.Node(
        package='joint_state_publisher_gui',
        executable='joint_state_publisher_gui',
        name='joint_state_publisher_gui',
        condition=launch.conditions.IfCondition(LaunchConfiguration('gui'))
    )
    
    rviz_node = launch_ros.actions.Node(
        package='rviz2',
        executable='rviz2',
        name='rviz2',
        output='screen'
    )

    return launch.LaunchDescription([
        launch.actions.DeclareLaunchArgument(name='gui', default_value='True',
                                            description='This is a flag for joint_state_publisher_gui'),
        launch.actions.DeclareLaunchArgument(name='model', default_value=urdfModelPath,
                                            description='Path to the urdf model file'),
        robot_state_publisher_node,
        joint_state_publisher_node,
        joint_state_publisher_gui_node,
        rviz_node
    ]) 

STEP 5: Final build and run of RViz

We need to edit the CMakeLists.txt file as follows:

cd ~/ws_urdf/src/urdf_test
gedit CMakeLists.txt

Then, find the line “if(BUILD_TESTING)”, and above this line, type the following

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

Next, we perform one last final build of the workspace and the package:

cd ~/ws_urdf
colcon build

The final step is to source the setup file of the created package, that is, to create the overlay:

source ~/ws_urdf/install/setup.bash

Next, we launch the RViz

ros2 launch urdf_test display.launch.py

The last step is to adjust the RViz parameters. Under “Global Options”, find “Fixed Frame”, and type “base_link”. This is the name of the link from the URDF file. Then, click on the add button and find “RobotModel ”. Under RobotModel, find “Description Source”, and select Topic. Then, under “Description Topic”, select “/robot_description”. The graph is shown below.