Advanced URDF Features

Overview

While basic URDF provides the foundation for robot modeling, advanced features extend its capabilities for more complex and realistic robot descriptions. This lesson explores advanced URDF features including transmissions for hardware interfaces, detailed visual and collision elements, material definitions, and Xacro for creating reusable and parameterized robot models.

Transmissions in URDF

What are Transmissions?

Transmissions in URDF define the relationship between actuators and joints in a robot. They specify how hardware components (like motors and encoders) interface with the robot's kinematic structure. This information is crucial for:

• Hardware interface configuration
• Control system setup
• Simulation-physical robot mapping
• Real-time control

Transmission Types

Simple Transmission

The most common type for single actuator-single joint systems:

<transmission name="simple_trans">
  <type>transmission_interface/SimpleTransmission</type>
  <joint name="joint1">
    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
  </joint>
  <actuator name="motor1">
    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
    <mechanicalReduction>1</mechanicalReduction>
  </actuator>
</transmission>

Differential Transmission

For systems with multiple actuators controlling a single joint:

<transmission name="differential_trans">
  <type>transmission_interface/DifferentialTransmission</type>
  <joint name="left_wheel_joint">
    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
    <role>left</role>
  </joint>
  <joint name="right_wheel_joint">
    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
    <role>right</role>
  </joint>
  <actuator name="left_motor">
    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
    <role>left</role>
  </actuator>
  <actuator name="right_motor">
    <hardwareInterface>hardware_interface/EffortJointInterface</hardwareInterface>
    <role>right</role>
  </actuator>
</transmission>

Hardware Interfaces

Joint Interfaces

Different types of hardware interfaces for joint control:

<joint name="head_swivel">
  <command_interface name="position"/>
  <command_interface name="velocity"/>
  <state_interface name="position"/>
  <state_interface name="velocity"/>
</joint>

• position: Control joint position
• velocity: Control joint velocity
• effort: Control joint torque/force
• impedance: Control joint impedance (advanced)

Complete Transmission Example

<?xml version="1.0"?>
<robot name="robot_with_transmissions">
  <link name="base_link">
    <visual>
      <geometry>
        <box size="0.5 0.5 0.2"/>
      </geometry>
    </visual>
  </link>

  <link name="arm_link">
    <visual>
      <geometry>
        <cylinder radius="0.05" length="0.3"/>
      </geometry>
    </visual>
  </link>

  <joint name="arm_joint" type="revolute">
    <parent link="base_link"/>
    <child link="arm_link"/>
    <axis xyz="0 1 0"/>
    <limit lower="-1.57" upper="1.57" effort="100" velocity="1"/>
    <origin xyz="0 0 0.2" rpy="0 0 0"/>
    <!-- Joint interfaces for control -->
    <command_interface name="position"/>
    <state_interface name="position"/>
  </joint>

  <!-- Transmission definition -->
  <transmission name="arm_trans">
    <type>transmission_interface/SimpleTransmission</type>
    <joint name="arm_joint">
      <hardwareInterface>hardware_interface/PositionJointInterface</hardwareInterface>
    </joint>
    <actuator name="arm_motor">
      <hardwareInterface>hardware_interface/PositionJointInterface</hardwareInterface>
      <mechanicalReduction>1</mechanicalReduction>
    </actuator>
  </transmission>
</robot>

Advanced Visual and Collision Elements

Visual Elements

Detailed Visual Properties

Visual elements define how a robot appears in visualization tools:

<link name="complex_visual_link">
  <visual>
    <origin xyz="0 0 0.1" rpy="0 0 0"/>
    <geometry>
      <mesh filename="package://my_robot_description/meshes/complex_part.stl"/>
    </geometry>
    <material name="red_plastic">
      <color rgba="0.8 0.1 0.1 1.0"/>
      <texture filename="package://my_robot_description/textures/plastic.png"/>
    </material>
  </visual>
</link>

Multiple Visual Elements

A single link can have multiple visual elements:

