## repository: https://kforge.ros.org/robotmodel/robot_model
<<PackageHeader(srdf)>>

<<TableOfContents(5)>>

== Semantic Robot Description Format (SRDF) ==
Proposer: '''Sachin Chitta, Kaijen Hsiao, Gil Jones, Ioan Sucan, John Hsu'''

This format is intended to represent information about the robot that is not in the URDF file, but it is useful for a variety of applications. The intention is to include information that has a semantic aspect to it.  A review of this format is available [[srdf/review|here]].

== Description ==
=== Tags ===
 * '''<robot>''' element
  * Purpose: This is the root tag that for this document. All information is included in this tag.
  * Elements: <group>, <end_effector>, <virtual_joint>, <group_state>, <disable_collisions>
  * Attributes:
   * ''name'' is the name of the robot. It should be the same name as in the corresponding URDF file.

 * '''<group>''' element
  * Purpose: Representation of a set of joints and links. This can be useful for specifying DOF to plan for, defining arms, end effectors, etc
  * Elements: <link>, <joint>, <chain>, <group>
  * Attributes:
   * ''name'' is the name of the group
  * Note: when a group contains no tags, only its name attribute, it is assumed to be a reference to a group with that name, but that is defined earlier.

 * '''<group_state>''' element
  * Purpose: Define a named state for a particular group, in terms of joint values. This is useful to define states like "folded arms".
  * Elements: <joint>
  * Attributes:
   * ''name'' is the name of the state
   * ''group'' is the name of the group the state is for
  * Note: all joints in a group must have their value specified as part of a group state in order for that state to be valid.

 * '''<link>''' element
  * Purpose: this element specifies a link that is part of a <group>.
  * Elements: none
  * Attributes:
   * ''name'' must be a name of a link in the corresponding URDF file
  * Note: When a link is included in a group, so is the corresponding parent joint (if one exists)

 * '''<joint>''' element
  * Purpose: this element specifies a joint that is part of a <group>.
  * Elements: none
  * Attributes:
   * ''name'' must be a name of a joint in the corresponding URDF file
   * ''value'' *only* in the <group_state> tag, the ''value'' attribute is accepted for joints (a floating point value). When a joint consists of multiple DOF, the value is simply a space-separated array of floating point values.
  * Note: When a joint is included in a group, so is the corresponding child link

 * '''<chain>''' element
  * Purpose: Represent a kinematic chain in the robot. This is useful for instance in representing arms.
  * Elements: none
  * Attributes:
   * ''base_link'' is the root link of the chain (the link that is fixed with respect to the chain)
   * ''tip_link'' is the last link of the chain (where the chain ends)
  * Note: Based on the links in the chain, the set of joints in the chain is implicitly defined. The joints that correspond to a chain are the parent joints for the links in the chain, except the parent joint of the ''base_link''.

 * '''<end_effector>''' element
  * Purpose: Represent information about an end effector.
  * Elements: none
  * Attributes:
   * ''name'' is the name of the end effector
   * ''group'' is the name of the group that contains the links (and joints) that make up the end effector
   * ''parent_link'' is the name of the link this end effector is attached to
   * ''parent_group'' (optional) is the name of the joint group containing ''parent_link''. If for instance, you have an ''arm'' group, a ''hand'' group, then the ''hand'' end-effector's ''parent_group'' would be ''arm''.

 * '''<virtual_joint>''' element
  * Purpose: this element defines a virtual joint between a robot link and an external frame of reference (considered fixed with respect to the robot)
  * Elements: none
  * Attributes:
   * ''name'' the name of the joint that is assumed to exist between the robot and the environment
   * ''child_link'' the name of the link that connects the robot to the environment
   * ''parent_frame'' the name of the frame assumed to be fixed with respect to the robot
   * ''type'' the type of joint to be assumed. This can be fixed (0 DOF), floating (all 6 DOF) or planar (3 DOF: x, y, yaw)
  * Note: When the <joint> tag is used to refer to existing joints by name, using the name of defined virtual joints is also possible.

 * '''<disable_collisions>''' element
  * Purpose: By default it is assumed that any link of the robot could potentially come into collision with any other link in the robot. This tag disables collision checking between a specified pair of links. There can be many such tags in this file
  * Elements: none
  * Attributes:
   * ''link1'' the name of the first link in the pair
   * ''link2'' the name of the second link in the pair
   * ''reason'' (optional) the reason this collisions between the two links should be disabled.

 * '''<passive_joint>''' element
  * Purpose: By default it is assumed that all joints specified by a URDF are active and their state is made available for planning. If this is not the case for some joints, this tag can be used to specify that.
  * Elements: none
  * Attributes:
   * ''name'' the name of the joint that is passive.

 * '''<link_sphere_approximation>''' element
  * Purpose: This tag specifies a set of spheres that conservatively approximates a link.  Spheres are specified in the same coordinate frame as the collision geometry in the URDF.  This tag is optional.  If no tag appears for a link then a single sphere that encloses the link's collision geometry will be used.  If a tag appears and contains only spheres with radius 0 then the link will not be considered when doing sphere based collision detection.
  * Elements: sphere
  * Attributes:
   * ''link'' the name of the link that is approximated by these spheres.

 * '''<sphere>''' element
  * Purpose: This tag specifies a sphere.
  * Elements: none
  * Attributes:
   * ''center'' 3 space-separated floating point values specifying the sphere center x y z.
   * ''radius'' a floating point sphere radius.

