Changing Tools

Stretch supports interchangeable end-of-arm tools. The software has a single configuration parameter, robot.tool, which dictates the current tool configuration active on the robot. This parameter is located within either the stretch_configuration_params.yaml or stretch_user_params.yaml files inside your robot's $HELLO_FLEET_PATH directory. It ensures that the appropriate kinematics, collision models, and software interfaces are strictly loaded upon startup.

Stretch Supported Tools

The official supported end-of-arm tool configurations are based on your robot model and can be found in the list below.

Supported Stretch 4 Tools

• eoa_wrist_dw4_tool_sg4
• eoa_wrist_dw4_tool_pg4
• eoa_wrist_dw4_tool_tablet
• eoa_wrist_dw4_tool_calibration
• eoa_wrist_dw4_tool_nil

You can run the following command in a terminal to print out the active robot.tool parameter:

stretch_params.py | grep robot.tool

To change the active tool configuration, use the stretch_configure_tool CLI utility. Running this command will guide you through updating your system to point to the newly selected tool automatically:

stretch_configure_tool

Adding a New Tool To Stretch

To add new end of arm hardware to Stretch and connect it to the software interface, you will need the mesh files and the URDF. These are typically exported from the CAD assembly or obtained from the manufacturer.

1. In the stretch_urdf_ii shared model tool directory (e.g. SE4_tools), create a directory for your tool with the following structure:

    > {model}_tools 
        > {tool_name} 
            > meshes 
            {tool_name}.urdf

1. Process the auto-generated tool URDF:

• Name the tool root link link_quick_connect_interface. This is the connection point to the rest of the arm.

  • This can be accomplished in a few ways:

    • Name the connecting link link_quick_connect_interface before generating the URDF
    • Rename the existing root link. Ensure all instances of the name are updated.
    • Add a new link and joint to the URDF file manually. This will be a "ghost" link with no collision or visual geometry, and the joint will be an identity transform to the existing root link.

      • Ex:

<link name="link_quick_connect_interface" />

<joint name="joint_quick_connect_interface" type="fixed">
    <origin xyz="0 0 0" rpy="0 0 -0" />
    <parent link="link_quick_connect_interface" />
    <child link="{existing_tool_root_link}" />
</joint>

1. Run the tool processing script process_new_tool.py and follow the prompts. This will create a config file for auto-generated collision meshes if one does not already exist, generate collision meshes, and update the tool URDF to use them. To change the collision mesh settings, edit the config file and re-run the script.
2. Add the tool to nominal_params in robot_params_SE4.py.

   • Add the tool name to the supported_eoa list. This must be the same name as the folder in stretch4_urdf.
   • Add a new entry for the tool in the self_collision_mujoco field
   • Add the tool name as a new key in the nominal_params dictionary

     • If the new tool is not actuated, it can use the existing SE4_eoa_wrist_dw4_tool_nil object.
     • If the new tool requires a control interface, add a dictionary for the new tool in the EndOfArm section above. Follow the structure of SE4_eoa_wrist_dw4_tool_sg4 or another existing end of arm tool.

       • Define a new class in the top level py_module_name and create the class in end_of_arm_tools.py and a class of the same name with _Client appended in robot_client.py
       • Add the tool actuator under devices along with the wrist_pitch, wrist_roll, and wrist_yaw
       • device_params expects another dictionary defined in the EOA joints section above the EndOfArm section
       • py_module_name and py_class_name point to the tool's API
       • For ROS support, include the ros section. py_module_name and py_class_name point to the command group that will be used by the ROS driver. The standard module is command_groups.py.