<link name="multi_visual_link">
  <visual name="main_visual">
    <geometry>
      <box size="0.1 0.1 0.2"/>
    </geometry>
    <material name="blue">
      <color rgba="0.1 0.1 0.8 1.0"/>
    </material>
  </visual>
  <visual name="decoration_visual">
    <origin xyz="0 0 0.1" rpy="0 0 0"/>
    <geometry>
      <sphere radius="0.02"/>
    </geometry>
    <material name="yellow">
      <color rgba="0.8 0.8 0.1 1.0"/>
    </material>
  </visual>
</link>

Collision Elements

Advanced Collision Properties

Collision elements define how a robot interacts with the environment:

<link name="collision_link">
  <collision>
    <origin xyz="0 0 0.1" rpy="0 0 0"/>
    <geometry>
      <mesh filename="package://my_robot_description/meshes/collision_mesh.stl"/>
    </geometry>
  </collision>
  <!-- Contact properties for physics simulation -->
  <contact_coefficients mu="0.2" kp="1000000.0" kd="1.0"/>
</link>

Multiple Collision Elements

Similar to visual elements, links can have multiple collision elements:

<link name="multi_collision_link">
  <collision name="main_collision">
    <geometry>
      <box size="0.1 0.1 0.2"/>
    </geometry>
  </collision>
  <collision name="attachment_collision">
    <origin xyz="0.05 0 0" rpy="0 0 0"/>
    <geometry>
      <cylinder radius="0.01" length="0.05"/>
    </geometry>
  </collision>
</link>

Inertial Properties

Detailed Inertial Elements

Inertial properties are crucial for physics simulation:

<link name="inertial_link">
  <inertial>
    <origin xyz="0.01 0.02 0.03" rpy="0 0 0"/>
    <mass value="2.5"/>
    <inertia ixx="0.01" ixy="0.0" ixz="0.001"
             iyy="0.02" iyz="0.002" izz="0.015"/>
  </inertial>
</link>

• mass: Mass in kilograms
• inertia: 3x3 inertia matrix (symmetric, 6 values)
• origin: Center of mass offset from link frame

Materials in URDF

Material Definitions

Named Materials

Materials can be defined once and reused across multiple links:

<material name="black">
  <color rgba="0.0 0.0 0.0 1.0"/>
</material>

<material name="red">
  <color rgba="0.8 0.1 0.1 1.0"/>
</material>

<material name="blue">
  <color rgba="0.1 0.1 0.8 1.0"/>
</material>

<material name="yellow">
  <color rgba="0.8 0.8 0.1 1.0"/>
</material>

<material name="white">
  <color rgba="1.0 1.0 1.0 1.0"/>
</material>

Textured Materials

Materials can also include texture references:

<material name="textured_material">
  <color rgba="1.0 1.0 1.0 1.0"/>
  <texture filename="package://my_robot_description/textures/wood.png"/>
</material>

Complete Material Example

<?xml version="1.0"?>
<robot name="robot_with_materials">
  <!-- Material definitions -->
  <material name="red">
    <color rgba="0.8 0.1 0.1 1.0"/>
  </material>

  <material name="green">
    <color rgba="0.1 0.8 0.1 1.0"/>
  </material>

  <material name="blue">
    <color rgba="0.1 0.1 0.8 1.0"/>
  </material>

  <!-- Links using materials -->
  <link name="red_link">
    <visual>
      <geometry>
        <box size="0.1 0.1 0.1"/>
      </geometry>
      <material name="red"/>
    </visual>
  </link>

  <link name="green_link">
    <visual>
      <geometry>
        <cylinder radius="0.05" length="0.2"/>
      </geometry>
      <material name="green"/>
    </visual>
  </link>

  <link name="blue_link">
    <visual>
      <geometry>
        <sphere radius="0.05"/>
      </geometry>
      <material name="blue"/>
    </visual>
  </link>
</robot>

Xacro: XML Macros for URDF

Introduction to Xacro

Xacro (XML Macros) is a macro language for XML that extends URDF capabilities. It allows you to:

