> For the complete documentation index, see [llms.txt](https://docs.hello-robot.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello-robot.com/stretch4_docs/working-with-stretch/common_tasks/changing-tools.md).

# 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:

```bash
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:

```bash
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
```

2. 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:

```xml
<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>
```

3. 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.
4. Add the tool to `nominal_params` in [robot\_params\_SE4.py](https://github.com/hello-robot/stretch4_body/blob/main/stretch4_body/robot/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](https://github.com/hello-robot/stretch4_body/blob/main/stretch4_body/robot/robot_params_SE4.py) 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](https://github.com/hello-robot/stretch4_body/blob/main/stretch4_body/subsystem/end_of_arm/end_of_arm_tools.py) and a class of the same name with `_Client` appended in [robot\_client.py](https://github.com/hello-robot/stretch4_body/blob/main/stretch4_body/robot/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](https://github.com/hello-robot/stretch4_body/blob/main/stretch4_body/robot/robot_params_SE4.py) 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](https://github.com/hello-robot/stretch4_ros2/blob/jazzy/stretch_core/stretch_core/command_groups.py).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hello-robot.com/stretch4_docs/working-with-stretch/common_tasks/changing-tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.