Tutorials/1.9/Using A URDF In Gazebo

The Universal Robotic Description Format (URDF) is an XML file format used in ROS to describe all elements of a robot. To use a URDF file in Gazebo, some additional simulation-specific tags must be added to work properly with Gazebo. This tutorial explains the necessary steps to successfully use your URDF-based robot in Gazebo, saving you from having to create a separate SDF file from scratch and duplicating description formats. Under the hood, Gazebo will then convert the URDF to SDF automatically.


 * 1) Background

While URDFs are a useful and standardized format in ROS, they are lacking many features and have not been updated to deal with the evolving needs of robotics. URDF can only specify the kinematic and dynamic properties of a single robot in isolation. URDF can not specify the pose of the robot itself within a world. It is also not a universal description format since it cannot specify joint loops (parallel linkages), and it lacks friction and other properties. Additionally, it cannot specify things that are not robots, such as lights, heightmaps, etc.

On the implementation side, the URDF syntax breaks proper formatting with heavy use of XML attributes, which in turn makes URDF more inflexible. There is also no mechanism for backward compatibility.

To deal with this issue, a new format called the Simulator Description Format (SDF) was created for use in Gazebo to solve the shortcomings of URDF. SDF is a complete description for everything from the world level down to the robot level. It is scalable, and makes it easy to add and modify elements. The SDF format is itself described using XML, which facilitates a simple upgrade tool to migrate old versions to new versions. It is also self-descriptive.

It is the intention of this author to make URDFs as fully documented and supported in Gazebo as possible, but it is relevant to the reader to understand why the two formats exist and the shortcomings of both. It would be nice if more work was put into URDFs to update them to the current needs of robotics.


 * 1) Overview of Converting to Gazebo

There are several steps to get a URDF robot properly working in Gazebo. The following is an overview of steps, which are then elaborated on in the rest of this tutorial:


 * 1) Required

- An element within each element must be properly specified and configured.


 * 1) Optional

- Add a element for every - Convert visual colors to Gazebo format - Convert stl files to dae files for better textures - Add sensor plugins - Add a element for every - Set proper damping dynamics - Add actuator control plugins - Add a element for the element - Add a link if the robot should be rigidly attached to the world/base_link


 * 1) The Element

The element is an extension to the URDF used for specifying additional properties needed for simulation purposes in Gazebo. It allows you to specify the properties found in the SDF format that are not by default in the URDF format. None of the elements within a element are required because default values will be automatically included. There are three different types of elements - one for the tag, one for tags, and one for tags. We will discuss the attributes and elements within each type of element throughout this tutorial.


 * 1) Prerequisites

The first step to getting your robot working in Gazebo is to have a working URDF file from the corresponding ROS URDF Tutorials. Test your URDF by viewing it in Rviz before proceeding to configure your robot with Gazebo. In this tutorial, we'll use a simple demo robot named RRBot. Feel free to follow along with this robot or your own bot.


 * 1) Getting RRBot

RRBot, or Revolute-Revolute Manipulator Robot, is a simple 3-linkage, 2-joint arm that we will use to demonstrate various features of Gazebo and URDFs. It essentially a double inverted pendulum and demonstrates some fun control concepts within a simulator.

To get RRBot, clone the Github repo into the /src folder of your catkin workspace and rebuild your workspace:

cd ~/catkin_ws/src/ git clone https://github.com/ros-simulation/gazebo_ros_demos.git cd .. catkin_make

If any of this is unfamiliar, be sure you have read the previous ROS Integration Tutorials.

To check if everything is working, launch RRBot in Rviz:
 * 1) View in Rviz

roslaunch rrbot_description rrbot_rviz.launch

And you should see our little bot like so:



If you do not get this, try killing all old roscore processes with killall roscore and relaunching RViz.

You should also be able to play with the slider bars in the Joint State Publisher window to move the two joints.

Its important that while converting your robot to work in Gazebo, you don't break Rviz or other ROS-application functionality, so its nice to occasionally test your robot in Rviz to make sure everything still works.

In the [gazebo_ros_control](http://gazebosim.org/wiki/Tutorials/1.9/ROS_Control_with_Gazebo) tutorial we'll go over how to use Rviz to monitor the state of your simulated robot by publishing /joint_states directly from Gazebo. In this previous example the RRBot in Rviz is getting its /joint_states from a fake joint_states_publisher node (the window with the slider bars).


 * 1) Examine the RRBot URDF

For the rest of this tutorial, we'll refer to various aspects of the RRBot's URDF. Go ahead and view the file now:

rosed rrbot_description rrbot.xacro

Note that we are using Xacro to make some of the link and joint calculations easier. We are also including two additional files:

- rrbot.gazebo a Gazebo specific file that includes most of our Gazebo-specific XML elements including the tags - materials.xacro a simple Rviz colors file for storing rgba values, not really necessary but a nice convention


 * 1) View in Gazebo

You should also be able to launch RRBot into Gazebo:

roslaunch rrbot_gazebo rrbot_world.launch

