.. _add_tool:

add_tool
------------------------------------------
This function registers the information of a tool to be mounted on the robot flange. The tool information includes **name, weight, center of gravity, and inertia**, and is stored in the robot controller’s memory. The data remains available until reboot, unless saved and restored through the T/P initialization process.

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

**Definition** |br|
``DRFLEx.h`` within class `CDRFLEx`, public section

.. code-block:: cpp

    bool add_tool(string strSymbol, float fWeight, float fCog[3], float fInertia[NUM_TASK]) {
        return _add_tool(_rbtCtrl, strSymbol.c_str(), fWeight, fCog, fInertia);
    };

**Parameter**

.. list-table::
   :widths: 20 20 20 40
   :header-rows: 1

   * - **Parameter Name**
     - **Data Type**
     - **Default Value**
     - **Description**
   * - strSymbol
     - string
     - -
     - Tool name.
   * - fWeight
     - float
     - -
     - Tool weight in kilograms.
   * - fCog
     - float[3]
     - -
     - Center of gravity of the tool in millimeters.
   * - fInertia
     - float[6]
     - -
     - Inertia tensor values (Ixx, Iyy, Izz, Ixy, Ixz, Iyz).

**Return**

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - **Value**
     - **Description**
   * - 0
     - Error — failed to register the tool
   * - 1
     - Success — tool successfully registered in memory

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

**Example**

.. code-block:: cpp

   float fCog[3]     = {10.f, 10.f, 10.f};
   float fInertia[6] = {0.f, 0.f, 0.f, 0.f, 0.f, 0.f};

   // (1) Register a new tool
   bool success = drfl.add_tool("tool#1", 5.3f, fCog, fInertia);

   // (2) Set it as the active tool
   if (success)
       drfl.set_tool("tool#1");

   // (3) Remove the tool registration
   drfl.del_tool("tool#1");

This example registers a new tool (“tool#1”) with its weight,  
center of gravity, and inertia data, then activates it and finally deletes the registration.