Tutorial: Using a URDF in Gazebo

Tutorial: Using a URDF in Gazebo

参考：http://gazebosim.org/tutorials?tut=ros_urdf&cat=connect_ros

URDF文件是xml 格式在ROS 中用于机器人描述，gazebo中基于URDF的 robot，需要SDF文件

The Universal Robotic Description Format (URDF)is an XML file format used in ROS to describe all elements of a robot.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.Simulation Description Format (SDF)

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 theSimulation 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.

urdf 缺乏很多特征而且不能适应机器人发展的需要。仅指定的运动和单机器人孤立的动态特性。不能指定在世界中的位置，也不是一种统一的描述格式，

它不能指定循环连接（平行连接），它缺乏摩擦和其他属性。不能表示例如灯光和高度图的东西。在应用方面，该urdf语法突破XML属性重用正确的格式，

从而使urdf更灵活。也没有向后兼容的机制。  ===》  sdf 格式

 
sdf 可以描述世界与机器人的每个东西 。 它具有可扩展性，可以方便地添加和修改元素。 SDF格式采用XML描述本身，这有利于一个简单的升级工具迁移旧版本，新版本。 这也是自我描述。

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:

Required  -- 惯性元素

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

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        //刚体连接
  

The Element          SDF格式

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 included 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.

Prerequisites

The first step to getting your robot working in Gazebo is to have a working URDF file from the correspondingROS 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.

   urdf 文件==》 rviz 显示验证

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 adouble inverted pendulum and demonstrates some fun control concepts within a simulator.

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

下载gazebo_ros_demos

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 Overview Tutorials.

View in Rviz   显示

To check if everything is working, launch RRBot in Rviz:

roslaunch rrbot_description rrbot_rviz.launch

And you should see our little bot like so:

滑动可以调节关节转动。rviz用于显示还是很有

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.

It is 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.

The gazebo_ros_controltutorial will explain how to use Rviz to monitor the state of your simulatedrobot by publishing/joint_states directly from Gazebo.In the previous example, the RRBot in Rviz is getting its/joint_statesfrom a fake joint_states_publisher node (the window with the slider bars).

Examine the RRBot URDF

The rest of this tutorial will refer to various aspects of the RRBot URDF.Go ahead and view therrbot.xacro filenow:

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.gazeboa Gazebo specific file that includes most of our Gazebo-specific XML elements including the tags
• materials.xacroa simple Rviz colors file for storing rgba values, not really necessary but a nice conventionT

he gazebo_ros_controltutorial will explain how to use Rviz to monitor the state of your simulatedrobot by publishing /joint_states directly from Gazebo.In the previous example, the RRBot in Rviz is getting its /joint_statesfrom a fake joint_states_publisher node (the window with the slider bars).  

Examine the RRBot URDF

The rest of this tutorial will refer to various aspects of the RRBot URDF.Go ahead and view therrbot.xacro filenow:

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          gazebo           
  
• materials.xacro a simple Rviz colors file for storing rgba values, not really necessary but a nice convention                  rviz

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.

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:

element for the tag

If a element is used without a reference="" property, it is assumed the element is for the whole robot model.

无《gazebo》标签中无refrence 表示整个机器人模型。

The elements for a inside the tag are listed in the following table:

Name	Type	Description
static	bool	If set to true, the model is immovable. Otherwise the model is simulated in the dynamics engine.

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 theROS Motor and Sensor Plugins tutorial.

Rigidly Fixing A Model to the World

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:

如果要让模型贴附到世界坐标系，需要创建world 的link与joint（连接两者）。

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

Links          碰撞 可视（材料：颜色与纹理） 惯性

Be sure you are familiar with the URDF link element.  

The following is an example link from RRBot:

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.

and elements

These tags work essentially the same in Gazebo as in Rviz.It is 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.

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.

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 filematerials.xacro:

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 allGazebo-specific tag in a secondary file calledrrbot.gazebo.You can find the and elements there.

The default available materials in Gazebo can be found in the Gazebo source code atgazebo/media/materials/scripts/gazebo.material.

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

• The SDF documentation
• OGRE materials documentation

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.

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:

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.

Elements For Links

List of elements that are individually parsed:

Name	Type	Description
material	value	Material of visual element
gravity	bool	Use gravity
dampingFactor	double	Exponential velocity decay of the link velocity - takes the value and multiplies the previous link velocity by (1-dampingFactor).
maxVel	double	maximum contact correction velocity truncation term.
minDepth	double	minimum allowable depth before contact correction impulse is applied
mu1	double	Friction coefficients μ for the principal contact directions along the contact surface as defined by theOpen Dynamics Engine (ODE) (see parameter descriptions inODE's user guide)
mu2
fdir1	string	3-tuple specifying direction of mu1 in the collision local reference frame.
kp	double	Contact stiffness k_p and damping k_d for rigid body contacts as defined by ODE (ODE uses erp and cfm but there is amapping between erp/cfm and stiffness/damping)
kd
selfCollide	bool	If true, the link can collide with other links in the model.
maxContacts	int	Maximum number of contacts allowed between two entities. This value overrides the max_contacts element defined in physics.
laserRetro	double	intensity value returned by laser sensor.

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 theROS Motor and Sensor Plugins tutorial.

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
  

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 are ignored
• In the tag, only the damping property is used for gazebo4 and earlier.Gazebo5 and up also uses thefriction property.
• All of properties in the tag are optional

RRBot Example

The following is a joint used in the RRBot:

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.

Elements For Joints

Name	Type	Description
stopCfm	double	Joint stop constraint force mixing (cfm) and error reduction parameter (erp) used by ODE
stopErp
provideFeedback	bool	Allows joints to publish their wrench data (force-torque) via a Gazebo plugin
implicitSpringDamper	bool	If this flag is set to true, ODE will use ERP and CFM to simulate damping.This is a more stable numerical method for damping than the default damping tag.The cfmDamping element is deprecated and should be changed to implicitSpringDamper.
cfmDamping
fudgeFactor	double	Scale the excess for in a joint motor at joint limits. Should be between zero and one.

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 theROS Motor and Sensor Plugins tutorial.

Verifying the Gazebo Model Works         check urdf->sdf

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

  # gazebo2 and below
  gzsdf print MODEL.urdf
  # gazebo3 and above
  gz sdf -p 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

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 namedMYROBOT_description in the subfolder /urdf. 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 and MYROBOT_gazebo. 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.

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 theSDF user guide for more info on various properties available in Gazebo, which are also available in the URDF via the tag.

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 theGazebo Model Database.It is an online server that Gazebo connects to to pull down models from the internet.Its Mercurial repository is located onBitbucket.SeeGazebo Model Databasedocumentation for how to submit a pull request to have your robot added to the database.

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.