.. _manual_set_tool:

set_tool (Manual Mode)
------------------------------------------
This section explains how to use :ref:`set_tool <set_tool>` in **Manual** mode to activate a predefined **tool configuration**. The active tool determines the robot’s payload, center of gravity, and motion behavior, making it essential for accurate task-space control and safe automated operation.

This function selects a tool definition that was previously registered  
using :ref:`add_tool <add_tool>`.

Available in Manual mode. In any other mode the function returns false and prints ``this command can only be used in manual mode. please change to manual mode as robot mode``. The mode check uses the value returned by :ref:`get_robot_mode <get_robot_mode>`.

.. Caution::

   On a real robot the safety board also refuses the call while the robot is moving; the motion is quick-stopped and a running program is stopped.

**Typical usage**

- Switch between different end-effectors (e.g., gripper, screwdriver, probe).  
- Activate the correct tool before switching to Auto mode for pick/place sequences.
- Ensure consistent dynamics and force-control performance.  
- Validate tool configuration in recipes with multiple tool types.

.. Note::

    - The symbol must match the tool name registered via ``add_tool``.  
    - Changing tools during motion is not recommended; switch at a safe pose.  
    - The active tool affects payload, CoG, and force/torque estimation.

**Example: Selecting a Tool Before Motion**

.. code-block:: cpp

   // Activate a predefined tool configuration
   if (!drfl.set_tool("RG2_GRIPPER")) {
       printf("Failed to activate tool RG2_GRIPPER.\n");
       return -1;
   }

   // Use this tool in the next motion
   float pickPose[6] = {300.f, 200.f, 250.f, 180.f, 0.f, 0.f};
   float vel[2] = {100.f, 50.f}, acc[2] = {300.f, 100.f};
   drfl.movel(pickPose, vel, acc);

In this example, the robot selects a tool configuration and executes a movement using the chosen tool's properties.

**Tips**

- Match the tool symbol exactly with the controller configuration.  
- Use this function when switching between tool types in automated workflows.  
- Use ``get_tool()`` to confirm which tool is currently active.