URDF: Building FollowBot's Digital Twin
Wrong inertial parameters in a URDF will make your simulation oscillate — and you will not find the bug for three days.
🎯 By the end you'll understand
The URDF link-joint hierarchy and why it maps directly to the TF tree you built in Lesson 1.2. How to specify visual versus collision geometry, and why they can and should differ. How to compute inertia tensors analytically for box, cylinder, and sphere primitives — and what happens to your simulation if you get them wrong by a factor of ten. How xacro macros eliminate the repetition that makes raw URDF unmaintainable. How to publish the robot description and visualize it in RViz2. And the single most common cause of simulated robot instability that has no counterpart on real hardware.
KEY INSIGHTA URDF is a physics contract, not just a visualization asset
The simulation doesn't care whether your robot looks right. It cares whether your inertia tensors are right. A robot that looks identical to FollowBot but has mass distributed incorrectly will tumble, oscillate, and behave in ways the real hardware never does — and the URDF will pass validation just fine.
Most robotics tutorials introduce URDF as a way to visualize your robot in RViz. That framing is dangerous. URDF is a formal specification of a mechanical system. Every link has mass and rotational inertia. Every joint has limits and dynamics. When you load a URDF into Gazebo, those numbers are fed directly into the rigid-body physics engine (ODE or Bullet). The simulation's fidelity — and therefore its usefulness for algorithm development — depends entirely on how accurately those numbers describe the real hardware.
Practitioners spend enormous effort closing the sim-to-real gap in perception and control. Almost no one talks about the mechanical sim-to-real gap — the divergence between simulated and real physics that comes from incorrect URDF parameters. Incorrect inertia tensors don't produce a warning, a crash, or even a clearly wrong behavior. They produce a robot that is subtly unstable: it oscillates when it should settle, it drifts when it should hold position, it tips when it should stay upright. You debug the control gains, the EKF noise model, the planner — none of which are at fault. The error was in the <inertial> block, authored three days ago and never questioned again.
HOW IT WORKSLinks, joints, and the kinematic tree
A URDF describes a robot as a tree of rigid bodies connected by joints. This structure maps directly to the TF tree introduced in Lesson 1.2: each link corresponds to a coordinate frame, and each joint defines the transform between parent and child frames.
<link>; every edge is a <joint>. base_link is the root — this is the frame that odom tracks in the TF tree. Sensor links (laser, camera) use fixed joints because they don't move relative to the chassis.The URDF XML structure mirrors this tree precisely. A minimal link looks like this:
<!-- Every robot link has three sub-elements --> <link name="base_link"> <!-- 1. Visual: shown in RViz, not used by physics --> <visual> <geometry> <box size="0.35 0.30 0.12"/> <!-- x y z in metres --> </geometry> <origin xyz="0 0 0.06" rpy="0 0 0"/> <material name="dark_grey"/> </visual> <!-- 2. Collision: used by Gazebo collision detection --> <collision> <geometry> <box size="0.35 0.30 0.12"/> <!-- often simpler than visual --> </geometry> <origin xyz="0 0 0.06" rpy="0 0 0"/> </collision> <!-- 3. Inertial: fed to physics engine — get this WRONG and pay --> <inertial> <mass value="4.5"/> <!-- kg --> <origin xyz="0 0 0.06"/> <!-- centre of mass offset --> <inertia ixx="0.0391" iyy="0.0513" izz="0.0797" ixy="0" ixz="0" iyz="0"/> <!-- kg·m² --> </inertial> </link>
Joints connect links and define how they move relative to each other:
<!-- Continuous joint: wheel spins freely around its axis --> <joint name="left_wheel_joint" type="continuous"> <parent link="base_link"/> <child link="left_wheel"/> <origin xyz="0 0.175 0" rpy="-1.5708 0 0"/> <!-- -90° so z=spin axis --> <axis xyz="0 0 1"/> </joint> <!-- Fixed joint: LIDAR doesn't move relative to chassis --> <joint name="laser_joint" type="fixed"> <parent link="base_link"/> <child link="laser"/> <origin xyz="0.12 0 0.18" rpy="0 0 0"/> <!-- 12 cm forward, 18 cm up --> </joint>
URDF defines six joint types. fixed: no motion, used for sensors and structural parts. continuous: rotates freely around an axis, no limits — used for drive wheels. revolute: rotates around an axis with upper/lower limits — used for arm joints. prismatic: slides along an axis with limits. floating: unconstrained 6-DOF, rarely used in links (mostly for floating-base robots). planar: motion in a plane. For FollowBot: wheels are continuous, sensors are fixed, arm joints (future stage) are revolute.
CORE CONCEPTInertia tensors: the math the physics engine actually uses
The <inertial> block contains three things: mass (a scalar), center of mass position (a 3D vector), and the inertia tensor (a 3×3 symmetric matrix). The physics engine uses these at every simulation timestep — typically at 1000 Hz — to integrate Newton's equations of motion. If these numbers are wrong, every simulated force and torque computation is wrong.
The inertia tensor in URDF is specified as six values because the tensor is symmetric: ixx, iyy, izz are the diagonal (principal) moments, and ixy, ixz, iyz are the off-diagonal products of inertia. For primitives whose geometry is aligned with the frame axes (and assuming uniform density), all off-diagonal terms are zero. The diagonal terms are:
Physical intuition: the moment of inertia around an axis measures how much torque you need to produce a given angular acceleration around that axis. A high Izz means the robot resists yaw strongly — it takes more torque to spin it. For FollowBot's chassis (a roughly flat box), Izz is the largest moment because most of the mass is spread out in the x-y plane, far from the z-axis. Ixx and Iyy are smaller because the chassis is thin in z.
A surprisingly common URDF authoring error: omit the <inertial> block, assuming the simulator will use a default. Gazebo and the ODE physics engine do not default to "reasonable" — they treat missing inertia as zero. A zero-mass or zero-inertia link is a division-by-zero in the physics integration. The simulation typically crashes or explodes immediately, which is at least loud. The silent variant: set ixx=iyy=izz=0.001 as a placeholder and never come back to fix it. For a 4.5 kg chassis, the correct Izz is ~0.080 kg·m². Setting it to 0.001 (an 80× error) will make the robot spin almost frictionlessly around its vertical axis — the torque model is completely wrong.
SEE ITURDF inertia explorer — build FollowBot's chassis, get the physics right
Configure FollowBot's chassis geometry and mass. The widget computes the correct inertia tensor analytically and simulates the robot's angular response to a step torque disturbance. Then use the "Inject 10× error" button to see what an incorrect (but plausible-looking) inertia does to simulated stability.
Notice that the 10× error simulation doesn't immediately crash — it produces a plausible-looking response that is simply too sensitive. In Gazebo, this manifests as oscillation that appears to be a control tuning problem. The URDF value is never questioned because it is still a valid positive-definite tensor.
IN PRACTICEXacro macros: making URDF maintainable
A real robot URDF for even a simple differential-drive base exceeds 500 lines of raw XML. Two wheels, one chassis, one caster, two sensors, a 6-DOF arm — with visual, collision, and inertial blocks each — produces thousands of lines of repetitive, error-prone XML. Xacro (XML macro language) solves this with two key features: properties (named constants) and macros (parameterized XML templates).
<?xml version="1.0"?> <robot name="followbot" xmlns:xacro="http://www.ros.org/wiki/xacro"> <!-- Named constants — change here, propagates everywhere --> <xacro:property name="chassis_mass" value="4.5"/> <xacro:property name="chassis_length" value="0.35"/> <xacro:property name="chassis_width" value="0.30"/> <xacro:property name="chassis_height" value="0.12"/> <xacro:property name="wheel_mass" value="0.4"/> <xacro:property name="wheel_radius" value="0.0325"/> <xacro:property name="wheel_width" value="0.025"/> <xacro:property name="wheel_separation" value="0.35"/> <!-- Macro: one definition, used twice (left + right) --> <xacro:macro name="wheel" params="prefix y_reflect"> <link name="${prefix}_wheel"> <visual> <geometry><cylinder radius="${wheel_radius}" length="${wheel_width}"/></geometry> </visual> <collision> <geometry><cylinder radius="${wheel_radius}" length="${wheel_width}"/></geometry> </collision> <inertial> <mass value="${wheel_mass}"/> <!-- Cylinder inertia: Ixx=Iyy=m(3r²+h²)/12, Izz=mr²/2 --> <inertia ixx="${wheel_mass*(3*wheel_radius**2+wheel_width**2)/12}" iyy="${wheel_mass*(3*wheel_radius**2+wheel_width**2)/12}" izz="${wheel_mass*wheel_radius**2/2}" ixy="0" ixz="0" iyz="0"/> </inertial> </link> <joint name="${prefix}_wheel_joint" type="continuous"> <parent link="base_link"/> <child link="${prefix}_wheel"/> <origin xyz="0 ${y_reflect*wheel_separation/2} 0" rpy="-1.5708 0 0"/> <axis xyz="0 0 1"/> </joint> </xacro:macro> <!-- Instantiate: one macro call per wheel --> <xacro:wheel prefix="left" y_reflect="1"/> <xacro:wheel prefix="right" y_reflect="-1"/> </robot>
The critical feature in this xacro: the inertia values are computed inline from the geometric parameters using xacro's math support. Change wheel_radius and the inertia tensor updates automatically. This is the correct workflow — the geometry and the inertia stay in sync by construction, not by manual recalculation.
Process the xacro file into a plain URDF (for tools that don't support xacro directly) with:
# Install xacro if needed sudo apt install ros-humble-xacro # Process xacro → URDF xacro followbot.xacro > followbot.urdf # Validate the output check_urdf followbot.urdf
IN PRACTICEPublishing the robot description and visualizing in RViz2
In ROS 2, the URDF is distributed as the robot_description parameter on the robot_state_publisher node. This node reads the URDF, subscribes to /joint_states, and publishes all link transforms to the /tf topic. The entire TF tree you learned about in Lesson 1.2 is generated by this single node from the URDF.
import os from ament_index_python.packages import get_package_share_directory from launch import LaunchDescription from launch_ros.actions import Node import xacro def generate_launch_description(): pkg = get_package_share_directory('followbot_description') xacro_path = os.path.join(pkg, 'urdf', 'followbot.xacro') # Process xacro at launch time — no stale URDF to keep in sync robot_desc = xacro.process_file(xacro_path).toxml() return LaunchDescription([ Node( package='robot_state_publisher', executable='robot_state_publisher', parameters=[{'robot_description': robot_desc}], ), # joint_state_publisher_gui for manual joint testing Node( package='joint_state_publisher_gui', executable='joint_state_publisher_gui', ), ])
Launch the description publishers
Run ros2 launch followbot_description followbot_description.launch.py. This starts robot_state_publisher (which publishes static TF transforms for fixed joints and dynamic ones from /joint_states) and the GUI node that lets you drag wheel angles manually.
Open RViz2 and add the RobotModel display
Run rviz2. Add a RobotModel display (Displays → Add → By display type → RobotModel). Set its Topic to /robot_description. Set Fixed Frame to base_link. FollowBot's chassis, wheels, and sensors should appear.
Verify the TF tree
Add a TF display. You should see frames for base_link, left_wheel, right_wheel, laser, and camera. Run ros2 run tf2_tools view_frames to generate a PDF of the full TF tree. Cross-check that every frame in the URDF appears in the tree — missing frames indicate a malformed joint.
Check the inertial parameters with a sanity tool
Install the xacro-inertia tool: pip install urdf-parser-py. Run python3 -c "import urdf_parser_py.urdf as urdf; r=urdf.URDF.from_xml_file('followbot.urdf'); [print(l.name, l.inertial.mass if l.inertial else 'NO INERTIAL') for l in r.links]". Any link with NO INERTIAL printed next to it will explode in Gazebo.
Visual geometry can be a detailed mesh (a .dae or .stl file) for aesthetics. Collision geometry should be the simplest convex hull that is a reasonable approximation of the real shape. Simulating collision between two complex meshes is expensive and often numerically unstable. For FollowBot's chassis: visual geometry is a detailed box with chamfers (a mesh); collision geometry is a plain <box> primitive. The LIDAR sensor link uses a <cylinder> for collision regardless of what the real LIDAR looks like. Simulation speed is proportional to collision geometry simplicity.
FOLLOWBOTFollowBot's complete URDF: the Stage 1 milestone
At this point in the course you have all the pieces to write FollowBot's full URDF. The Stage 1 milestone is: a working URDF (or xacro) that when launched produces a complete TF tree, visualizes in RViz2, and loads without physics explosions in Gazebo. Here is the full link and joint inventory, with correct inertial parameters:
| Link | Geometry | Mass (kg) | Izz (kg·m²) | Joint type | Parent |
|---|---|---|---|---|---|
| base_link | box 0.35×0.30×0.12 | 4.5 | 0.0797 | — (root) | — |
| left_wheel | cylinder r=0.0325, h=0.025 | 0.4 | 0.00021 | continuous | base_link |
| right_wheel | cylinder r=0.0325, h=0.025 | 0.4 | 0.00021 | continuous | base_link |
| caster_wheel | sphere r=0.025 | 0.05 | 0.0000125 | fixed | base_link |
| laser | cylinder r=0.04, h=0.06 | 0.18 | 0.000144 | fixed | base_link |
| camera | box 0.025×0.09×0.025 | 0.07 | 0.0000118 | fixed | base_link |
The TF tree this URDF produces (when robot_state_publisher is running) is exactly the sub-tree from base_link downward in the full frame graph from Lesson 1.2. The frames above base_link — odom and map — are added by the odometry node and the localization stack respectively, not by the URDF.
The URDF milestone is not "the robot looks right in RViz." It means: (1) check_urdf followbot.urdf passes. (2) Every link with a non-trivial mass has a correct <inertial> block — computed from the formula, not guessed. (3) The TF tree from ros2 run tf2_tools view_frames matches the kinematic tree diagram above, including all sensor frames. (4) Gazebo spawns the robot without immediately exploding or oscillating at rest. (5) The /joint_states topic publishes left_wheel and right_wheel positions when you manually command wheel velocities. Only then is the digital twin ready to be driven by the differential-drive kinematics you'll develop in Lesson 2.1.
The xacro workflow for the full FollowBot description is organized as:
followbot_description/
urdf/
followbot.xacro # top-level: includes all sub-files
materials.xacro # color definitions
base.xacro # chassis + caster
wheels.xacro # wheel macro + instantiations
sensors.xacro # laser + camera links + joints
gazebo_plugins.xacro # diff_drive + sensor plugins for Gazebo
meshes/
chassis_visual.dae # optional: detailed visual mesh
launch/
display.launch.py # RViz2 preview
gazebo.launch.py # Gazebo spawn
rviz/
followbot.rviz # saved RViz2 config
WEAKNESSWhere URDF authoring bites
This is the lesson's central failure mode and deserves full description. Inertia tensors that are too large (by 2–10×) do not crash the simulation — they produce a robot that is too resistant to angular acceleration. In Gazebo's physics engine, this means the controller must apply more torque than the real hardware would need to achieve the same motion. The result: your controllers are tuned in simulation, transferred to real hardware, and the robot behaves completely differently — not because of the usual sim-to-real issues (perception, floor friction, tire compliance) but because the physics engine was running a different robot. Inertia tensors that are too small (including near-zero) cause a different failure: the robot is hypersensitive to torques and oscillates wildly. The way to catch this is a sanity check: compute the expected angular natural frequency of the robot as a rigid body. For FollowBot with Izz ≈ 0.0797 kg·m² and a controller that applies ≈ 1 N·m per radian of heading error, the natural frequency is √(1/0.0797) ≈ 3.5 rad/s. If your simulated robot oscillates at 20+ rad/s with the same controller, your Izz is too small.
Visual meshes (from CAD software) routinely have 10,000–100,000 faces. Using the same mesh for collision geometry means Gazebo's collision detection — which runs at 1000 Hz — must compute intersections between those faces. Simulations with complex collision meshes run at 10–30% of real time, making reinforcement learning and long-horizon planning tests impractical. The fix is always to use primitive geometry (<box>, <cylinder>, <sphere>) for collision, regardless of visual complexity. A differential-drive robot is well approximated by a cylinder collision footprint. The only exception: if your robot's exact shape matters for collision (a robot arm with fine manipulation tasks), use the minimum number of convex hull primitives, not the raw mesh.
The robot_state_publisher publishes two types of transforms: static transforms for fixed joints (published once, permanently), and dynamic transforms for movable joints (published per incoming /joint_states message). A common mistake: add a new revolute or continuous joint in the URDF but don't update the node that publishes to /joint_states. The joint exists in the URDF but its transform is never published — RViz shows the child link at the default (origin) position regardless of actual joint state, and any algorithm that consumes TF data gets incorrect link positions. The symptom: everything looks fine in RViz when the robot is stationary, but sensor data appears to come from the wrong location as soon as the robot moves.
KEY INSIGHTHow this connects
- Coordinate Frames and Homogeneous Transforms (1.2) — every joint origin and axis in a URDF is a coordinate frame transform in SE(3). The URDF kinematic tree is the static structure that
robot_state_publisherpopulates to build the TF tree you studied there. - Rotation Representations: Matrices, Euler Angles, and Quaternions (1.3) — URDF uses roll-pitch-yaw (rpy) in joint and link origins. The rpy convention maps to rotation matrices via the same formulas from Lesson 1.3. When debugging why a sensor frame looks wrong in RViz, you are debugging rpy values.
- FollowBot System Architecture: Requirements to Block Diagram (1.8) — the system architecture lesson specified what links and sensors FollowBot must have. This lesson implements that specification as a formal URDF, closing the loop between requirements and model.
- Differential Drive Kinematics: FollowBot's Motion Model (2.1) — the next lesson. The kinematic model uses the wheel separation and wheel radius parameters that are defined in the URDF. A URDF with incorrect wheel dimensions will produce a kinematics model that disagrees with the simulation. Start Stage 2 with the URDF verified.
The URDF is the single source of truth for FollowBot's physical description. Everything downstream — the TF tree, the kinematics model, the dynamics simulation, the collision avoidance footprint — consumes the URDF. Errors here propagate into every stage of the course and the real robot. A correct URDF built once carefully is an investment; a URDF authored quickly and never validated is a debt you will pay for the rest of the project.
GLOSSARYKey terms introduced
- URDF (Unified Robot Description Format)
- An XML format for describing a robot as a tree of rigid links connected by joints. Specifies visual geometry (for visualization), collision geometry (for physics simulation), and inertial parameters (for dynamics). The standard robot description format in ROS 2.
- Inertia tensor
- A 3×3 symmetric matrix that describes how a rigid body resists rotational acceleration around each axis and across axes. In URDF, specified as six values: ixx, iyy, izz (diagonal moments) and ixy, ixz, iyz (off-diagonal products of inertia). Incorrect values are the most common cause of simulated instability.
- Xacro
- An XML macro language that extends URDF with properties (named constants), macros (parameterized XML templates), and math expressions. Eliminates repetition and keeps geometry and inertial parameters consistent by computing inertia analytically from the same variables that define the geometry.
- robot_state_publisher
- A ROS 2 node that reads a URDF from the
robot_descriptionparameter, subscribes to/joint_states, and publishes all link transforms to/tfand/tf_static. The single node that generates FollowBot's entire TF tree from the URDF. - Principal moment of inertia
- The diagonal elements of the inertia tensor (Ixx, Iyy, Izz) when the tensor is expressed in a frame aligned with the body's principal axes. For a uniform-density primitive with geometry aligned to the frame axes, the off-diagonal (product of inertia) terms are zero.
- Parallel axis theorem
- A theorem that relates a body's moment of inertia around any axis to its moment around a parallel axis through the center of mass: I = I_cm + m·d², where d is the perpendicular distance between the axes. Used in URDF when the link's coordinate origin does not coincide with its center of mass.
- Collision geometry
- The geometric shape used by the physics engine for collision detection between links. Should be the simplest convex primitive that reasonably approximates the real shape. Distinct from visual geometry, which can be a complex mesh for rendering purposes only.
- Fixed joint
- A URDF joint type that allows no motion between parent and child links. Used for sensors, structural attachments, and any link that is rigidly mounted. robot_state_publisher publishes the transform for a fixed joint once as a static TF broadcast, not as a dynamic update.
ACTIVE RECALLCheck your understanding
Answer in your own words first, then reveal.
1What are the three sub-elements of a URDF link, and which one does the physics engine use?›
A URDF link has three sub-elements: visual (geometry used for display in RViz — can be a complex mesh), collision (geometry used by the physics engine for contact detection — should be simple primitives), and inertial (mass, center-of-mass location, and inertia tensor — used by the physics engine to integrate rigid-body dynamics). The physics engine uses both collision and inertial. The visual element is ignored by Gazebo during simulation — it only matters for RViz rendering.
2FollowBot's chassis is a box of dimensions 0.35 m × 0.30 m × 0.12 m with mass 4.5 kg. What is Izz, and why is it the largest principal moment?›
For a uniform box with dimensions l (x), w (y), h (z): Izz = m(l² + w²)/12 = 4.5 × (0.35² + 0.30²) / 12 = 4.5 × (0.1225 + 0.09) / 12 = 4.5 × 0.2125 / 12 ≈ 0.0797 kg·m². (The widget uses slightly different rounding.) Izz is the largest moment because it resists rotation around the vertical (z) axis, and most of the chassis mass is spread out in the x-y plane — far from the z-axis — contributing maximum moment. Ixx and Iyy are smaller because the chassis is thin in the z direction, so rotating around x or y requires less torque.
3Why should you set ixy=ixz=iyz=0 for a box, cylinder, or sphere whose geometry is aligned with the link frame axes?›
The off-diagonal terms (products of inertia) of the inertia tensor are zero when the coordinate frame is aligned with the body's principal axes — the axes of symmetry of the mass distribution. All three primitive types (box, cylinder, sphere) are symmetric about their coordinate axes when centered at the origin with geometry aligned to the frame. For a box, the x-z plane is a plane of symmetry, so there is no tendency to rotate around y when torqued around x — Ixy = 0 by symmetry. The same argument applies to all six off-diagonal combinations. If you set non-zero off-diagonal values for a perfectly aligned primitive, you are telling the physics engine the robot has an asymmetric mass distribution that doesn't exist — it will simulate nonexistent coupling between rotation axes.
4Your FollowBot simulation oscillates when it should hold position. You've already re-tuned the PID controller three times and it hasn't helped. What URDF parameter should you check, and how would you diagnose it?›
Check the inertia tensor values in the <inertial> block of the oscillating link. A URDF inertia that is too small (e.g., near zero, or a placeholder 0.001) makes the link hypersensitive to torques — small control inputs produce large angular accelerations, and the controller perpetually overshoots and oscillates. To diagnose: compute the analytically correct values from the geometry (using the formulas in this lesson) and compare to what is in the URDF. Also compute the expected natural frequency: ω = √(K/I) where K is the effective torque gain and I is the relevant moment. If the simulated oscillation frequency is much higher than this estimate, the inertia is too small. Fix: replace the URDF values with the analytically correct ones (or switch to a xacro that computes them inline). Do not re-tune the PID — the controller is not the problem.