.. _manual_add_tool:

add_tool (Manual Mode)
------------------------------------------
This section explains how to use :ref:`add_tool <add_tool>` in **Manual** mode during initialization routines to register a **new tool** (end-effector) on the robot controller.

A tool definition includes weight, center of gravity (CoG), and inertia information,  
all of which are necessary for accurate trajectory generation and force estimation.
Once registered, a tool can be activated using :ref:`set_tool <set_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**

- Register a new gripper, probe, or custom end-effector.  
- Load tool data measured from Smart Setup or CAD specifications.  
- Prepare multiple tool configurations for automated tool-changing processes.  
- Initialize tool definitions during system startup or commissioning.

.. Note::

    - The name is limited to 32 bytes; longer names are truncated. Adding a name that already exists replaces that entry, and if the tool (TCP) is active the new values take effect immediately. The controller holds up to 50 tools and 50 TCPs; adding beyond that raises an alarm and stops the running program.
    - Weight and CoG values should match the physical tool as closely as possible.  
    - Tool registration is typically performed once—not every cycle.

**Example: Registering a New Tool Configuration**

.. code-block:: cpp

   float cog[3]     = {0.f, 0.f, 40.f};       // in mm relative to flange/TCP
   float inertia[6] = {0.f, 0.f, 0.f, 0.f, 0.f, 0.f};

   // Register a new tool
   if (drfl.add_tool("NEW_END_EFFECTOR", 1.2f, cog, inertia)) {
       printf("Tool registered successfully.\n");
   } else {
       printf("Failed to register tool.\n");
       return -1;
   }

   // Select the new tool
   drfl.set_tool("NEW_END_EFFECTOR");

In this example, a new tool is created and then enabled for subsequent motion using ``set_tool()``.

**Tips**

- Register all tools during initialization, then switch tools using ``set_tool``.  
- Use accurate mass/CoG values to ensure safe motion and torque estimation.  
- Store tool symbols in a central recipe table for multi-tool automation.