Chapter 06 · Give the robot an inspectable body, frame tree, and control boundary
Today in the field story
One problem, then the next
The arm model now repeats wheels, fingers, and sensor mounts, so the Warehouse Arm Identity Audit introduces Xacro only where variation is real. Expand every macro, verify unique names and units, and inspect generated output. Record SRDF planning groups as a later semantic layer; never use them to hide a wrong URDF axis, mass, limit, or collision body.
- Why now
Reuse must reduce maintenance without making the physical model opaque.
- Ignore today
Ignore full MoveIt configuration; keep SRDF as an explicitly deferred semantic preview.
- Unlocks next
Deterministic model generation and named components ready for frame publication.
Understand
Build the physical picture first
Xacro is a template maker for robot XML: humans edit the recipe, but every tool downstream must receive and validate the fully expanded URDF.
Plain URDF becomes repetitive when a robot has two wheels, two fingers, or several sensor mounts. Copying a twenty-line link block and changing a few values is an invitation to leave one old name or offset behind. Xacro adds properties, calculations, parameters, macros, includes, and conditionals to XML. A macro can describe one wheel once and instantiate it as left and right with different names and signs. Xacro is a build-time generator; the expanded URDF, not the compact template, is the actual robot model consumed by normal URDF tools.
A useful macro exposes a real variation such as name prefix, wheel side, radius, length, material, or mounting pose. It should not hide essential structure behind a maze of global properties. Every generated link and joint still needs a unique name, and every parent or child reference must point to the intended generated name. Prefixing is especially important when the same module is instantiated twice. Treat expansion like compiling source code: generate the output in an automated check, validate it, and inspect a meaningful diff when parameters change.
Calculations inside Xacro need the same unit discipline as handwritten URDF. A track width of 0.40 m gives wheel y offsets of +0.20 m and −0.20 m when the base frame sits halfway between them. Store the width once, derive both offsets, and make the sign an explicit side parameter. That removes duplicate numbers but does not remove the need for a physical measurement. A calculated value can be consistently wrong if the source property is wrong, so keep measurement provenance and range checks.
SRDF answers different questions from URDF. URDF describes the physical kinematic tree and geometry. An SRDF commonly adds semantic information for motion planning, such as named joint groups, a named home state, end-effectors, virtual joints, or collision pairs known to be safe to ignore. It does not repair a missing URDF link, incorrect axis, bad mass, or wrong transform. Keep semantic planning choices beside—but not mixed up with—the physical model, and expect later MoveIt work to use both.
Words you need
Name each idea precisely
- Xacro property
A named value reused or calculated while generating XML.
Physical example:One measured wheel radius used by both wheel instances.
- Xacro macro
A parameterized XML template that expands into links, joints, or other elements.
Physical example:One wheel template instantiated for the left and right sides.
- Expanded URDF
The ordinary XML robot model produced after Xacro evaluates the recipe.
Physical example:The six uniquely named wheel-and-joint elements a checker sees after two macro calls.
- Name prefix
A caller-supplied string used to keep repeated component names unique.
Physical example:left_ and right_ distinguish two otherwise identical gripper fingers.
- SRDF
A semantic description used with the robot model for concepts such as planning groups and named states.
Physical example:An arm group contains shoulder, elbow, and wrist joints and has a named stowed state.
Math, one line at a time
Work through today’s relationship
Prerequisite rescue · optionalTransforms, joint limits, and command interfaces
A robot model must keep geometry, state, and commands consistent.
- q
- joint positionUnit: rad or m
- q̇
- joint velocityUnit: rad/s or m/s
- limit
- allowed minimum or maximumUnit: same as the value
A joint accepts q from −1.0 rad to +1.0 rad.
A planner asks for 1.2 rad, which exceeds the maximum by 0.2 rad.
Reject it by default before the hardware interface. Clip only when a separate, explicit controller contract authorizes clipping inside a validated envelope and records both the proposal and applied command.
Treat hardware interfaces like typed function contracts with validated ranges, except a broken contract can damage a mechanism.
Is q = −0.8 rad valid for limits [−0.5, 1.0] rad?
No. It is 0.3 rad below the minimum.
For two links,
The conversion must happen before the value enters a model whose unit is metres.
Expand one wheel macro twice without name collisions
A base has track width 0.40 m and two identical wheels of radius 0.08 m. The base frame is centred between them.
Store wheel_radius = 0.08 and track_width = 0.40 as clearly unit-labelled properties.
Define a wheel macro with prefix and side_sign parameters rather than separate left and right copies.
Calculate y = side_sign × track_width / 2, giving +0.20 m for one side and −0.20 m for the other.
Generate link names left_wheel_link and right_wheel_link and joint names left_wheel_joint and right_wheel_joint.
Expand the Xacro and verify that exactly two wheel links and two wheel joints exist with no duplicate identifiers.
Check both origins in the expanded URDF and move each joint independently in the viewer.
One measured width creates two symmetric 0.20 m offsets, while explicit prefixes keep all generated references unique.
Removing duplicated XML is valuable only if the generated model becomes easier—not harder—to inspect.
Physical examples
Where this appears in real life
Mirrored drive wheels
The same wheel shape, mass, radius, and joint type appear on both sides, but the names and lateral offsets differ.
Make the side sign and prefix explicit; do not mirror by copying a block and hoping every old value was changed.
Replaceable camera module
A camera bracket is reused on a base mast and a wrist with different parent links and mounting poses.
The macro should expose parent, prefix, and mount pose while keeping camera geometry and frame naming rules in one place.
Hands-on exercise
Make the idea observable
Start from the Day 36 description and work only with unpowered or simulated geometry.
Identify one genuinely repeated physical module, such as a wheel, finger, caster, or sensor bracket.
Convert that module into a macro whose parameters correspond to measured variations and naming needs.
Generate the plain URDF and save it as a CI artifact or temporary review output.
Validate the expanded model, check unique names, and compare its tree and zero pose with the original working model.
Call the macro twice with the same prefix, observe the validation or tree failure, then restore unique prefixes.
Add a small SRDF note naming one planning group and one safe named state, while explaining why neither belongs in the physical URDF.
Most dangerous template failures are visible only after expansion: duplicate names, wrong parent references, sign errors, or hidden unit calculations.
A reviewer can change one declared dimension, regenerate the model deterministically, and see the exact expected physical differences in the expanded output.
Build today
Model a mobile manipulator in URDF/Xacro/SRDF, wire it to ros2_control, and verify frames, controllers, state, and lifecycle in RViz.
Evidence to save
DONE when “Xacro, SRDF, and reusable robot descriptions” runs from one documented command and the nominal plus boundary outputs are attached.
Common mistakes
Catch the wrong mental model
Reviewing only the compact Xacro because it looks clean.
Generate, validate, and inspect the expanded URDF that downstream components actually consume.
Using shared global properties for every value in the model.
Pass real component variations as explicit macro parameters and keep local calculations close to their use.
Putting planning groups into URDF or using SRDF to hide bad geometry.
Keep physical structure and geometry in URDF; keep supported semantic planning information in SRDF.
Job connection
How this becomes employable evidence
Maintain a reusable description package for several robot variants while CI expands every supported configuration, rejects duplicate names, and checks known physical dimensions.
Relevant target roles
- Robotics Deployment, Integration & Validation Engineer
- Robotics Application / ROS 2 Integration Engineer
- Robotics Software Engineer — ROS 2 / AMR
Chapter 06 interview drill
Interview questions: Xacro, SRDF, and reusable robot descriptions
Practise a 60–90 second answer: define the idea, connect it to a physical robot, state assumptions, frames, and units when relevant, then finish with the failure signal or evidence you would inspect.
Primary interview scenario
When would you introduce a Xacro macro, what would you expose as parameters, and how would you stop a template error from silently changing every robot variant?
Answer shape: clarify the situation → trace the physical and software path → test the most likely boundaries → name the evidence that would confirm the result.
Technical follow-up questions
Q1What file should the normal URDF validator inspect when you author with Xacro?
The fully expanded ordinary URDF generated from the Xacro input.
Q2Why does a repeated module need a name prefix parameter?
Each generated link and joint must be unique, and every generated reference must point to the correct instance.
Q3Name one thing appropriate for SRDF but not a replacement for URDF.
A semantic arm planning group or named home state; it does not replace the physical link-and-joint tree.