Xacro macros for URDF - Step-by-Step Execution

Concept Flow - Xacro macros for URDF

Start Xacro file

↓

Define macro with parameters

↓

Use macro call with arguments

↓

Macro expands to URDF XML elements

↓

URDF robot description built

↓

Robot model ready for ROS tools

Xacro macros let you define reusable robot parts with parameters, then expand them into full URDF XML to build robot models.

Execution Sample

ROS

<xacro:macro name="wheel" params="radius width">
  <link name="wheel_link">
    <visual>
      <geometry><cylinder radius="${radius}" length="${width}"/></geometry>
    </visual>
  </link>
</xacro:macro>

<xacro:wheel radius="0.1" width="0.05"/>

Defines a wheel macro with radius and width, then calls it to create a wheel link in URDF.

Execution Table

Step	Action	Macro/Element	Parameters	Resulting XML snippet
1	Start parsing Xacro file	N/A	N/A	Ready to read macros and elements
2	Define macro 'wheel'	wheel	radius, width	Macro stored with parameters radius and width
3	Encounter macro call <xacro:wheel>	wheel	radius=0.1, width=0.05	Prepare to expand macro with these values
4	Expand macro body	wheel	radius=0.1, width=0.05	<link name="wheel_link"><visual><geometry><cylinder radius="0.1" length="0.05"/></geometry></visual></link>
5	Insert expanded XML into URDF	N/A	N/A	URDF now includes wheel_link with specified geometry
6	Finish parsing	N/A	N/A	Complete URDF robot description ready for use

💡 All macros expanded and URDF XML fully generated

Variable Tracker

Variable	Start	After Step 3	After Step 4	Final
radius	undefined	0.1	0.1	0.1
width	undefined	0.05	0.05	0.05
macro 'wheel'	defined with params	called with args	expanded with args	expanded XML inserted

Key Moments - 3 Insights

Why do we use ${radius} inside the macro instead of a fixed number?

Because ${radius} is a placeholder replaced by the argument value (0.1 here) during macro expansion, as shown in execution_table step 4.

What happens if we call the macro without required parameters?

The macro expansion will fail or produce incorrect XML because parameters like radius and width are needed to fill placeholders, as seen in step 3 where parameters are passed.

Does the macro create new XML elements each time it is called?

Yes, each macro call expands into its own XML snippet inserted into the URDF, shown in step 4 and 5.

Visual Quiz - 3 Questions

Look at the execution_table, what is the value of 'width' after step 4?

A undefined

B 0.05

C 0.1

D Not set yet

💡 Hint

Check variable_tracker column 'After Step 4' for 'width'

At which step does the macro 'wheel' get expanded into XML elements?

A Step 4

B Step 2

C Step 3

D Step 5

💡 Hint

See execution_table row where 'Expand macro body' happens

If you call the macro 'wheel' with radius=0.2, how would the XML snippet change?

A The link name changes to wheel_0.2

B The width attribute changes to 0.2

C The cylinder radius attribute becomes 0.2

D No change in XML

💡 Hint

Look at how parameters replace placeholders in execution_table step 4

Concept Snapshot

Xacro macros let you define reusable robot parts with parameters.
Use <xacro:macro name="name" params="p1 p2"> to define.
Call with <xacro:name p1="val1" p2="val2"/>.
During processing, macros expand to URDF XML with parameters replaced.
This avoids repeating XML and makes robot models easier to manage.

Full Transcript

Xacro macros are a way to write reusable pieces of robot description in URDF files. You define a macro with a name and parameters. When you call the macro with specific values, it replaces placeholders in the macro body with those values and produces XML elements. This process builds the full URDF robot model. For example, a wheel macro can take radius and width parameters and create a wheel link with those dimensions. The execution flow starts by reading the Xacro file, storing macros, then expanding macro calls into XML snippets. Variables like radius and width get their values when the macro is called. This helps avoid repeating XML code and makes robot descriptions easier to maintain and customize.

Practice

1. What is the main purpose of using xacro:macro in a URDF file?

easy

A. To define reusable robot parts with customizable parameters

B. To execute robot movement commands

C. To compile the URDF into machine code

D. To visualize the robot in 3D

Solution

1. Step 1: Understand what xacro:macro does

   xacro:macro lets you define a piece of robot description once and reuse it multiple times with different settings.

