[Documentation] [TitleIndex] [WordIndex

Note: This tutorial assumes that you have completed the previous tutorials: URDF tutorials.
(!) Please ask about problems and questions regarding this tutorial on answers.ros.org. Don't forget to include in your question the link to this page, the versions of your OS & ROS, and also add appropriate tags.

Create a URDF for an Industrial Robot

Description: Walks through the steps and conventions for creating a Unified Robot Description Format (URDF) for an industrial robot.

Keywords: urdf, industrial, manipulator

Tutorial Level: INTERMEDIATE

Next Tutorial: Create a MoveIt Package for an Industrial Robot

In this tutorial we will learn to create URDFs for typical industrial manipulators. The URDF XML format is very expressive and allows many different ways of defining the same geometry. We will discuss specific conventions that are meant to:

Generate STLs from 3D CAD Models

The arm path planning methods that are used by ROS-Industrial are collision aware. In order to take advantage of this capability 3D information about the robot geometry is required.

Prepare CAD Models

Link coordinate systems must be created before exporting STL files from 3D CAD models. The coordinate system present in vendor supplied CAD models are rarely in the desired position. The desired coordinate systems should adhere to the following:

Create STLs

The URDF allows for two types of 3D models, visual and collision models.

Visual quality STLs

A visual quality model is used for display purposes only. These models can be highly detailed because they are not used for collision checking. Visual models can be exported directly from a CAD package. Make certain to export binary STLs.

Collision quality STLs

Collision quality models should not be highly detailed. The more detailed these models, the longer it takes to perform collision checks. Collision models should be simple, yet encompass the entire link geometry. It is suggested the convex hulls be created from visual STLs, using a 3D mesh tool such as MeshLab (Filters->Remeshing, Simplification and Reconstruction->Convex Hull).

Create a URDF for your robot

As you step through the following to create a URDF for your robot, adhere to the following conventions:

Create a support package for your robot

The convention for the name of a package containing urdf / xacro files along with launch files to bring up the robot controller is <<yourrobot>>_support.

$ catkin_create_pkg <<yourrobot>>_support

Add xacro as dependency to the generated package.xml:

   1 <exec_depend>xacro</exec_depend>

Create a XACRO Macro for your robot

While it is possible to write an explicit URDF for a particular industrial arm, a more general XACRO approach is taken. A XACRO is a type of URDF macro that can be used to generate a URDF. We take this approach because industrial manipulators are often combined with custom end-effectors, requiring a custom URDF. By writing a XACRO that can generate the manipulator portion of the URDF, we provide flexible and extensible library that can be used to generate any custom robot.

See the m10ia_macro.xacro for an example.

For more information on creating an XACRO, see the XACRO tutorials.

Additional/Standard Frames

By convention and in order to match common industrial robot frames, several additional frames should be added to the XACRO

base_link The base_link shall be positioned in the logical base position (oriented by convention, z-axis up, x-axis forward). This frame name is by ROS convention. Typically this frame is the first frame of the robot tied to the first link.

flange The flange shall be the attachment point for an end-effector. As with other robot links it is oriented with the z-axis up (pointing towards the end-effector).

tool0 The tool0 frame (pronounced: 'tool-zero') shall match exactly an all-zeros TCP configuration as defined on the robot controller. For most controllers, this is equal to an unconfigured TCP, which lies on the physical robot's mounting flange.

This transform (between the last robot link and tool0) may be defined in any way (so may consist of all combinations of translations and rotations), as long as it is a fixed joint type in the URDF.

Users are advised to never change flange or tool0, but instead add additional frame(s) as (a) child(ren) of flange.

The following snippet shows an example definition:

   1 <link name="${prefix}tool0" />
   3 <joint name="${prefix}link_6-tool0" type="fixed">
   4   <parent link="${prefix}link_6" />
   5   <child link="${prefix}tool0" />
   6   <origin xyz="0 0 0" rpy="0 0 0" />
   7 </joint>

base The base frame shall match exactly the base defined by the robot controller. Its purpose is to allow users to transform points into the Cartesian base frame of the robot. Examples of base frames are the World Frame on Fanuc controllers and $ROBROOT for KUKA.

The transform between base and base_link can be defined in any way, as long as the transform is fixed between the two (i.e. not across a movable joint). The preference is for base to be defined relative to base_link. It does not have to be part of the main kinematic chain.

The following snippet shows an example base definition:

   1 <link name="${prefix}base" />
   3 <joint name="${prefix}base_link-base" type="fixed">
   4   <parent link="${prefix}base_link" />
   5   <child link="${prefix}base" />
   6   <origin xyz="0 0 0" rpy="0 0 0" />
   7 </joint>

Generate a URDF for your robot

In order to generate a URDF for your robot, another XACRO (a "top-level" XACRO) must be written to call the XACRO macro written in the previous section. See m10ia.xacro for an example.

Note that URDFs are not composible - meaning that you cannot (easily) combine them with other models as you can with XACROs. Most tools that consume URDF in ROS are capable of loading XACRO directly, so there is typically no need to manually convert them to URDFs.

Converting like below can be a good check to see whether your XACRO is formatted correctly though, so it could still be useful.

To generate the URDF and check the result (Groovy and older):

$ rosrun xacro xacro.py -o <<urdf_file>> <<xacro_file>>
$ rosrun urdf_parser check_urdf <<urdf_file>>

To generate the URDF and check the result (Hydro and newer):

$ rosrun xacro xacro.py -o <<urdf_file>> <<xacro_file>>
$ check_urdf <<urdf_file>>

If successful, the commands above will generate a URDF of your industrial manipulator. As an example, see the m10ia.urdf.

Generate a URDF for your robot and end-effector (Optional)

This section is meant to demonstrate why a XACRO is used instead of directly writing the URDF. In the case where an end-effector is added to the robot, the XACRO comes in handy.

See the following robot + end-effector example.

Verify your URDF

It is very important that the information within the URDF is accurate. Specifically, the joint limits and orientations will used in the following steps and must be correct. To visualize your robot run the following:

$ roslaunch urdf_tutorial display.launch model:=<<urdf_file>> gui:=True

Use the GUI sliders to verify the joint orientation (i.e. plus/minus moves the actual robot). Also verify that the joint limits match.

2019-12-07 12:18