In the launched Gazebo window you should see the robot standing straight up. Despite there being no intentional disturbances in the physics simulator by default, numerical errors should start to build up and cause the double inverted pendulum to fall after a few seconds. The following is a mid-swing screenshot of the RRBot:

Eventually the arm should come to a complete stop. We encourage you to tweak and test various aspects of the URDF during the following tutorials to help you learn more about simulating URDF robots.


 * 1) Header of a URDF File

There have been many API changes in Gazebo and the required URDF format, one of which that Gazebo xml-schema namespaces are no longer needed. If your URDF has something like:



You can remove them. All you need in your root element tag is the name of the robot and optionally the xml namespace for xacro if you are using that:




 * 1) element for the tag

If a element is used without a reference="" property, it is assumed the element is for the whole robot model. The elements for a inside the tag are listed in the following table:

Elements within a tag that are not in the above table are directly inserted into the SDF tag for the generated SDF. This is particularly useful for plugins, as discussed in the ROS Motor and Sensor Plugins tutorial.

If you would like your URDF model to be permanently attached to the world frame (the ground plane), you must create a "world" link and a joint that fixes it to the base of your model. RRBot accomplishes this with the following:
 * 1) Rigidly Fixing A Model to the World



If however you have a mobile base or some other moving robot, you do not need this link or joint.


 * 1) Links

Be sure you are familiar with the URDF link element.

The following is an example link from RRBot:

 

 <box size="${width} ${width} ${height1}"/>

<origin xyz="0 0 1" rpy="0 0 0"/> <inertia ixx="1.0" ixy="0.0" ixz="0.0" iyy="1.0" iyz="0.0" izz="1.0"/>


 * 1) Note On Units

As per ROS REP 103: Standard Units of measure and Coordinate Conventions, units in Gazebo should be specified in meters and kilograms. Gazebo could possibly be used with imperial units if the constants such as gravity were changed manually, but by default gravity is 9.81 m/s^2. When specifying mass, use units of kilograms.


 * 1) and elements

These tags work essentially the same in Gazebo as in Rviz. Its important that you specify both though, because unlike some ROS applications, Gazebo will not use your elements as elements if you do not explicitly specify a element. Instead, Gazebo will treat your link as "invisible" to laser scanners and collision checking.


 * 1) Simplify collision model

You can use the same geometry or meshes for both your collision and visual elements, though for performance improvements we strongly suggest you have a simplified model/meshes for your collision geometry. A good open-source tool for simplifying meshes is Blender. There are many closed-source tools, such as Maya and 3DS Max, which can also simplify meshes.


 * 1) Materials: Using proper colors and textures

A standard URDF can specify colors using a tag such as in the RRBot:

With the color orange defined separately such as in the file materials.xacro</tt>: <color rgba="${255/255} ${108/255} ${10/255} 1.0"/>

Unfortunately, this method of specifying link colors does not work in Gazebo as it adopts OGRE's material scripts for coloring and texturing links. Instead, a Gazebo material tag must be specified for each link, such as:

Gazebo/Orange

As mentioned earlier, in the RRBot example we have chosen to include all Gazebo-specific tag in a secondary file called rrbot.gazebo</tt>. You can find the and elements there.

The default available materials in Gazebo can be found in the Gazebo source code at gazebo/media/materials/scripts/gazebo.material</tt> and some of them are listed here for reference:

Gazebo Colors and Materials


 * Gazebo/DepthMap
 * Gazebo/XYZPoints
 * Gazebo/LaserScan1st
 * Gazebo/LaserScan2nd
 * Gazebo/Grey
 * Gazebo/White
 * Gazebo/FlatBlack
 * Gazebo/Black
 * Gazebo/Red
 * Gazebo/Green
 * Gazebo/Blue
 * Gazebo/Yellow
 * Gazebo/Purple
 * Gazebo/Turquoise
 * Gazebo/Orange
 * Gazebo/WhiteGlow
 * Gazebo/RedGlow
 * Gazebo/GreenGlow
 * Gazebo/BlueGlow
 * Gazebo/YellowGlow
 * Gazebo/PurpleGlow
 * Gazebo/TurquoiseGlow
 * Gazebo/TurquoiseGlowOutline
 * Gazebo/RedTransparent
 * Gazebo/GreenTransparent
 * Gazebo/BlueTransparent
 * Gazebo/YellowTransparent
 * Gazebo/LightOn
 * Gazebo/LightOff
 * Gazebo/BlueLaser
 * Gazebo/OrangeTransparent
 * Gazebo/JointAnchor
 * Gazebo/WoodFloor
 * Gazebo/CeilingTiled
 * Gazebo/PaintedWall
 * Gazebo/PioneerBody
 * Gazebo/Pioneer2Body
 * Gazebo/Gold
 * Gazebo/GreyGradientSky
 * Gazebo/CloudySky
 * Gazebo/WoodPallet
 * Gazebo/Wood
 * Gazebo/Road
 * Gazebo/GaussianCameraNoise

For more advanced or custom materials, you can create your own OGRE colors or textures. See:

- The SDF documentation - OGRE materials documentation


 * 1) STL and Collada files

