Urdf Xacro Builder

---
name: urdf-xacro-builder
description: Use when authoring or modifying URDF/Xacro robot descriptions — modular macro structure, link/joint kinematics, inertia tensor calculation, Gazebo physics/material tags, and safety checks before running check_urdf.
---

# URDF / Xacro Robot Description Builder

Rules and templates for producing modular, physically valid, simulation-ready Xacro robot
descriptions.

## 1. Modular file structure

Never write one monolithic `.urdf` file. Split by concern and `xacro:include` them from a
single top-level entry point:

```
my_robot_description/
├── urdf/
│   ├── my_robot.urdf.xacro          # top-level: includes everything below
│   ├── my_robot.materials.xacro     # <material> color/texture definitions
│   ├── my_robot.core.xacro          # base_link, chassis links/joints
│   ├── my_robot.wheels.xacro        # xacro:macro for a wheel, instantiated per wheel
│   ├── my_robot.sensors.xacro       # lidar/camera/imu links + <gazebo> sensor plugins
│   └── my_robot.gazebo.xacro        # ros2_control + <gazebo> friction/plugin tags
└── meshes/
    ├── visual/
    └── collision/                    # simplified geometry, separate from visual meshes
```

```xml
<!-- my_robot.urdf.xacro -->
<?xml version="1.0"?>
<robot name="my_robot" xmlns:xacro="http://www.ros.org/wiki/xacro">
  <xacro:include filename="$(find my_robot_description)/urdf/my_robot.materials.xacro"/>
  <xacro:include filename="$(find my_robot_description)/urdf/my_robot.core.xacro"/>
  <xacro:include filename="$(find my_robot_description)/urdf/my_robot.wheels.xacro"/>
  <xacro:include filename="$(find my_robot_description)/urdf/my_robot.sensors.xacro"/>
  <xacro:include filename="$(find my_robot_description)/urdf/my_robot.gazebo.xacro"/>
</robot>
```

Rules:
- One `<robot>` root tag, only in the top-level file — never in included fragments.
- Reusable structures (wheels, sensor mounts) are `xacro:macro` blocks parameterized by name
  and pose, instantiated once per instance, never copy-pasted with renamed links.
- `xacro:property` for every numeric constant that's reused (wheel radius, chassis mass) —
  never a duplicated magic number.

## 2. Link and joint kinematics

```xml
<xacro:macro name="wheel" params="prefix parent_link *origin">
  <link name="${prefix}_wheel_link">
    <visual>
      <geometry><cylinder radius="${wheel_radius}" length="${wheel_width}"/></geometry>
      <material name="black"/>
    </visual>
    <collision>
      <geometry><cylinder radius="${wheel_radius}" length="${wheel_width}"/></geometry>
    </collision>
    <xacro:cylinder_inertia mass="${wheel_mass}" radius="${wheel_radius}" length="${wheel_width}"/>
  </link>

  <joint name="${prefix}_wheel_joint" type="continuous">
    <parent link="${parent_link}"/>
    <child link="${prefix}_wheel_link"/>
    <xacro:insert_block name="origin"/>
    <axis xyz="0 1 0"/>
    <limit effort="10.0" velocity="20.0"/>
    <dynamics damping="0.1" friction="0.05"/>
  </joint>
</xacro:macro>
```

Rules:
- Exactly one root link in the whole tree (usually `base_link`, per REP 105) — URDF is a tree,
  never a graph; a link with two parents will fail `check_urdf`.
- `base_link` itself should carry no visual/collision/inertial geometry when the robot has a
  distinct `base_footprint` frame at ground level; otherwise `base_link` is the chassis and
  does carry them. Pick one convention and apply it consistently across the whole robot.
- Every joint's `<axis>` follows the right-hand rule relative to its own frame, not the world
  frame — a `continuous` wheel joint typically rotates about its local Y or X, not Z.
- `<origin xyz="..." rpy="...">` on every joint is relative to the **parent** link's frame.
  Never omit it (an omitted origin silently defaults to zero, which is rarely what's intended
  once a robot has more than a couple of links).
- Every non-fixed joint (`revolute`, `prismatic`) MUST have a `<limit>` with `lower`, `upper`,
  `effort`, and `velocity`. `continuous` joints have no position limits but still need
  `effort`/`velocity` — a missing velocity limit is a real safety gap once this URDF drives
  `ros2_control` hardware.
- Give every moving joint `<dynamics damping="..." friction="...">` — omitting it makes physics
  engines (and `ros2_control` simulated hardware) behave unrealistically stiff or unstable.

## 3. Inertia tensor calculation

Never leave `<inertial>` at placeholder/identity values — an incorrect or singular inertia
tensor is the single most common cause of an unstable or NaN-diverging Gazebo simulation.