=== Generic Example ===
{{{
<?xml version="1.0"?>

 <!-- This does not replace URDF, and is not an extension of URDF.
      This is a format for representing semantic information about the robot structure.
      A URDF file must exist for this robot as well, where the joints and the links that are referenced are defined -->
 <robot name="some robot">

   <group name="group1">
      <!-- when a link is specified, the parent joint of that link (if it exists) is automatically included -->
      <link name="..."/>
      <link name="..."/>

      <!-- when a joint is specified, the child link of that joint (which will always exist) is automatically included -->
      <joint name="..." />

      <!-- when a chain is specified, all the links along the chain (including endpoints) are included in the group. Additionally, all the joints that are parents to included links are also included. This means that joints along the chain and the parent joint of the base link are included in the group -->
      <chain base_link="l_shoulder_pan_link" tip_link="l_wrist_roll_link"/>
      <chain base_link="r_shoulder_pan_link" tip_link="r_wrist_roll_link"/>
   </group>

   <!-- groups can also be formed by referencing to already defined group names -->
   <group name="arms">
      <group name="left_arm"/>
      <group name="right_arm"/>
      <link name="..." />
   </group>

   <!-- define a named state/configuration of a group -->
   <group_state name="name of this state" group="name of group the state is for">
      <joint name="name of joint in group" value="" />
      <!-- all joints must be specified for the state to be valid -->
   </group_state>

   <!-- Define how the robot moves in its environment, i.e., connection to robot's root link -->
   <virtual_joint name="world_joint" type="planar" parent_frame="some fixed frame" child_link="robot's root link name"/> <!-- type can be planar, floating or fixed -->

   <!-- We can then include the virtual joint in groups -->
   <group name="whole_body">
      <group name="arms"/>
      <joint name="world_joint"/>
   </group>


   <!-- define end effectors -->
   <end_effector name="some diff name" parent_link="..." group="group_name"/>

   <!-- By default it is assumed that any link of the robot could potentially come into collision with any other link in the robot. This tag disables collision checking between a specified pair of links. There can be many such tags in this file.-->
   <disable_collisions link1="link1" link2="link2" />

</robot>
}}}
=== Example for the PR2 ===
{{{
<?xml version="1.0"?>

<robot name="pr2">

   <virtual_joint name="world_joint" type="planar" parent_frame="odom" child_link="base_footprint"/>

   <group name="right_arm">
      <chain base_link="torso_lift_link" tip_link="r_wrist_roll_link"/>
   </group>

   <group name="left_arm">
      <chain base_link="torso_lift_link" tip_link="l_wrist_roll_link"/>
   </group>

   <group name="arms">
      <group name="left_arm"/>
      <group name="right_arm"/>
   </group>

   <group_state name="tuck_arms" group="arms">
      <joint name="l_shoulder_pan_joint" value="0.2" />
      <!-- ... the rest of the joint values... -->
   </group_state>

   <group name="base">
      <joint name="world_joint"/>
   </group>

   <group name="whole_body">
      <group name="arms"/>
      <group name="base"/>
      <joint name="torso_lift_joint"/>
   </group>

   <group name="l_end_effector">
      <joint name="l_gripper_palm_joint" />
      <joint name="l_gripper_l_finger_joint" />
      <joint name="l_gripper_l_finger_tip_joint" />
      <joint name="l_gripper_led_joint" />
      <joint name="l_gripper_motor_accelerometer_joint" />
      <joint name="l_gripper_motor_slider_joint" />
      <joint name="l_gripper_motor_screw_joint" />
      <joint name="l_gripper_r_finger_joint" />
      <joint name="l_gripper_r_finger_tip_joint" />
      <joint name="l_gripper_joint" />
      <joint name="l_gripper_tool_joint" />
   </group>

   <group name="r_end_effector">
      <joint name="r_gripper_palm_joint" />
      <joint name="r_gripper_l_finger_joint" />
      <joint name="r_gripper_l_finger_tip_joint" />
      <joint name="r_gripper_led_joint" />
      <joint name="r_gripper_motor_accelerometer_joint" />
      <joint name="r_gripper_motor_slider_joint" />
      <joint name="r_gripper_motor_screw_joint" />
      <joint name="r_gripper_r_finger_joint" />
      <joint name="r_gripper_r_finger_tip_joint" />
      <joint name="r_gripper_joint" />
      <joint name="r_gripper_tool_joint" />
   </group>

   <end_effector name="r_end_effector" parent_link="r_wrist_roll_link" group="r_end_effector"/>
   <end_effector name="l_end_effector" parent_link="l_wrist_roll_link" group="l_end_effector"/>

   <disable_collisions link1="r_shoulder_pan_link" link2="r_shoulder_lift_link" />
   <!-- and many more disable_collisions tags -->

</robot>
}}}