Robot URDF Model

1. Course Content

Basic: Learn how to view the robot's model file and use the GUI debugging tool window to check the movement of the model's joints by sliding the progress bar.

Advanced: Understand the composition of a URDF description file.

2. Preparations

2.1 Content Description

For Raspberry Pi boards, you need to open a terminal on the host machine, enter the command to get into the Docker container, and then input the commands mentioned in this lesson in the terminal within the Docker container. A tutorial on how to enter the Docker container from the host can be found in this product's guide [00.Configuration and Operation Guide]-[3.Enter the Docker (For RPI5)]. For ORIN and RDK boards, you can directly open a terminal and enter the commands mentioned in this lesson.

3. Start the Program

• Enter the command in the terminal:

For Raspberry Pi 5 users, if the ROS container is not started, you need to start it first,

bringup_m3

Open a terminal inside the container,

xxxxxxxxxx
exec_m3

Enter the command,

xxxxxxxxxx
ros2 launch m3_description display.launch.py gui:=true

The startup interface is as follows:

• Visualize the TF coordinate tree

Click on the left menu bar, then check the box for TF to visualize the TF coordinate tree.

• Test rotating joints

Click and drag the slider in the joint_state_publisher panel to adjust the rotation of the corresponding joint. For the ROSMASTER-M3 robot, the only movable joints are the four drive wheels.

4. Source Code Analysis

Robot model description file path:

xxxxxxxxxx
~/yahboomM3_ws/code_ws/src/m3_description/urdf/ROSMASTER-M3.xacro

Robot model launch file path:

xxxxxxxxxx
~/yahboomM3_ws/code_ws/src/m3_description/launch/display.launch.py

• URDF, which stands for Unified Robot Description Format, is a robot model file described in XML format.

​x
<?xml version="1.0" encoding="utf-8"?>
​
<robot name="ROSMASTER-M3" xmlns:xacro="http://ros.org/wiki/xacro">
​
  <xacro:arg name="prefix" default="" />                                      <!-- namespace -->
  <xacro:arg name="laser_type" default="dual" />                              <!-- Laser sensor type (single/dual) -->    
  <xacro:arg name="camera_type" default="as_hp60c" />                         <!-- Depth camera type -->
​
  <xacro:include filename="$(find m3_description)/urdf/materials.xacro"/>     <!-- Model color properties -->
  <xacro:include filename="$(find m3_description)/urdf/common_base.xacro" />  <!-- Robot chassis template -->
  <xacro:include filename="$(find m3_description)/urdf/laser.xacro" />        <!-- Lidar template -->
​
  <xacro:common_base prefix="$(arg prefix)"  camera_type="$(arg camera_type)" /><!-- Instantiating the robot chassis -->
  <xacro:laser laser_type="$(arg laser_type)" prefix="$(arg prefix)" />         <!-- Instantiate lidar -->
​
</robot>

The first line is a required XML item, describing the XML version information.

The second line describes the current robot's name; all information about the current robot is contained within the <robot> tag.

xxxxxxxxxx
  <!-- base_footprint projection point -->
  <link
    name="${prefix}base_footprint">
  </link>
  <joint
    name="${prefix}base-Joint"
    type="fixed">
    <origin
      xyz="0 0 0.03"
      rpy="0 0 0" />
    <parent
      link="${prefix}base_footprint" />
    <child
      link="${prefix}base_link" />
  </joint>
​
​
  <!-- base_link chassis -->
  <link
    name="${prefix}base_link">
    <inertial>
      <origin
        xyz="-0.02984496350171 -0.000481153572635691 0.0765287728161752"
        rpy="0 0 0" />
      <mass
        value="0.99934444005899" />
      <inertia
        ixx="0.00160080186836152"
        ixy="3.98571758764143E-06"
        ixz="-0.000131328647411587"
        iyy="0.00221164246632588"
        iyz="5.5986256573897E-07"
        izz="0.00344837201415694" />
    </inertial>
    <visual>
      <origin
        xyz="0 0 0"
        rpy="0 0 0" />
      <geometry>
        <mesh
          filename="package://m3_description//meshes/base_link.STL" />
      </geometry>
      <material
        name="">
        <color
          rgba="0.776470588235294 0.756862745098039 0.737254901960784 1" />
      </material>
    </visual>
    <collision>
      <origin
        xyz="0 0 0"
        rpy="0 0 0" />
      <geometry>
        <mesh
          filename="package://m3_description//meshes/base_link.STL" />
      </geometry>
    </collision>
  </link>
​

4.1 Components

• link: Can be thought of as a person's arm.
• joint: Can be thought of as a person's elbow joint.
• Relationship between link and joint: Two links are connected by a joint. Imagine an arm with a forearm (link) and an upper arm (link) connected by an elbow joint (joint).
• In the URDF descriptive language, link is used to describe physical properties:
• Visual display is described by the <visual> tag.
• Collision properties are described by the <collision> tag.
• Physical inertia is described by the <inertial> tag (less commonly used).

Tag Descriptions:

• origin: Describes pose information; the xyz attribute describes the coordinate position in the larger environment, and the rpy attribute describes its own orientation.
• mass: Describes the mass of the link.
• inertia: The inertial reference frame. Due to the symmetry of the rotational inertia matrix, only the 6 upper triangular elements ixx, ixy, ixz, iyy, iyz, izz are needed as attributes.
• geometry: Describes the shape; the mesh attribute's main function is to load texture files, and the filename attribute specifies the path to the texture file.
• material: Describes the material; the name attribute is required, can be empty, and can be repeated. The rgba attribute within the <color> tag describes red, green, blue, and alpha (transparency), separated by spaces. The color range is [0-1].

4.2 Joints

Introduction

Describes the relationship between two joints, motion position and velocity limits, and kinematic and dynamic properties.

Joint Types:

• fixed: A fixed joint. Does not allow movement and serves as a connection.
• continuous: A rotational joint. Can rotate continuously with no angle limits.
• revolute: A rotational joint. Similar to continuous, but with angle limits.
• prismatic: A sliding joint. Moves along an axis, with position limits.
• floating: A floating joint. Has six degrees of freedom (3T3R).
• planar: A planar joint. Allows for translation or rotation on a plane.
• In the <joint> tag, the name attribute is required, describes the joint's name, and must be unique.
• In the <joint> tag, the type attribute corresponds to one of the six joint types.

Tag Descriptions

• origin: A sub-tag that refers to the relative position of the rotating joint in the parent's coordinate system.

• parent, child: Sub-tags that represent the two links to be connected; parent is the reference, and child rotates around the parent.

• axis: A sub-tag that indicates which axis (xyz) the child link rotates around and the amount of rotation around that fixed axis.

• limit: A sub-tag that primarily restricts the child. The lower and upper attributes limit the range of rotation in radians, the effort attribute limits the force range during rotation (positive/negative values, in Newtons or N), and the velocity attribute limits the speed of rotation (in meters/second or m/s).