liminfoURDF Reference
Free reference guide: URDF Reference
About URDF Reference
The URDF Reference is a complete guide to the Unified Robot Description Format used in ROS (Robot Operating System) and Gazebo simulation. It covers link elements in detail: visual geometry for rendering (box, cylinder, sphere, STL/DAE meshes with package:// URI and scale support), collision geometry for physics simulation (simplified shapes recommended for performance), and inertial properties (mass, center of mass, inertia tensor with ixx/iyy/izz formulas for standard shapes like cylinders).
The joint section documents all six URDF joint types: revolute (angle-limited rotation for robot arms), continuous (unlimited rotation for wheels), prismatic (linear translation for lifts and actuators), fixed (rigid sensor mounts), floating (6DOF for drones), and planar (3DOF surface movement). Each type includes the required elements: parent/child links, origin (xyz + rpy), axis, limit (lower/upper/effort/velocity), dynamics (damping/friction), and mimic for coupled gripper fingers.
Advanced sections cover Xacro macros for modular URDF development (xacro:property variables, xacro:macro with params for reusable link/joint templates, xacro:include for file composition, xacro:if/unless conditionals), Gazebo-specific plugins (material colors, diff_drive_controller for mobile robots, camera sensor with FOV/resolution, ray-type LiDAR with 360-degree scanning, ros2_control hardware interface), and complete working examples including a 2-DOF robot arm and URDF validation/build commands (check_urdf, urdf_to_graphiz, xacro conversion).
Key Features
- Link elements: visual (geometry + material), collision (simplified shapes), inertial (mass + inertia tensor formulas)
- Six joint types: revolute, continuous, prismatic, fixed, floating, planar with full parameter specifications
- Geometry primitives (box size, cylinder radius/length, sphere radius) and mesh loading (STL/DAE with scale)
- Joint dynamics: limit (lower/upper/effort/velocity), dynamics (damping/friction), mimic for coupled joints
- Xacro macros: property variables, reusable macro blocks with params, file includes, if/unless conditionals
- Gazebo plugins: diff_drive_controller, camera sensor (640x480 RGB), LiDAR (360-sample ray), ros2_control
- Complete 2-DOF robot arm URDF example with base_link, revolute joints, axis definitions, and limits
- Build and validation commands: xacro conversion, check_urdf, urdf_to_graphiz, RViz visualization launch
Frequently Asked Questions
What are the three sub-elements of a URDF link?
Visual defines rendering geometry (box/cylinder/sphere/mesh) with material colors. Collision defines simplified shapes for physics-based collision checking (use simpler geometry than visual for performance). Inertial specifies mass, center of mass origin, and the 3x3 inertia tensor (ixx, iyy, izz, ixy, ixz, iyz). Inertial is required for Gazebo simulation stability.
What are the six URDF joint types and when do I use each?
Revolute: angle-limited single-axis rotation (robot arm joints). Continuous: unlimited rotation (wheels, rollers). Prismatic: linear translation with position limits (lifts, linear actuators). Fixed: rigid connection without motion (sensor mounts, frames). Floating: 6DOF free movement (drones). Planar: 3DOF on a surface (x, y, yaw).
How do I specify joint limits in URDF?
The <limit> element requires: lower/upper (position range in radians for revolute, meters for prismatic), effort (max torque in Nm for revolute, force in N for prismatic), and velocity (max speed in rad/s or m/s). Example: lower="-3.14" upper="3.14" effort="100" velocity="1.0" for a full-rotation revolute joint.
How do I load custom 3D meshes in URDF?
Use <geometry><mesh filename="package://my_robot/meshes/link.stl" scale="0.001 0.001 0.001" /></geometry>. STL files exported in millimeters need scale="0.001 0.001 0.001" to convert to meters. DAE (Collada) files can include color and texture information. Always use the package:// URI for ROS compatibility.
What are Xacro macros and how do they simplify URDF development?
Xacro (XML Macros) provides: xacro:property for named constants (link_length, joint_effort), xacro:macro for reusable URDF blocks with params (create a cylinder_link macro used multiple times), xacro:include for modular file composition (separate arm, gripper, sensor files), and xacro:if/unless for conditional elements (enable camera only in simulation mode).
How do I set up a differential drive robot in Gazebo?
Use the libgazebo_ros_diff_drive.so plugin with left_joint, right_joint names, wheel_separation and wheel_diameter measurements, max_wheel_torque, command_topic (cmd_vel), and odometry_topic (odom). Set the ros namespace for topic remapping. The plugin handles velocity commands and publishes odometry automatically.
How do I add a camera or LiDAR sensor in Gazebo?
Camera: Add a <sensor type="camera"> to the camera_link with update_rate, horizontal_fov, image resolution (640x480), and the libgazebo_ros_camera.so plugin with frame_name. LiDAR: Use <sensor type="ray"> with horizontal scan parameters (360 samples, -pi to pi), range limits (0.1m to 30m), and libgazebo_ros_ray_sensor.so outputting sensor_msgs/LaserScan.
How do I validate and visualize a URDF file?
Convert xacro to URDF: xacro model.urdf.xacro > model.urdf. Validate syntax: check_urdf model.urdf. Generate joint tree PDF: urdf_to_graphiz model.urdf. Visualize in RViz: ros2 launch urdf_tutorial display.launch.py model:=model.urdf. Use joint_state_publisher_gui to interactively test joint movements.