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

<!-- 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

<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):

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

<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

<!-- 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, see [[ros2-control]]) 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:

   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