urdf-fundamentals

# URDF Fundamentals Skill This skill provides comprehensive guidance on creating, structuring, and validating URDF (Unified Robot Description Format) files for robot descriptions. ## When to Use This Skill Use this skill when: - Creating a new URDF from scratch - Understanding URDF/Xacro syntax and structure - Designing kinematic chains and joint hierarchies - Adding links, joints, or coordinate frames - Debugging URDF validation errors - Implementing inertial properties and mass - Understanding and using package paths and mesh references ## URDF File Structure ### Basic Robot Structure Every URDF file has this basic structure: ```xml <?xml version="1.0"?> <robot name="robot_name"> <!-- Define links (rigid bodies) --> <link name="base_link"> <!-- Visual geometry for rendering --> <visual> <geometry> <box size="0.5 0.3 0.1"/> </geometry> <material name="blue"> <color rgba="0 0 1 1"/> </material> </visual> <!-- Collision geometry for physics --> <collision> <geometry> <box size="0.5 0.3 0.1"/> </geometry> </collision> <!-- Inertial properties for dynamics --> <inertial> <mass value="5.0"/> <inertia ixx="0.1" ixy="0" ixz="0" iyy="0.1" iyz="0" izz="0.1"/> </inertial> </link> <!-- Define joints (connections between links) --> <joint name="base_to_wheel" type="continuous"> <parent link="base_link"/> <child link="wheel_link"/> <origin xyz="0.2 0.2 0" rpy="0 1.57 0"/> <axis xyz="0 1 0"/> </joint> <!-- Define other links --> <link name="wheel_link"> <!-- ... geometry ... --> </link> </robot> ``` ### Key Elements **`<link>`** - Represents a rigid body in the robot: - `name` - Unique identifier - Usually contains: `<visual>`, `<collision>`, `<inertial>` elements - The first link is typically the "base_link" (root of kinematic chain) **`<joint>`** - Represents a connection between two links: - `name` - Unique identifier - `type` - Joint type (revolute, continuous, prismatic, fixed, etc.) - `<parent>` - Parent link name - `<child>` - Child link name - `<origin>` - Relative position and orientation - `<axis>` - Direction and rotation/translation axis - `<limit>` - Joint constraints (for movable joints) **`<origin>`** - Specifies relative pose: - `xyz` - Position (x, y, z in meters) - `rpy` - Orientation (roll, pitch, yaw in radians) ## Links in Detail ### Visual Geometry Used for display and rendering: ```xml <link name="example_link"> <visual> <!-- Geometry type and dimensions --> <geometry> <box size="x y z"/> <!-- or --> <cylinder radius="r" length="l"/> <!-- or --> <sphere radius="r"/> <!-- or --> <mesh filename="package://robot_name/meshes/part.stl" scale="0.001 0.001 0.001"/> </geometry> <!-- Optional: Position and orientation within link --> <origin xyz="0 0 0" rpy="0 0 0"/> <!-- Optional: Material coloring --> <material name="blue"> <color rgba="0 0 1 1"/> <!-- R G B Alpha (0-1) --> </material> </visual> </link> ``` **Geometry types:** - `<box size="x y z"/>` - Rectangular box in meters - `<cylinder radius="r" length="l"/>` - Cylinder with radius and length in meters - `<sphere radius="r"/>` - Sphere with radius in meters - `<mesh filename="path" scale="sx sy sz"/>` - External 3D mesh file (STL, DAE, OBJ) **Material colors (RGBA):** - `rgba="1 0 0 1"` - Red - `rgba="0 1 0 1"` - Green - `rgba="0 0 1 1"` - Blue - `rgba="1 1 1 1"` - White - `rgba="0 0 0 1"` - Black - Last value (alpha) is transparency: 1 = opaque, 0 = transparent ### Collision Geometry Used for physics simulation and collision detection. Should typically be simpler than visual geometry: ```xml <link name="complex_part"> <visual> <!-- Detailed visual mesh --> <geometry> <mesh filename="package://robot/meshes/detailed_part.stl"/> </geometry> </visual> <collision> <!-- Simplified collision boxes --> <geometry> <box size="0.5 0.3 0.1"/> </geometry> </collision> </link> ``` **Best practices:** - Keep collision geometry simple for performance - Use multiple collision elements to approximate complex shapes: ```xml <link name="gripper"> <collision> <origin xyz="0 0 0"/> <geometry><box size="0.1 0.2 0.05"/></geometry> </collision> <collision> <origin xyz="0.08 0.1 0"/> <geometry><box size="0.04 0.1 0.05"/></geometry> </collision> </link> ``` ### Inertial Properties Define mass and rotational inertia for dynamics simulation: ```xml <link name="base_link"> <inertial> <!-- Mass in kilograms --> <mass value="5.0"/> <!-- Inertia tensor (moment of inertia) --> <!-- ixx, iyy, izz = rotational inertia about x, y, z axes --> <!-- ixy, ixz, iyz = products of inertia (usually 0 for symmetric objects) --> <inertia ixx="0.1" ixy="0" ixz="0" iyy="0.1" iyz="0" izz="0.2"/> <!-- Optional: Center of mass offset from link origin --> <origin xyz="0 0 0.05" rpy="0 0 0"/> </inertial> </link> ``` **Computing inertia:** - For a box: `I = (1/12) * m * (h^2 + d^2)` where h, d are dimensions - For a cylinder: `I_x = I_y = (1/12) * m * (3*r^2 + h^2)`, `I_z = (1/2) * m * r^2` - For a sphere: `I = (2/5) * m * r^2` **Simplified approach:** If exact inertia is unknown, use rough estimates: ```xml <inertial> <mass value="1.0"/> <inertia ixx="0.01" ixy="0" ixz="0" iyy="0.01" iyz="0" izz="0.01"/> </inertial> ``` ## Joints in Detail ### Joint Types #### 1. **Fixed Joint** No movement - connects two links rigidly: ```xml <joint name="fixed_joint" type="fixed"> <parent link="base_link"/> <child link="sensor_link"/> <origin xyz="0.1 0 0.05" rpy="0 0 0"/> </joint> ``` **Use for:** - Sensors mounted on the robot - Non-moving parts - Rigid attachments #### 2. **Revolute Joint** Rotational movement with limits (like a door hinge): ```xml <joint name="shoulder_joint" type="revolute"> <parent link="base_link"/> <child link="arm_link"/> <origin xyz="0 0 0.3" rpy="0 0 0"/> <axis xyz="0 1 0"/> <!-- Rotate around Y axis --> <limit lower="-1.57" upper="1.57" effort="50" velocity="1.0"/> </joint> ``` **Parameters:** - `<axis>` - Rotation axis (unit vector, typically one value = 1) - `<limit>`: - `lower`, `upper` - Min/max angles in radians - `effort` - Maximum torque in Newton-meters - `velocity` - Maximum angular velocity in rad/s **Common axes:** - `xyz="1 0 0"` - Rotate around X (roll) - `xyz="0 1 0"` - Rotate around Y (pitch) - `xyz="0 0 1"` - Rotate around Z (yaw) #### 3. **Continuous Joint** Unlimited rotation (like a wheel): ```xml <joint name="wheel_joint" type="continuous"> <parent link="base_link"/> <child link="wheel_link"/> <origin xyz="0.2 0.15 0" rpy="0 1.57 0"/> <axis xyz="0 1 0"/> </joint> ``` **Use for:** - Wheels that spin indefinitely - Rotating shafts - Continuous rotating joints **Note:** No `<limit>` element needed #### 4. **Prismatic Joint** Linear sliding movement (like a piston): ```xml <joint name="linear_actuator" type="prismatic"> <parent link="base_link"/> <child link="piston_link"/> <origin xyz="0 0 0" rpy="0 0 0"/> <axis xyz="0 0 1"/> <!-- Move along Z axis --> <limit lower="0" upper="0.2" effort="100" velocity="0.1"/> </joint> ``` **Parameters:** - `<axis>` - Direction of movement (unit vector) - `<limit>`: - `lower`, `upper` - Min/max position in meters - `effort` - Maximum force in Newtons - `velocity` - Maximum linear velocity in m/s #### 5. **Planar Joint** Movement in a 2D plane (advanced, less common) #### 6. **Floating Joint** Free 6-DOF movement (for flying robots or underwater vehicles) ### Joint Limits and Effort **Always specify limits for revolute joints:** ```xml <!-- Limited rotation: safe joint --> <joint name="elbow" type="revolute"> <axis xyz="0 1 0"/> <limit lower="-2.0" upper="2.0" effort="30" velocity="1.5"/> <!-- Can rotate -2 to +2 radians (~-114 to +114 degrees) --> <!-- Max torque: 30 Nm, Max speed: 1.5 rad/s --> </joint> ``` **If you forget limits:** Many simulators will refuse to load the file! ## Kinematic Structures ### Building a Kinematic Chain A robot is organized as a tree of links connected by joints: ``` base_link (root) | | shoulder_joint (revolute) | arm_link | | elbow_joint (revolute) | forearm_link | | wrist_joint (revolute) | hand_link ``` **URDF representation:** ```xml <robot name="robot_arm"> <!-- Root link --> <link name="base_link"> <visual> <geometry><box size="0.3 0.3 0.1"/></geometry> </visual> </link> <!-- First joint and child link --> <joint name="shoulder_joint" type="revolute">