Alex's Notes

URDF (Unified Robot Description Format)

An xml based file format for specifying robots. Used in cm3020 Topic 01: Genetic Algorithms to specify our evolved creatures.

The document model is summarised here from the official documentation

<robot>

The root node is a <robot> tag, with a mandatory name attribute in master files. In included files name is optional but if included must have the same value as the master.

Can have the following children: <link> <joint> <transmission> <gazebo>. In practice though, we’re only using links and joints, the others are extensions to the spec in other applications.

The link element describes a rigid body with an inertia, visual features and collision properties. It has a mandatory name attribute.

Can have the following children (all optional): <inertial> <visual> <collision>

<inertial>

The inertial properties of the link. Must have the following children: <mass> <inertia>. May have an <origin> child:

  • <mass>: the mass of the link is specified by the value attribute here.

  • <inertia>: the 3x3 rotational inertia matrix. The matrix is symmetric so we just specify the above-diagonals in attributes of this element: ixx, ixy, ixz, iyy, iyz, izz. You can see common shapes here

  • <origin>: Defaults to identity if not specified. The pose of the inertial reference frame, relative to the link reference frame. The origin should be the centre of gravity. Attributes for the xyz offset (defaults to 0 vector), and rpy roll, pitch, and yaw angles in radians.

<visual>

The visual properties of the link. Multiple instances of <visual> can exist for a link, the union of their geometry defines its visual form. Has an optional name attribute. Must have a <geometry> child. May have <origin> and <material> children:

  • <origin>: same properties as before, the reference frame for the visual.

  • <geometry>: The shape, with one of the following children: <box size=""> <cylinder radius="" length=""> <sphere radius=""> <mesh filename="" scale="">

  • <material>: Can specify a material element outside the link object, in the top level robot. Then you can just specify the material by a name attribute. May have the following children: <color rgba="0 0.3 0.7 1"> <texture filename="">

<collision>

The collision properties, can be different (often simpler) than visual properties. Multiple instances can exist on a link. Has an optional name attribute. Must have a <geometry> child (same properties as above). May have an <origin> child, same properties as above.

<link name="my_link">
   <inertial>
     <origin xyz="0 0 0.5" rpy="0 0 0"/>
     <mass value="1"/>
     <inertia ixx="100"  ixy="0"  ixz="0" iyy="100" iyz="0" izz="100" />
   </inertial>

   <visual>
     <origin xyz="0 0 0" rpy="0 0 0" />
     <geometry>
       <box size="1 1 1" />
     </geometry>
     <material name="Cyan">
       <color rgba="0 1.0 1.0 1.0"/>
     </material>
   </visual>

   <collision>
     <origin xyz="0 0 0" rpy="0 0 0"/>
     <geometry>
       <cylinder radius="1" length="0.5"/>
     </geometry>
   </collision>
</link>

<joint>

Describes the kinematics and dynamics of the joint, and specifies its safety limits

Must have the attributes name and type, the latter can be one of:

  • revolute: hinge with limited range, rotates around axis

  • continuous: rotates around axis with no upper and lower limits

  • prismatic: sliding joint that slides along axis with limited range

  • fixed: Not really a joint, cannot move

  • floating: allows motion for all 6 degrees of freedom

  • planar: allows motion in a plane perpendicular to the axis

Must have children: <parent link=""> <child link="">. May have the following children:

  • <origin> same as before

  • <axis xyz="">: Defaults to (1,0,0). The joint axis specified in the joint frame. Axis of rotation for revolute joints, translation for prismatic joints, surface normal for planar joints. Not used by fixed or floating joints.

  • <calibration>: Reference positions to calibrate the absolute position of the joint. may have rising and falling attributes.

  • <dynamics>: Specifies the physical properties of the joint. May have damping and friction attributes (real values).

  • <limit>: Required only for revolute and prismatic joints, may have lower and upper limits (radians for revolute, meters for prismatic). Omit limits if continuous. Must have effort attribute and velocity attribute for enforcing maximums.

  • <safety_controller>: Allows you to specify when the safety controller intervenes with soft_lower_limit and soft_upper_limit attributes. Must have k_velocity attribute specifying relation between effort and velocity limits, may have k_position attribute specifying relation between position and velocity limits.

Example Joint

<joint name="my_joint" type="floating">
   <origin xyz="0 0 1" rpy="0 0 3.1416"/>
   <parent link="link1"/>
   <child link="link2"/>

   <calibration rising="0.0"/>
   <dynamics damping="0.0" friction="0.0"/>
   <limit effort="30" velocity="1.0" lower="-2.2" upper="0.7" />
   <safety_controller k_velocity="10" k_position="15" soft_lower_limit="-2.0" soft_upper_limit="0.5" />
</joint>

Links to this note