2. Step 2: Identify the main purpose

   It helps to avoid repeating code and makes the URDF easier to maintain by allowing parameter customization.

3. Final Answer:

   To define reusable robot parts with customizable parameters -> Option A

4. Quick Check:

   Reusability and customization [OK]

Hint: Macros = reusable parts with parameters [OK]

Common Mistakes:

• Thinking macros run robot commands
• Confusing macros with visualization tools
• Believing macros compile code

2. Which of the following is the correct syntax to define a macro named wheel with a parameter radius in Xacro?

easy

A. <xacro:macro name="wheel" radius="1.0">...</xacro:macro>

B. <xacro:macro name="wheel" params="radius">...</xacro:macro>

C. <macro name="wheel" param="radius">...</macro>

D. <xacro:define name="wheel" radius>...</xacro:define>

Solution

1. Step 1: Recall Xacro macro syntax

   Macros are defined with <xacro:macro> tag and parameters are listed in the params attribute as a space-separated string.

2. Step 2: Match the correct syntax

   <xacro:macro name="wheel" params="radius">...</xacro:macro> correctly uses params="radius" inside <xacro:macro> tag.

3. Final Answer:

   <xacro:macro name="wheel" params="radius">...</xacro:macro> -> Option B

4. Quick Check:

   Params attribute [OK]

Hint: Use params="param1 param2" inside [OK]

Common Mistakes:

• Using attributes other than 'params' for parameters
• Omitting the 'params' attribute
• Using incorrect tag names like <macro> or

3. Given the following Xacro macro and call:

<xacro:macro name="link_with_length" params="length">
  <link name="link_${length}">
    <visual>
      <geometry>
        <box size="${length} 0.1 0.1"/>
      </geometry>
    </visual>
  </link>
</xacro:macro>

<xacro:link_with_length length="2.0"/>

What will be the name of the generated link element?

medium

A. link_

B. link_length

C. link_2.0

D. link_${length}

Solution

1. Step 1: Understand macro parameter substitution

   The macro uses ${length} to insert the parameter value into the link name and box size.

2. Step 2: Substitute the parameter value

   The call passes length="2.0", so link_${length} becomes link_2.0.

3. Final Answer:

   link_2.0 -> Option C

4. Quick Check:

   Parameter substitution = link_2.0 [OK]

Hint: Parameter values replace ${param} in macro body [OK]

Common Mistakes:

• Not substituting parameter, leaving ${length} literal
• Using parameter name instead of value
• Leaving name empty

4. Consider this Xacro macro call:

<xacro:link_with_length length=""/>

What is the most likely problem with this call if the macro expects a numeric length parameter?

medium

A. The parameter should be named 'size' instead of 'length'

B. The macro name is incorrect

C. The macro call is missing closing tag

D. The length parameter is empty, causing invalid geometry size

Solution

1. Step 1: Check parameter value in macro call

   The call passes length="", which is empty and not a valid number.

2. Step 2: Understand impact on geometry

   The macro uses ${length} for box size, so empty string leads to invalid or zero size, causing errors or unexpected behavior.

3. Final Answer:

   The length parameter is empty, causing invalid geometry size -> Option D

4. Quick Check:

   Empty parameter causes invalid size [OK]

Hint: Always provide valid parameter values in macro calls [OK]

Common Mistakes:

• Ignoring empty parameter values
• Assuming macro name or tag is wrong
• Confusing parameter names

5. You want to create a robot arm with multiple identical segments but different lengths using Xacro macros. Which approach best achieves this?

hard

A. Define a macro with a length parameter and call it multiple times with different lengths

B. Write separate link elements manually for each segment with hardcoded lengths

C. Use a single macro call without parameters and change lengths later in the URDF

D. Create a macro without parameters and duplicate it multiple times

Solution

1. Step 1: Identify the need for reusable segments with different lengths

   You want to reuse the same segment design but customize length for each segment.

2. Step 2: Choose the approach that supports reuse and customization

   Defining a macro with a length parameter and calling it multiple times with different lengths allows reuse and easy updates.

3. Final Answer:

   Define a macro with a length parameter and call it multiple times with different lengths -> Option A

4. Quick Check:

   Reusable macro with parameters [OK]

Hint: Use parameterized macros for repeated parts with variations [OK]

Common Mistakes:

• Duplicating code manually instead of using macros
• Using macros without parameters losing flexibility
• Changing parameters outside macro calls