.. _set_desired_force:

set_desired_force
------------------------------------------
This function defines the **target force and torque** for each task-space axis, along with the **direction mask**,  
**transition time**, and **control mode**. It linearly transitions from the current force to the target values over ``fTargetTime``.

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

.. code-block:: cpp

   bool set_desired_force(float fTargetForce[NUM_TASK],
                          unsigned char iTargetDirection[NUM_TASK],
                          COORDINATE_SYSTEM eForceReference = COORDINATE_SYSTEM_TOOL,
                          float fTargetTime = 0.f,
                          FORCE_MODE eForceMode = FORCE_MODE_ABSOLUTE) {
       return _set_desired_force(_rbtCtrl, fTargetForce, iTargetDirection, eForceReference, fTargetTime, eForceMode);
   };

**Parameter**

.. list-table::
   :widths: 24 22 18 36
   :header-rows: 1

   * - **Parameter Name**
     - **Data Type**
     - **Default Value**
     - **Description**
   * - fTargetForce
     - float[6]
     - -
     - Target forces and torques applied along the task-space axes: **[Fx, Fy, Fz, Mx, My, Mz]**. |br|
       Units: N (translational) and N·m (rotational).
   * - iTargetDirection
     - unsigned char[6]
     - -
     - Axis mask for control |br|
       (**0**: ignore, **1**: active control). |br|
       Controls which axes respond to the commanded force.
   * - eForceReference
     - :ref:`COORDINATE_SYSTEM <enum_coordinate_system>`
     - ``COORDINATE_SYSTEM_TOOL``
     - Coordinate system where the force is defined (e.g., TOOL, BASE, WORLD).
   * - fTargetTime
     - float
     - 0
     - Transition time [sec] for the force ramp (**0–1.0**). |br|
       Linear interpolation over this time.
   * - eForceMode
     - :ref:`FORCE_MODE <enum_force_mode>`
     - ``FORCE_MODE_ABSOLUTE``
     - Force mode (**absolute** for direct control, **relative** for incremental application).

**Return**

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

   * - **Value**
     - **Description**
   * - 0
     - Failed
   * - 1
     - Success

.. note::

   When the address passed to ``open_connection`` is exactly "127.0.0.1", ``task_compliance_ctrl``, ``set_stiffnessx``, ``release_compliance_ctrl``, ``set_desired_force`` and ``release_force`` return true without sending the command to the controller.

**Example A — Manual Mode (Pressing During Teaching)**

.. code-block:: cpp

   // Preconditions: Connected, Teach mode active, Servo ON.

   // 1) Enable compliance with moderate stiffness
   float stiff[6] = {3000.f, 3000.f, 3000.f, 200.f, 200.f, 200.f};
   drfl.task_compliance_ctrl(stiff, COORDINATE_SYSTEM_TOOL, 0.0f);

   // 2) Apply +20 N along TOOL Z axis
   float fTarget[6] = {0.f, 0.f, 20.f, 0.f, 0.f, 0.f};
   unsigned char dir[6] = {0, 0, 1, 0, 0, 0};  // control only Z
   drfl.set_desired_force(fTarget, dir, COORDINATE_SYSTEM_TOOL, 0.3f, FORCE_MODE_ABSOLUTE);

   printf("Force control active: +20N along TOOL Z.\n");

   // 3) Gradually release the applied force
   drfl.release_force(0.4f);
   drfl.release_compliance_ctrl();

**Example B — Auto Mode (Force-Controlled Insertion Task)**

.. code-block:: cpp

   // Preconditions: Robot connected, Auto mode active, motion sequence running.

   // 1) Move to approach position
   float p_app[NUM_TASK] = {550.f, 200.f, 130.f, 180.f, 0.f, 0.f};
   float vel1[2] = {100.f, 30.f}, acc1[2] = {400.f, 150.f};
   drfl.movel(p_app, vel1, acc1);
   drfl.mwait();

   // 2) Enable compliance
   float stiff[6] = {2500.f, 2500.f, 1500.f, 150.f, 150.f, 150.f};
   drfl.task_compliance_ctrl(stiff, COORDINATE_SYSTEM_TOOL, 0.1f);

   // 3) Apply downward insertion force (+Z)
   float fTarget[6] = {0.f, 0.f, 30.f, 0.f, 0.f, 0.f};
   unsigned char dir[6] = {0, 0, 1, 0, 0, 0};
   drfl.set_desired_force(fTarget, dir, COORDINATE_SYSTEM_TOOL, 0.2f, FORCE_MODE_ABSOLUTE);

   // 4) Perform insertion motion
   float p_down[NUM_TASK] = {550.f, 200.f, 90.f, 180.f, 0.f, 0.f};
   float vel2[2] = {50.f, 20.f}, acc2[2] = {200.f, 80.f};
   drfl.movel(p_down, vel2, acc2);
   drfl.mwait();

   // 5) Release force and compliance
   drfl.release_force(0.3f);
   drfl.release_compliance_ctrl();

   printf("Force-controlled insertion completed.\n");

**Notes & Best Practices**

- If the robot enters EMERGENCY_STOP, SAFE_OFF or SAFE_OFF2 while the force is active, the force is released (except when connected with the address "127.0.0.1", see :ref:`open_connection <open_connection>`).
- Apply :ref:`task_compliance_ctrl <task_compliance_ctrl>` before setting a target force to ensure stable behavior.  
- Use the **direction mask** to apply force only along the required axes (e.g., pressing in Z while maintaining free X/Y).  
- Set a small ``fTargetTime`` (0.2–0.5s) for smooth transitions and to avoid sudden motion.  
- ``FORCE_MODE_RELATIVE`` can be used to incrementally adjust existing force values during process adaptation.  
- Always call :ref:`release_force <release_force>` and :ref:`release_compliance_ctrl <release_compliance_ctrl>` after force-based tasks to restore normal control.