.. _manual_add_tcp:

add_tcp (Manual Mode)
------------------------------------------
This section explains how to use :ref:`add_tcp <add_tcp>`  
during system initialization or tool setup to register a new  
**Tool Center Point (TCP)** on the robot controller.  

The TCP defines a position and orientation relative to the tool flange  
and is a key element for precise task-space control.

Once registered, the TCP may be activated with :ref:`set_tcp <set_tcp>`.

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 TCPs for new grippers, screwdrivers, weld torches, or probes.  
- Create multiple TCP points for complex tools with different working tips.  
- Load TCP values measured using Smart Setup or CAD specifications.  
- Prepare TCP configurations for recipe-based automated tasks.

.. 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.
    - Orientation values follow the Z-Y-Z Euler angle convention (A, B, C).  
    - TCP registration is normally performed once during commissioning.

**Example: Registering a New TCP for a Gripper**

.. code-block:: cpp

   // Example TCP: 80 mm forward, 0 mm right, 30 mm downward from flange
   // Position (X, Y, Z) followed by Euler Z-Y-Z angles (A, B, C)
   float tcp[6] = {80.f, 0.f, -30.f, 180.f, 0.f, 180.f};

   // Register TCP
   if (!drfl.add_tcp("TCP_GRIPPER_CENTER", tcp)) {
       printf("Failed to register TCP.\n");
       return -1;
   }

   // Activate the TCP
   drfl.set_tcp("TCP_GRIPPER_CENTER");

In this example, a TCP is registered and immediately activated for subsequent pick-and-place operations.

**Tips**

- Define multiple TCPs for tools with different contact or measurement points.  
- Use Smart Setup auto-measurement when possible for higher precision.  
- Maintain consistent naming conventions for recipes and tool libraries.