.. _set_rt_control_input:

set_rt_control_input
------------------------------------------
This function sets the **input data communication configuration**  
for Real-time External Control (from external controller → robot controller).  
It defines the version, update period, and loss tolerance used for UDP-based input streaming.

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

.. code-block:: cpp

   bool set_rt_control_input(string strVersion, float fPeriod, int nLossCnt) {
       return _set_rt_control_input(_rbtCtrlUDP, strVersion.c_str(), fPeriod, nLossCnt);
   };

**Parameter**

.. list-table::
   :widths: 25 20 20 35
   :header-rows: 1

   * - **Parameter Name**
     - **Data Type**
     - **Default Value**
     - **Description**
   * - strVersion
     - string
     - -
     - Input data version to be used for RT streaming (e.g., `"v1.0"`)
   * - fPeriod
     - float
     - -
     - Communication period in seconds. |br|
       Valid range: **0.001 ~ 1.0 [s]** (1 kHz ~ 1 Hz update rate)
   * - nLossCnt
     - int
     - -
     - Maximum allowed consecutive packet loss count. |br|
       The RT connection is automatically terminated once the number of consecutive lost packets **reaches** this value. |br|
       ``-1`` does not disable the check. The counter reaches 1 one period after the last packet, so ``-1``, ``0`` and ``1`` all end the session at that same moment. Use **2 or more** to tolerate any loss at all; the supplied examples use 4.

**Note**

- ``fPeriod`` currently supports **0.001 s ~ 1.0 s** only.  
- This function must be called **after** :ref:`connect_rt_control <connect_rt_control>`  
  and **before** :ref:`start_rt_control <start_rt_control>`.  
- Input schema must match one of the versions from :ref:`get_rt_control_input_version_list <get_rt_control_input_version_list>`.
- The input watchdog is armed by this function only. For monitoring-only sessions that send no input data, skip this call and configure output alone with :ref:`set_rt_control_output <set_rt_control_output>`; no loss check is then applied.

**Return**

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

   * - **Value**
     - **Description**
   * - 1
     - The configuration datagram was sent.
   * - 0
     - The configuration datagram could not be sent.

.. note::

   This function does not wait for the controller to acknowledge the configuration. A return value of 1 means only that the datagram was sent; it does not confirm that the version, period or loss count were accepted. A rejected configuration is reported through :ref:`set_on_rt_log_alarm <set_on_rt_log_alarm>`.

**Example**

.. code-block:: cpp

   // Connect and configure RT input data
   drfl.connect_rt_control("192.168.137.100", 12347);

   std::string version = "v1.0";
   float period = 0.001f;   // 1 msec = 1 kHz
   int lossCount = 4;

   if (drfl.set_rt_control_input(version, period, lossCount))
       printf("RT input configuration set successfully.\n");
   else
       printf("Failed to set RT input configuration.\n");

   drfl.disconnect_rt_control();

In this example, the function sets the RT input configuration for version `"v1.0"`  
with a 1 ms update rate and a loss tolerance of 4 consecutive packets.

**Tips**

- For stable performance, use a **period between 0.002 s and 0.01 s** depending on network conditions.  
- Matching input/output periods ensures smoother real-time synchronization.  
- If the connection drops frequently, increase ``nLossCnt``. The time the robot tolerates silence is ``fPeriod`` x ``nLossCnt``.