Here, you'll learn how to describe your robot in terms of code. We make a file that gives you complete idea about a robot.

ROS uses URDF (Unified Robot Description Format) as the format for describing robot models. It's an XML based format which is specifically used to write a robot description, so again it all boils down to elements and properties defined using tags. There is a lot to this and a good part of this seeps into simulation but for now, we'll do only the basics that will help you write a simple robot description and visualize it on RViZ.

Let's get started with URDF

URDF

URDF (Unified Robot Description Format) is an XML format used to describe robots. It's used for the following purposes:

• Description of the mechanical linkage of the entire robot.
• Description of the joints between various links.
• Mechanical transmissions that link actuators to joints.
• Defining various simulation related properties.

And much more, but we'll explore only the first two here.

All the URDF files are stored in a folder named "urdf" in your package, we'll create a new package first, to do this run the following commands on a terminal:

• cd ~/ROS_workspaces/ros_ws/src/
  • Navigate to the src folder of your workspace
• catkin_create_pkg intro_robot_description robot_state_publisher urdf xacro tf
  • Create a package (I'll name it intro_robot_description, you can pick anything) and have robot_state_publisher, urdf, xacro and tf. Here's a small description for all these dependencies:
    • urdf: For the URDF description files that we'll write
    • xacro: This is an advanced form of robot description (we'll explore this later in this same page)
    • robot_state_publisher: This manages the transmission of the transformations between different links of our robot. It's sole purpose is to convert a set of joint states into transformations.
    • tf: This is to build the transformations package before this package is built. This package heavily relies on transformations, but it's all in the back end and we don't need to worry much about that.
• mkdir urdf
  • Creates a folder named "urdf" which will contain all the URDF files of this package.
• cd ../../
  • Goes back to the workspace home folder (we could rather do cd ~/ROS_workspaces/ros_ws/src/).
• catkin_make
  • Builds all the packages in the workspace.

Code

After the package has been created and built. Let's create a file named first_robot.urdf in the "urdf" folder. Let's start with just a single revolute joint robot. Here's how you write the code in this file (info about all XML tags later on):

• Start with <?xml version="1.0"?>.
• Start the <robot> tag (all our robot definition comes inside this)
  • Start the <link> tag for the base link (named "base_link")
    • Specify <visual> data for the box
  • End the </link> tag for the base link
  • Specify the <link> for the next link (named "link1") the same way we defined base_link.
  • Specify the <joint> between the two links. Note that the values for the child link (link 1) are with reference to the origin of this link.
    • Specify the origin, parent, child and axis.
  • End the </joint> tag
• End the </robot> tag

To get the file on terminal, you can run the following on a terminal:

• roscd intro_robot_description/urdf/
• cat first_robot.urdf
  • Print the file contents to terminal. We'll be feeding the output of this command as a parameter on the ROS parameter server as we'll see later.

We can verify a URDF file using the following command:

• check_urdf first_robot.urdf
  • You might have to install liburdfdom-tools using sudo apt install liburdfdom-tools.

RViZ Preparation

Follow the following steps to set up RViZ:

• Run RViZ using rosrun rviz rviz, make sure roscore is running.
• Add a Robot Model (RobotModel in the Add menu) into the Display panel
• Set the "Fixed Frame" value (under "Global Options") to "base_link".
• Save the configuration file under the name "RobotViewer.rviz" in the rviz folder of the package.

Here's how the configurations must look like

Creating the launch file

• Create the following parameters:
  • robot_description that has the output of command "cat $(find intro_robot_description)/urdf/first_robot.urdf".
  • use_gui that holds the value "true".
• Execute the following nodes:
  • joint_state_publisher from the package joint_state_publisher.
    • This is to make the GUI window that will help you control the robot.
  • robot_state_publisher from the package robot_state_publisher.
    • This is to take the joint states and convert them into transformations. These are frame transformations, essentially a function that takes us from the base (fixed frame) to any link in the robot. It's basically the mathematical model of the links of the robot (it gives position and orientation of every individual link if any joint is actuated).
  • rviz from the package rviz. Pass it the RViZ configuration file we saved.
    • For visualizing.
    • We use the -d argument to pass the .rviz file to RViZ.

Running everything

• Execute the following command on a terminal:
  • roslaunch intro_robot_description FirstLaunch.launch

All outputs below

URDF XML Tags

All tags on the official page, there's a summary here as well. The tags for simple robot description are sorted priority wise (high to low).

Main bounds

• The tag <?xml version="1.0"?> is to specify the version of XML used for the URDF file. It's best we keep it the same and put it in the beginning of every URDF file.
• The <robot>...</robot> tag is what contains the entire robot description inside it. It has the following attributes:
  • name: The name of the robot being described. It's important for the URDF to be parsed successfully.

Defining a Link

A link is basically any physical object in the robot. The <link>...</link> tag is used to define a link. It has the following attributes:

• name: Name of the link (every link has to have a name).

It has various elements to describe various properties of the link. Some important ones are:

Inertial

This is to define the inertia tensor of the robot. It's different for different mass distributions, but here is a list of general mass distributions. The <intertia> ... </inertia> tag is used for this. The elements of this tag are:

• <mass ... />: mass of the link, pass it in value attribute.
• <inertia ... />: For the mass matrix calculated using the formulas here (some examples here). Because the rotational inertia matrix is symmetric, only 6 above-diagonal elements of this matrix are specified here, using the attributes ixx, ixy, ixz, iyy, iyz, izz.
• <origin ... />: Inertial reference frame (by default it's with the body frame, if not specified). Attributes are xyz for position and rpy for orientation.

Visual

The visual properties of a link, the apparent shape. The <visual> ... </visual> tag is used for this. It has the following attributes:

• name: a name that we add for reference, not mandatory.

It has the following elements for definition of the visual properties:

• <origin ... />: The origin of the link. Use xyz to define the position and rpy for orientation. All the values are with respect to the main frame for the link. It's more like the offset we apply to the geometry from the link origin defined by joints or the base.
• <geometry> ... </geometry>: The geometry (shape) of the element. These are the elements available as options:
  • <box ... />: To define a cuboid of size specified by size attribute.
  • <cylinder ... />: To define a cylinder of a particular radius and length.
  • <sphere ... />: To define a sphere of a particular radius.
  • <mesh ... />: A trimesh element, specify filename and an optional scale factor. The trimesh files could be Collada files (.dae) for texture and color, but STL (.stl) files work as well.
• <material> ... </material>: To define the color and texture of the link. You can use the attribute name to save the material and reuse it. It has the following elements available:
  • <color ... />: To specify the color for the material. Specify it using the attribute rgba (four numbers in a string).
  • <texture ... />: To specify texture, pass it the filename.

Collision

These are for the collision boundaries of the link. These are usually primitive boundaries for simpler computation. Since this is also like a region, all of the tags, attributes and elements that are for visual apply for this as well but no <material> tag here. The <collision> ... </collision> tag is used for this.

You can have multiple collision and visual tags under the same link. The ultimate result is just the union of all the regions.

Defining a Joint

A joint is basically something that connects two links together. The <joint> ... </joint> tag is used for this. It has the following attributes:

• name: Name of the joint. This is important for the joint state controller.
• type: The type of the joint. These are the joints supported:
  • prismatic: For single degree of freedom translational joint. More info here.
  • revolute: For rotational joints with some lower and upper limits on the angle. More info here.
  • continuous: A revolute joint that has full rotational freedom, it can perform full rotations.
  • fixed: For completely fixed joint (non movable).
  • floating: For joints that can be controlled in all ways (all six degrees of freedom).
  • planar: Allows motion in all directions on a plane (two translational degrees of freedom and one rotational degree of freedom) perpendicular to an axis.

These are the important elements for this tag:

• <origin ... />: The origin for the joint. This origin is with respect to the parent link's origin and defines the base for the child link definitions. It needs the attributes xyz for translational and rpy for orientational positioning.
• <parent ... />: To define the parent link for the joint. The joint position is defined with respect to the parent and the parent is not moved by the joint (it stays still when the joint actuates). We have to pass the attribute link as a parameter (give it the link name).
• <child ... />: To define the child link for the joint. This is the link that is actuated by the joint. We have to pass the attribute link as a parameter (give it the link name).
• <axis ... />: To specify the axis for the joint actuation. For rotational joints, it's the axis of rotation as per the right hand thumb rule. For prismatic joints, it's the axis of movement and for planar joints, it's an axis perpendicular to the plane. Pass it the attribute xyz value to specify the axis (normalized values). By default it's the X axis or "1 0 0".
• <limit ... />: To specify the limits of the joint. The attributes are lower (lower limit of joint value), upper (upper limit of joint value), effort (maximum joint efforts to be applied) and velocity (maximum velocity required). This is required for revolute and prismatic joints only. You can check this page out for safety limits.

XACRO

XACRO stands for XML Macro. You must have thought that writing code using URDF is very time consuming and that there are many parts that repeat for large structures. XACRO is simply a more advanced way of writing descriptions for robots.

You could check out the official documentation for this and a tutorial showing you how to clean up a URDF using XACRO. However, we'll discuss this briefly here as well.

Here are a few important things to remember while using XACRO for robot modelling:

• The file extension of a XACRO file is ".xacro" and it can be stored in the "urdf" folder of the package itself.
• All of the URDF code is valid in a XACRO file as well, XACRO just provides additional functionalities. In fact, most of the code here is written in URDF only.
• For a XACRO file, the robot tag has another attribute for the namespace:
  • xmlns:xacro: Pass it the documentation string. This is for the successful parsing of the XACRO file. We basically have to add this inside the tag.
    • Basically add the following inside the robot tag as a attribute: xmlns:xacro="http://www.ros.org/wiki/xacro".
    • This tag is important for successful parsing of the XACRO file.
• The XACRO tags start with "xacro:"
• Everything in ${expression} is evaluated (mathematical expressions and substitution of variables).

Let's get started with a simple XACRO file

Tutorial on XACRO

XACRO file code

1. Create a file named "first_xacro.xacro" in the urdf folder
2. Declare the robot tag using <robot>. All the code will be inside it.
3. Create a property for side length
4. Create a macro to add a link of specified length at a specified origin with a specified axis of rotation.
5. Call that macro 5 times for the five links that we make using it.

Launch file

1. Create arguments to be passed
   • model for the XACRO file name
   • rviz_config for the RViZ configuration to be used, we'll use the one we made for URDF
   • use_gui for spawning the GUI window to control the robot
2. Create parameters for the ROS parameter server
   • robot_description for the robot. The output of xacro command should be parsed.
   • use_gui for the GUI window. Same as the argument.
3. Launch the nodes
   • rviz for the main RViZ window. Use the "-d" tag to parse the configuration file.
   • joint_state_publisher for publishing the joint states, values of joint displacement (angles here). We'll call this joint vector.
   • robot_state_publisher which converts the joint vector to transformations.

Name the file "XACROLauncher.launch" and save it in the launch folder. Run the following command on a terminal and play around with the joint_state_publisher GUI window:

roslaunch intro_robot_description XACROLauncher.launch

Output below, all codes after the image

XACRO Tags

Using XACRO

• Have xmlns:xacro="http://www.ros.org/wiki/xacro" inside the robot tag as an argument.
• XACRO files are converted into URDF files using the xacro node of the xacro package. You can find more about it by running either of the following commands:
  • rosrun xacro xacro --help
  • xacro --help

There are a few tags declared below.

Constants

To declare a constant, use the <xacro:property ... /> tag. It has the following attributes:

• name: The name of the property
• value: The value of the property. All values in URDF is a string, so are all values in XACRO.

Use ${property_name} to substitute for the property value at the site.

For example, the following code

<xacro:property name=”var1” value=”name1” />

<link name=”link_${var1}” />

will generate the following output

<link name=”link_name1” />

The substitution of ${var1} can be observed.

Math

Everything in ${} is evaluated mathematically. All math is done using floating point evaluation. Even variable names (constant names) inside ${} are substituted in value. We can use +, -, *, /, sin and cos. Essentially the math module in python. More info here.

Conditional Blocks

XACRO also allows blocks to be parsed only if certain conditions are met. Virtually, any python evaluateable boolean expression will work. We use the <xacro:unless> ... </xacro:unless> tag and <xacro:if> ... </xacro:if> tag which have the value attribute that must evaluate to "1" (or "true") or "0" (or "false").

Macro

MACROs are snippets of codes that are substituted wherever called. The <xacro:macro> ... </xacro:macro> tag is used, it has the following attributes:

• name: Under which the XACRO tag is created and will be used under.
• params: Parameters for the XACRO macro.
  • Simple names are just like variables in the macro and an attribute in the macro function call. Default parameters are also available (reference here) using :=value after parameter definition.
  • Names with a single asterisk (*) in the beginning are blocks of code that can be inserted intro the macro using <xacro:insert_block ... /> tag and accessed using the name attribute.

Under this, we can write any code that we want to substitute for the macro call. More on this here.

We call the macro using <xacro:macro_name ... > ... </xacro:macro_name> tag.

Include other files into a XACRO file

We use the <xacro:include ... /> tag for this. This is used to include other files (preferably xacro, but it's used for other purposes as well). We'll use this later on in gazebo as well (you will see that in later pages). The attributes of <xacro:include ... /> are:

• filename: Relative file path with full filename extension. You can use $(find package_name) and $(cwd) as well for file paths.
• ns: Namespace (not mandatory).

Additional notes on URDF

Positioning of link elements

• The <joint> ... </joint> tag defines the frame of child link with respect to the parent lint. For this child link, this new frame server the purpose of the reference frame.
• The <origin ... /> tag in <link> ... </link> tag specifies the offset to be given to the link properties with respect to the reference frame of the link. For the base link (first link) the reference frame is the X, Y and Z axis in RViZ. For other links, the frame they receive in the <joint> ... </joint> tag defines the reference frame.

Checking the URDF file

Here are the following commands that help us in checking a URDF file:

• check_urdf first_xacro.urdf
  • This shows a command line text representation of the link structure. This also parses the XML
• urdf_to_graphiz first_xacro.urdf
  • It creates a PDF and a GV file. The file name is same as the model name (first_xacro here).

Additional notes on XACRO

Converting XACRO to URDF

Use the "xacro" command (or "rosrun xacro xacro" will also do the same):

• xacro first_xacro.xacro > first_xacro.urdf
  • The xacro first_xacro.xacro command actually parses the XACRO and converts it to URDF and sends the output to the terminal, the > first_xacro.urdf part is simply to put thing output in a file named first_xacro.urdf (your file names could be anything).
  • You can check the options of this command using xacro --help command.

Controlling a robot in RViZ

This is about making the robot move in RViZ. We'll have a simple two link robot with one oscillating joint but you can have this procedure done for any robot.

Making the robot

• Create a link named base_link.
• Create a link named link1.
• Create a joint between base_link and link1.

Making the Launch file

• Have the following arguments
  • robot_model: The name of the URDF file without extension to be launched (file in the urdf folder).
  • rviz_model: The name of the RViZ configuration file without extension to be launched (file in the rviz folder).
  • internal: The joint controller node is inside the package (true), or use the one in joint_state_publisher package (false).
  • jc_exec: The executable node name of the joint controller in the package.
  • use_gui: For the joint_state_publisher (default option)
• Set the following parameters:
  • robot_description: Load the contents of the URDF file
  • use_gui: The argument value
• Launch the following nodes:
  • rviz for the RViZ window. Pass it the rviz_model configuration file. Make it required for the launch.
  • robot_state_publisher
  • If internal is false, joint_state_publisher. If internal is true then the argument jc_exec.

Running everything

Execute the following command on a terminal:

• roslaunch intro_robot_description RViZ_Robot_Controller.launch

You could also run the following commands on different terminal and see how the joint_states are published:

• rostopic echo /joint_states
• rostopic info /joint_states

It'll show you the message structure being published.

Making the package ready

• Add the following in CMakeLists.txt file (file here):
  • Add sensor_msgs to the find_package function
• Add the following in package.xml file (file here):
  • Add sensor_msgs tag to build_depend, build_export_depend and exec_depend
• Build the package
  • cd ~/ROS_workspaces/ros_ws/
  • catkin_make

Now that we've added the sensor_msgs dependency we can use the topic sensor_msgs/JointState to write code.

Joint controller using C++

• Include the header files for ROS (ros/ros.h), time (ros/time.h), joint state messages (sensor_msgs/JointState.h).
• Declare main function, initialize the node, create a node handler.
• Create a publisher that publishes messages of type sensor_msgs::JointState. The topic name must be "joint_states".
• Make a rate controller that will control how many times a second we publish data, use ros::Rate class.
• Create a message of type sensor_msgs::JointState that we'll publish.
  • The header.frame_id part must be blank. Initialize the current time to the header.stamp member.
  • Resize the name and position vector to 1 (or number of joints). This is basically initializing vector size.
  • Initialize the name (joint names) vector and position (joint values) vector.
• Publish the message and increment the sequence for the header.
• Cause a delay to maintain rate

Building the node

• In the CMakeLists.txt file (code here), add the following:
  • Add an executable named JointController_CPP and give the source as "src/JointController.cpp". Use the add_executable function.
  • Link the ${catkin_LIBRARIES} to the executable using target_link_libraries function.
  • The file in the link might have packages gazebo_ros and sensor_msgs under find_packages. Ignore them for now, we'll learn about them later.
• Build the package:
  • cd ~/ROS_workspaces/ros_ws/
  • catkin_make

Running the node

Run the following launch command on a terminal (we've already created the launch file before)

roslaunch intro_robot_description RViZ_Robot_Controller.launch internal:="true" jc_exec:="JointController_CPP"

The internal tag is set to true, that means we'll assign an executable as a joint controller. In jc_exec, we give the executable name as well. We could run the joint controller using the command rosrun intro_robot_description JointController_CPP and it's the same thing.

You must see the RViZ window open and the robot model with it's joints receiving the commands.

Joint controller using Python

• Write the first comment line for every python script in ROS
• Import the rospy library for ROS, JointStates from sensor_msgs.msg package and other needed packages
• Initialize the node and create a publisher object that publishes messages of type JointStates. The topic name must be "joint_states".
• Have a rate controller
• Create a message object to publish
  • Assign it a sequence number
  • Assign it the current time
  • Assign it the joint names and position values
  • Publish the message
• Create a delay to maintain the rate

Executing the python script

• Make the script executable if not already done
  • roscd intro_robot_description/scripts/
  • chmod +x *.py
• Run the launch file, this time give the python executable as the jc_exec argument
  • roslaunch intro_robot_description RViZ_Robot_Controller.launch internal:="true" jc_exec:="PyJointController.py"

You must see the RViZ window open and the robot model with it's joints receiving the commands.