Standard closed-form formulas (mass `m`, principal axes aligned with the link's local frame):

| Shape | Ixx | Iyy | Izz |
|---|---|---|---|
| Solid box (x,y,z dims) | `m(y²+z²)/12` | `m(x²+z²)/12` | `m(x²+y²)/12` |
| Solid cylinder (radius r, length h, axis = z) | `m(3r²+h²)/12` | `m(3r²+h²)/12` | `mr²/2` |
| Solid sphere (radius r) | `2mr²/5` | `2mr²/5` | `2mr²/5` |

Xacro macros to compute these directly so no author hand-calculates them:

```xml
<xacro:macro name="box_inertia" params="mass x y z">
  <inertial>
    <mass value="${mass}"/>
    <inertia ixx="${mass*(y*y+z*z)/12}" ixy="0" ixz="0"
             iyy="${mass*(x*x+z*z)/12}" iyz="0"
             izz="${mass*(x*x+y*y)/12}"/>
  </inertial>
</xacro:macro>

<xacro:macro name="cylinder_inertia" params="mass radius length">
  <inertial>
    <mass value="${mass}"/>
    <inertia ixx="${mass*(3*radius*radius+length*length)/12}" ixy="0" ixz="0"
             iyy="${mass*(3*radius*radius+length*length)/12}" iyz="0"
             izz="${mass*radius*radius/2}"/>
  </inertial>
</xacro:macro>

<xacro:macro name="sphere_inertia" params="mass radius">
  <inertial>
    <mass value="${mass}"/>
    <inertia ixx="${2*mass*radius*radius/5}" ixy="0" ixz="0"
             iyy="${2*mass*radius*radius/5}" iyz="0"
             izz="${2*mass*radius*radius/5}"/>
  </inertial>
</xacro:macro>
```

Rules (safety checks to apply before trusting an `<inertial>` block):
- `mass` > 0 always. A zero or negative mass is physically invalid and will produce NaNs in
  simulation.
- `Ixx`, `Iyy`, `Izz` > 0 (positive-definite diagonal). A zero principal moment means the solver
  treats that axis as having no rotational inertia at all.
- Triangle inequality on principal moments: `Ixx + Iyy >= Izz` (and both other permutations).
  If it's violated, the geometry/mass combination is not physically realizable and usually
  indicates a units mistake (e.g. dimensions in millimeters fed into a meter-based formula).
- For composite/irregular links (a chassis with mounted electronics), either approximate with
  one dominant primitive shape's inertia or sum the parallel-axis-theorem-shifted inertias of
  several primitives — never leave a complex link at a default/copied inertia from an unrelated
  link.

## 4. Gazebo physics and material tags

```xml
<!-- my_robot.gazebo.xacro -->
<gazebo reference="${prefix}_wheel_link">
  <mu1>1.0</mu1>
  <mu2>1.0</mu2>
  <material>Gazebo/Black</material>
</gazebo>

<gazebo reference="base_link">
  <material>Gazebo/Grey</material>
</gazebo>

<ros2_control name="my_robot_system" type="system">
  <hardware>
    <plugin>gz_ros2_control/GazeboSimSystem</plugin>
  </hardware>
  <joint name="left_wheel_joint">
    <command_interface name="velocity"/>
    <state_interface name="velocity"/>
    <state_interface name="position"/>
  </joint>
  <joint name="right_wheel_joint">
    <command_interface name="velocity"/>
    <state_interface name="velocity"/>
    <state_interface name="position"/>
  </joint>
</ros2_control>

<gazebo>
  <plugin filename="gz_ros2_control-system" name="gz_ros2_control::GazeboSimROS2ControlPlugin">
    <parameters>$(find my_robot_bringup)/config/controllers.yaml</parameters>
  </plugin>
</gazebo>
```

Rules:
- Every `<gazebo reference="link_name">` must reference a link that actually exists in the
  URDF — a typo here fails silently (Gazebo just ignores the unmatched tag) rather than raising
  an error, so double-check names against the `<link>` definitions.
- Set friction (`mu1`/`mu2`) explicitly on any link that touches the ground (wheels, feet) —
  the physics engine default is rarely appropriate for a wheeled or legged robot.
- Keep the `<ros2_control>` hardware plugin swappable: use `gz_ros2_control/GazeboSimSystem`
  for simulation and a real hardware plugin (e.g. a custom `SystemInterface`) for the physical
  robot, selected via a launch argument — never hardcode simulation-only tags in a file also
  used on hardware.
- Collision geometry should be simplified primitives or a decimated mesh, never the full-detail
  visual mesh — using the visual mesh as collision geometry is a common cause of extremely slow
  or unstable physics stepping.

## 5. Pre-flight safety checks (before trusting the model)

Verify all of the following before considering a URDF/Xacro file done — this plugin's
`verify_urdf` hook automatically runs `xacro` + `check_urdf` on save, but these structural
checks go beyond what `check_urdf` catches:

1. Exactly one root link (no cycles, no disconnected sub-trees).
2. No duplicate `link` or `joint` names anywhere in the expanded URDF.
3. Every non-fixed joint has `<limit>` with sane `effort`/`velocity` (and `lower`/`upper` for
   non-continuous types).
4. Every link with physical presence has `mass > 0` and a positive-definite inertia tensor
   (see §3) — purely virtual/frame-only links (e.g. a `*_optical_frame` for a camera) may
   validly omit `<inertial>`.
5. Collision geometry is simpler than visual geometry for every link with a mesh.
6. Run the actual tools before declaring success:
   ```bash
   xacro my_robot.urdf.xacro -o /tmp/my_robot.urdf
   check_urdf /tmp/my_robot.urdf
   urdf_to_graphiz /tmp/my_robot.urdf   # visualize the tree, spot unintended disconnections
   ```