Like in Rviz, Gazebo can use both STL and Collada files. It is generally recommended you use Collada (.dae) files because they support colors and textures, whereas with STL files you can only have a solidly colored link.


 * 1) Element

For the Gazebo physics engine to work properly, the element must be provided as documented on the URDF link element page. For links to not be ignored in Gazebo, their mass must be greater than zero. Additionally, links with zero principal moment of inertia (ixx, iyy, izz) could lead to infinite acceleration under any finite torque application.

Determining the correct values for each link is required to get accurate physics approximations in Gazebo. This can be performed by conducting various measurements of the robots parts, or by using CAD software like Solidworks that includes features for approximating these values. For beginners, you can also just make the values up.

An example inertia element from the RRBot first link: <origin xyz="0 0 ${height1/2}" rpy="0 0 0"/> <inertia ixx="1.0" ixy="0.0" ixz="0.0" iyy="1.0" iyz="0.0" izz="1.0"/>

The origin tag represents the center of mass of this link. By setting the center of mass to half the height of the RRBot's rectangular link, we center the mass in the middle. You can visually check if your center of mass is correct in your URDF within Gazebo by clicking on the View menu of Gazebo and selecting both Wireframe and Center of Mass.

In this example robot, both the mass and inertia matrix are made up values since this robot has no real-world counterpart.


 * 1) Elements For Links

List of elements that are individually parsed:

Similar to elements for, any arbitrary blobs that are not parsed according to the table above are inserted into the the corresponding element in the SDF. This is particularly useful for plugins, as discussed in the ROS Motor and Sensor Plugins tutorial.


 * 1) RRBot Example of element

In the RRBot, the friction coefficients of the two non-fixed linked were specified so that if a collision occurred more accurate contact interactions were simulated. The following is an example link's tag:

0.2    0.2     Gazebo/Black


 * 1) Joints

Make sure you are familiar with the URDF joint documentation. However, not all of the elements documented for URDF joints are applicable to Gazebo:


 * The, and are required
 * and <safety_controller> are ignored
 * In the tag, only the damping</tt> property is used
 * All of properties in the tag are optional


 * 1) RRBot Example

The following is a joint used in the RRBot:

<joint name="joint2" type="continuous"> <origin xyz="0 ${width} ${height2 - axel_offset*2}" rpy="0 0 0"/> <dynamics damping="0.7"/>

Notice the dynamics element with a viscous damping coefficient of 0.7 N*m*s/rad, damping is simply the amount of opposing force to any joint velocity (in this case torque per angular velocity) that is used to "slow" a moving joint towards rest.

The value of 0.7 N*m*s/rad was decided on by testing different amounts of damping and watching how "realistic" the swinging pendulum appeared. We encourage you to play with this value now (increase/decrease it) to get a feel for how it affects the physics engine.


 * 1) Elements For Joints

Again, similar to elements for and, any arbitrary blobs that are not parsed according to the table above are inserted into the the corresponding element in the SDF. This is particularly useful for plugins, as discussed in the ROS Motor and Sensor Plugins tutorial.


 * 1) Verifying the Gazebo Model Works

With Gazebo installed, an easy tool exists to check if your URDF can be properly converted into a SDF. Simply run the following command:

gzsdf print MODEL.urdf

This will show you the SDF that has been generated from your input URDF as well as any warnings about missing information required to generate the SDF.

Note: in Gazebo version 1.9 and greater, some of the debug info has been moved to a log file you can view with:

cat ~/.gazebo/gzsdf.log


 * 1) Viewing the URDF In Gazebo

Viewing the RRBot in Gazebo was already covered at the beginning of this tutorial. For your own custom robot, we assume its URDF lives in a ROS package named MYROBOT_description</tt> in the subfolder /urdf</tt>. The method to open a URDF from that location into Gazebo using ROS was covered in the previous tutorial, Using roslaunch Files to Spawn Models. If you have not completed that tutorial, do so now.

From that tutorial you should have two ROS packages for your custom robot: MYROBOT_description</tt> and MYROBOT_gazebo</tt>. To view your robot and test it in Gazebo, you should be able to now run something like:

roslaunch MYROBOT_gazebo MYROBOT.launch

This should launch both the Gazebo server and GUI client with your robot automatically launched spawned inside.


 * 1) Tweaking your model

If your robot model behaves unexpectedly within Gazebo, it is likely because your URDF needs further tuning to accurately represent its physics in Gazebo. See the SDF user guide for more info on various properties available in Gazebo, which are also available in the URDF via the tag.


 * 1) Sharing your robot with the world

If you have a common robot that other's might want to use in Gazebo, you are encouraged to add your URDF to the Gazebo Model Database. It is an online server that Gazebo connects to to pull down models from the internet. Its Mercurial repository is located on Bitbucket. See Gazebo Model Database documentation for how to submit a pull request to have your robot added to the database.


 * 1) Next steps

You have now learned how to use ROS packages containing URDFs with Gazebo, and how to convert your custom URDF to work in Gazebo. You are now ready to learn about adding plugins to your URDF so that different aspects of your robot and the simulated environment can be controlled. See ROS Motor and Sensor Plugins.