• Create reusable components
• Use variables and constants
• Define parameterized macros
• Reduce redundancy in complex models
• Create more maintainable robot descriptions

Installing and Using Xacro

To use xacro files, you typically process them to URDF:

xacro input_file.xacro > output_file.urdf

Or use them directly in launch files:

ros2 launch urdf_tutorial display.launch.py model:=path/to/model.urdf.xacro

Xacro Properties (Constants)

Define constants to avoid repetition:

<?xml version="1.0"?>
<robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="xacro_example">
  <!-- Define constants -->
  <xacro:property name="M_PI" value="3.14159"/>
  <xacro:property name="width" value="0.2"/>
  <xacro:property name="bodylen" value="0.6"/>
  <xacro:property name="leglen" value="0.5"/>

  <link name="base_link">
    <visual>
      <geometry>
        <cylinder radius="${width}" length="${bodylen}"/>
      </geometry>
      <material name="blue"/>
    </visual>
  </link>
</robot>

Xacro Macros

Simple Macros

Create reusable components:

<xacro:macro name="default_origin">
  <origin xyz="0 0 0" rpy="0 0 0"/>
</xacro:macro>

<xacro:macro name="default_inertial" params="mass">
  <inertial>
    <mass value="${mass}"/>
    <inertia ixx="1e-3" ixy="0.0" ixz="0.0"
             iyy="1e-3" iyz="0.0"
             izz="1e-3"/>
  </inertial>
</xacro:macro>

Parameterized Macros

Create flexible, parameterized components:

<xacro:macro name="wheel" params="prefix parent xyz_offset">
  <link name="${prefix}_wheel">
    <visual>
      <origin xyz="0 0 0" rpy="${M_PI/2} 0 0"/>
      <geometry>
        <cylinder radius="0.1" length="0.05"/>
      </geometry>
    </visual>
    <collision>
      <origin xyz="0 0 0" rpy="${M_PI/2} 0 0"/>
      <geometry>
        <cylinder radius="0.1" length="0.05"/>
      </geometry>
    </collision>
    <xacro:default_inertial mass="0.5"/>
  </link>

  <joint name="${prefix}_wheel_joint" type="continuous">
    <parent link="${parent}"/>
    <child link="${prefix}_wheel"/>
    <origin xyz="${xyz_offset}" rpy="0 0 0"/>
    <axis xyz="0 1 0"/>
  </joint>
</xacro:macro>

Macros with Block Parameters

For maximum flexibility, use block parameters:

<xacro:macro name="blue_shape" params="name *shape">
  <link name="${name}">
    <visual>
      <geometry>
        <xacro:insert_block name="shape"/>
      </geometry>
      <material name="blue"/>
    </visual>
    <collision>
      <geometry>
        <xacro:insert_block name="shape"/>
      </geometry>
    </collision>
  </link>
</xacro:macro>

<!-- Usage -->
<xacro:blue_shape name="base_link">
  <cylinder radius=".42" length=".01"/>
</xacro:blue_shape>

Complete Xacro Example

