.. _connect_rt_control:

connect_rt_control
------------------------------------------
This function establishes a **UDP/IP connection** between the external PC and the robot controller  
to enable **Real-time External Control (RT)** communication. |br|
This channel is independent of the original TCP/IP API, and control authority does not apply to it. |br|
For the integrated controller (v3), versions v3.3 or below can be connected to 192.168.137.50. 

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

.. code-block:: cpp

   bool connect_rt_control(string strIpAddr = "192.168.137.100", 
                           unsigned int usPort = 12347) {
       return _connect_rt_control(_rbtCtrlUDP, strIpAddr.c_str(), usPort);
   };

**Parameter**

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

   * - **Parameter Name**
     - **Data Type**
     - **Default Value**
     - **Description**
   * - strIpAddr
     - string
     - ``"192.168.137.100"``
     - Target controller IP address for the UDP connection. Pass the controller address as a dotted IPv4 string (for example ``"192.168.137.100"``).
   * - usPort
     - unsigned int
     - ``12347``
     - Port number for RT communication (default UDP port).

**Return**

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

   * - **Value**
     - **Description**
   * - 1
     - The controller completed the connect handshake.
   * - 0
     - The RT channel is not connected. Causes: the UDP socket cannot be opened; the controller does not answer within about 5 seconds; the connection drops during the handshake; the :ref:`set_rt_thread_priority <set_rt_thread_priority>` setting cannot be applied; the library cannot start its real-time processing; real-time control is already connected (the library prints ``Already connected``); or the function is called from inside a real-time callback (the library prints ``connect_rt_control() cannot be called from an RT callback``). Except for the last two cases, the function closes the RT channel before returning, and a later call can connect again.

.. Caution::

   - Do not call this function from inside a real-time callback, such as the one registered with :ref:`set_on_rt_monitoring_data <set_on_rt_monitoring_data>`. It returns 0 there.
   - If the controller does not answer, for example because the IP address or port is wrong, or because another RT client is already connected to the controller, the function returns 0 after about 5 seconds.

**Typical usage**

- Connect before configuring RT control input/output schema and period.  
- Used as the first step of any **real-time joint or task control loop**.  

**Note**

- Real-time external control uses **UDP/IP** communication, not TCP/IP.  
- This channel runs independently of the TCP/IP API connection. It has no commands for control authority or safety settings; use the TCP/IP API for those.
- On integrated controllers (v3.x) up to **v3.3**, the RT server accepts connections on every controller address, including **192.168.137.50**. From v3.4, it accepts them only on the API address (default 192.168.137.100).
- Default configuration supports **1-to-1** UDP communication between controller and external PC.
- When the controller ends the RT session, it reports an alarm to the :ref:`set_on_rt_log_alarm <set_on_rt_log_alarm>` callback, and RT data stops.
- RT has no disconnect notification. To detect a lost RT link, check that time_stamp in read_data_rt or the RT callback keeps advancing.
- After :ref:`disconnect_rt_control <disconnect_rt_control>`, the RT channel can be connected again in the same process.
- To see why the connection fails, register :ref:`set_on_rt_log_alarm <set_on_rt_log_alarm>` before calling this function.
- If the real-time connection closes, wait at least 5 seconds before calling this function again. On the simulator, restart the simulator instead.

**Example**

.. code-block:: cpp

   // Connect to the robot controller via UDP for RT control
   if (drfl.connect_rt_control("192.168.137.100", 12347)) {
       printf("RT connection established successfully.\n");

       // Ready to configure input/output schema and start RT streaming
       drfl.start_rt_control();
   } 
   else {
       printf("RT connection failed.\n");
   }

In this example, the function establishes a UDP connection with the controller  
to prepare for real-time motion control or high-frequency data exchange.  
Once connected, users can call :ref:`start_rt_control <start_rt_control>` to begin RT streaming.

**Tips**

- Ensure the robot is powered and reachable on the specified IP before calling this function.  
- Close the RT channel gracefully using :ref:`disconnect_rt_control <disconnect_rt_control>` after operations.  
- In real-time applications, this step should be followed by setting the **input/output version and period**  
  using :ref:`set_rt_control_input <set_rt_control_input>` and :ref:`set_rt_control_output <set_rt_control_output>`.