add_new_tool

Adding a new tool

Overview

• Wrapping an existing robot : passing generic properties and instantiating the new tool.
• Setting up properties : storing the properties for different instances of the tool
• Setting up calibration : storing mounting offsets for different instances of the tool

Pre-requirements

• The new tool should offer a xacro macro in a separate description package
• The new tool URDF/Xacro should be prefixable, meaning the joint/link/other names should include a prefix variable to permit multiple instances (left/right tools)

Steps

Wrapping an existing robot

1. Add the new robot description package to your environment

   Example: adding schunk_description

2. Analyze existing macros and the parameters they require

• Every required parameters will have to be generated or loaded from properties.
• If the macro does not contain a joint to attach the tool base to a parent link, this is fine, a single property will be set later.
• If the macro already includes a joint to attach the tool base to a parent link, an intermediate tool_mount link must be created because agni_description arm_with_tool macros explicitly adds a joints to tool_mount.

Example: schunk_sdh with params="parent name *origin"

• Here the parameters require a parent link name, a robot name and an origin.
• The macro includes a joint to parent link, so we create sdh_mount dummy link, and pass this as the parent as well as an zero offset origin. The placement of the hand is done through the calibration file (see calibration)

3. Create a wrapper xacro file agni_description/robots/new_tool_name

   Example: agni_description/robots/schunk_hand.urdf.xacro

   Below is a template xacro, where user properties should be added matching the required properties of the new tool.

  <!-- instantiate the tool here, using existing macros and passing required property1/parameters --> 

</xacro:macro>

**Note** : 
 * the ```prefix``` property should **always** be present and is the only one passed
 * ```user properties``` are not passed but read from props variable also with default values if needed.
4. Instantiate the tool within the template macro, using the existing macros of the new description package

Example
```xml
<?xml version="1.0"?>
<robot name="sdh" xmlns:xacro="http://www.ros.org/wiki/xacro">
<xacro:include filename="$(find schunk_description)/urdf/sdh/sdh.urdf.xacro" />

<xacro:macro name="schunk_hand" params="prefix:=''">
 <xacro:property name="prefix_" value="${'' if prefix=='' else prefix+'_'}"/>
 <link name="${prefix_}sdh_mount" />
 <xacro:call macro="schunk_sdh" parent="${prefix_}sdh_mount" name="${prefix_}sdh" >
   <origin xyz="0 0 0" rpy="0 0 0"/>
 </xacro:call>
</xacro:macro>
</robot>

Setting up properties

Properties can be loaded when instantiating a tool. These properties are in the tool section of agni_description/robots/robots.yaml :

• file: the xacro file of the wrapper to the tool
• macro: the wrapper macro name to be called
• mount: the name of the tool link that should be attached at the arm mount
• props: list of required properties
  • mass: total mass of the tool. Helps the robot arm controller to compensate for the additional mass.
  • cog: center of gravity of the tool given in the frame of the last robot link. Helps the robot arm controller to compensate for the additional mass
  • optional user properties to instantiate the tool, for instance, side, model, tactile_type, port, init_joint_pos

Example :

tools:
  schunk_hand_right:
    file: ../robots/schunk_hand.urdf.xacro
    macro: schunk_hand
    mount: sdh_mount
    props:
      mass:  2.0
      cog: "0.0 0.0 0.15"

Setting up calibration

Calibration contain attachment offsets, dedicated to each instance of the tool, and even for each robot arm setup. Indeed, the tools might be mounted in a different orientation on a different arm.

1. Create a default config

In the calibration/default directory add one file per tool instance you created in robots.yaml with name <tool_instance_name>_cal.xml

Below is a template

 <?xml version="1.0"?>
<root xmlns:xacro="http://www.ros.org/wiki/xacro">
<!-- mount -->
<xacro:property name="cal_x" value="0.0" />
<xacro:property name="cal_y" value="0.0" />
<xacro:property name="cal_z" value="0.0" />
<xacro:property name="cal_yaw"   value="${pi/2}" /> 
<xacro:property name="cal_pitch" value="0.0" />
<xacro:property name="cal_roll"  value="0.0" />
</root>

Example: create schunk_hand_cal.xml and then a symlink to it as schunk_hand_right_cal.xml

2. Create symlinks in the platform directory

Example: in famula directory, schunk_hand_right_cal.xml -> ../default/schunk_hand_right_cal.xml