<?xml version="1.0"?>
<robot xmlns:xacro="http://www.ros.org/wiki/xacro" name="xacro_robot">
  <!-- Constants -->
  <xacro:property name="M_PI" value="3.14159"/>
  <xacro:property name="width" value="0.2"/>
  <xacro:property name="bodylen" value="0.6"/>
  <xacro:property name="leglen" value="0.5"/>

  <!-- Materials -->
  <material name="blue">
    <color rgba="0 0 0.8 1"/>
  </material>

  <!-- Macros -->
  <xacro:macro name="default_inertial" params="mass">
    <inertial>
      <mass value="${mass}"/>
      <inertia ixx="1e-3" ixy="0.0" ixz="0.0"
               iyy="1e-3" iyz="0.0"
               izz="1e-3"/>
    </inertial>
  </xacro:macro>

  <xacro:macro name="leg" params="prefix reflect">
    <link name="${prefix}_leg">
      <visual>
        <geometry>
          <box size="${leglen} 0.1 0.2"/>
        </geometry>
        <origin xyz="0 0 -${leglen/2}" rpy="0 ${M_PI/2} 0"/>
        <material name="blue"/>
      </visual>
      <collision>
        <geometry>
          <box size="${leglen} 0.1 0.2"/>
        </geometry>
        <origin xyz="0 0 -${leglen/2}" rpy="0 ${M_PI/2} 0"/>
      </collision>
      <xacro:default_inertial mass="10"/>
    </link>

    <joint name="base_to_${prefix}_leg" type="fixed">
      <parent link="base_link"/>
      <child link="${prefix}_leg"/>
      <origin xyz="0 ${reflect*(width+.02)} 0.25"/>
    </joint>
  </xacro:macro>

  <!-- Robot structure -->
  <link name="base_link">
    <visual>
      <geometry>
        <cylinder radius="${width}" length="${bodylen}"/>
      </geometry>
      <material name="blue"/>
    </visual>
    <collision>
      <geometry>
        <cylinder radius="${width}" length="${bodylen}"/>
      </geometry>
    </collision>
    <xacro:default_inertial mass="50"/>
  </link>

  <!-- Use macros to create legs -->
  <xacro:leg prefix="right" reflect="1"/>
  <xacro:leg prefix="left" reflect="-1"/>
</robot>

Advanced Xacro Features

Conditional Statements

Xacro supports conditional statements for more complex logic:

<xacro:macro name="conditional_part" params="include_sensor:=false">
  <link name="base_part">
    <visual>
      <geometry>
        <box size="0.1 0.1 0.1"/>
      </geometry>
    </visual>
  </link>

  <xacro:if value="${include_sensor}">
    <link name="sensor">
      <visual>
        <geometry>
          <cylinder radius="0.01" length="0.02"/>
        </geometry>
      </visual>
    </link>
    <joint name="sensor_joint" type="fixed">
      <parent link="base_part"/>
      <child link="sensor"/>
      <origin xyz="0.05 0 0" rpy="0 0 0"/>
    </joint>
  </xacro:if>
</xacro:macro>

Mathematical Expressions

Xacro supports mathematical operations:

<xacro:property name="a" value="5"/>
<xacro:property name="b" value="3"/>
<xacro:property name="sum" value="${a + b}"/>
<xacro:property name="product" value="${a * b}"/>
<xacro:property name="angle" value="${M_PI / 4}"/>

File Inclusion

Include other xacro files:

<xacro:include filename="package://my_robot_description/urdf/common_properties.xacro"/>
<xacro:include filename="package://my_robot_description/urdf/sensors/camera.xacro"/>

Best Practices for Advanced URDF

1. Use Xacro for Complex Models

• Reduce redundancy with properties and macros
• Create parameterized components
• Organize files logically with includes

2. Optimize Collision Geometry

• Use simple shapes for collision elements
• Balance accuracy with performance
• Consider using separate, simplified meshes

3. Plan Your Kinematic Structure

• Design the joint hierarchy carefully
• Consider control requirements
• Account for workspace limitations

4. Validate Your Models

• Check URDF validity with check_urdf
• Test in simulation before hardware deployment
• Verify joint limits and ranges

5. Document Complex Models

• Use comments to explain complex sections
• Provide examples of how to use macros
• Document parameter meanings

Common Advanced URDF Issues

Issue: Xacro processing fails

Solution: Check for syntax errors, ensure all properties are defined before use.

Issue: Transmissions not working

Solution: Verify hardware interface names match your controller configuration.

Issue: Complex collision meshes causing performance issues

Solution: Simplify collision geometry or use multiple simple shapes.

Issue: Inertial properties causing simulation instability

Solution: Verify that inertia values are physically realistic and properly calculated.

Learning Objectives

By the end of this lesson, you should be able to:

• Define and configure transmissions for hardware interfaces
• Create advanced visual and collision elements
• Apply materials to enhance robot appearance
• Use Xacro to create reusable and parameterized robot models
• Implement complex Xacro features like conditionals and includes
• Apply best practices for advanced URDF development
• Troubleshoot common issues with advanced URDF features