.. _cb_tonrtmonitoringdatacb:

TOnRTMonitoringDataCB
------------------------------------------
This is a **real-time callback function** that provides robot operation data at high-frequency intervals  
through the **UDP-based real-time communication interface**. |br|
It allows continuous monitoring of key robot states (joint position, torque, external force, etc.)  
in applications requiring low-latency feedback.

The callback is called once per output period set with :ref:`set_rt_control_output <set_rt_control_output>`.

See :ref:`Rules for callback functions <callback_rules>`.

**Defined in:** ``DRFLEx.h``

.. code-block:: cpp

   // typedef (DRFLEx.h)
   typedef void (*TOnRTMonitoringDataCB)(const LPRT_OUTPUT_DATA_LIST);

   // internal definition
   DRFL_API void _set_on_rt_monitoring_data(LPROBOTCONTROL pCtrl, TOnRTMonitoringDataCB pCallbackFunc);

   // user-callable wrapper (UDP real-time control interface)
   void set_on_rt_monitoring_data(TOnRTMonitoringDataCB pCallbackFunc)
   {
       _set_on_rt_monitoring_data(_rbtCtrlUDP, pCallbackFunc);
   };

**Parameter**

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

   * - Parameter Name
     - Data Type
     - Default Value
     - Description
   * - pRTData
     - :ref:`RT_OUTPUT_DATA_LIST <struct_RT_OUTPUT_DATA_LIST>`
     - -
     - Pointer to a structure containing **real-time monitoring data** such as joint position, torque, velocity, and status flags.

**Return** |br|
None

**Example**

.. code-block:: cpp

   #include "DRFLEx.h"
   #include <iostream>
   #include <iomanip>
   #include <mutex>
   #include <thread>
   #include <chrono>
   using namespace DRAFramework;
   using namespace std;

   // Latest sample, copied in the callback and printed by the main loop
   std::mutex g_mtxRT;
   RT_OUTPUT_DATA_LIST g_tLatestRT;
   bool g_bHasRT = false;

   // Real-time data callback (UDP): copy the data and return
   void OnRTMonitoringDataCB(const LPRT_OUTPUT_DATA_LIST pRTData)
   {
       if (!pRTData) return;

       std::lock_guard<std::mutex> lock(g_mtxRT);
       g_tLatestRT = *pRTData;
       g_bHasRT = true;
   }

   void PrintRTData(const RT_OUTPUT_DATA_LIST& tData)
   {
       cout << fixed << setprecision(3);
       cout << "[REAL-TIME MONITORING DATA]" << endl;

       // Display joint positions
       cout << "Joint positions [deg]: ";
       for (int i = 0; i < NUM_JOINT; i++)
           cout << setw(8) << tData.actual_joint_position[i] << " ";
       cout << endl;

       // Display external torques
       cout << "External torque [Nm]: ";
       for (int i = 0; i < NUM_JOINT; i++)
           cout << setw(8) << tData.external_joint_torque[i] << " ";
       cout << endl;

       // Display tool force
       cout << "Tool force [N]: ";
       for (int i = 0; i < 3; i++)
           cout << setw(8) << tData.external_tcp_force[i] << " ";
       cout << endl;

       cout << "------------------------------------" << endl;
   }

   int main()
   {
       CDRFLEx drfl;

       // Connect to controller in real-time mode (UDP)
       if (!drfl.connect_rt_control("192.168.137.100")) {
           cout << "Failed to connect to controller (RT mode)." << endl;
           return -1;
       }

       // Register callback for RT monitoring
       drfl.set_on_rt_monitoring_data(OnRTMonitoringDataCB);

       // Select the output data version and period, then start the stream
       drfl.set_rt_control_output("v1.0", 0.002f, 4);
       drfl.start_rt_control();

       // Main loop: print the latest sample every 100 ms
       while (true) {
           RT_OUTPUT_DATA_LIST tData;
           bool bHasData = false;
           {
               std::lock_guard<std::mutex> lock(g_mtxRT);
               tData = g_tLatestRT;
               bHasData = g_bHasRT;
           }
           if (bHasData)
               PrintRTData(tData);
           std::this_thread::sleep_for(std::chrono::milliseconds(100));
       }

       drfl.disconnect_rt_control();
       return 0;
   }

**Notes**

- This callback is called once per output period set with :ref:`set_rt_control_output <set_rt_control_output>`.
- Typical fields accessible in :ref:`RT_OUTPUT_DATA_LIST <struct_RT_OUTPUT_DATA_LIST>` include: |br|
  - Joint positions, velocities, and torques |br|
  - External TCP force and moment |br|
  - Digital/analog input states |br|
  - System and motion flags |br|
- Recommended use cases: |br|
  - Real-time visualization of robot motion |br|
  - Force-based control or adaptive compliance monitoring |br|
  - Research or control experiments using low-latency feedback |br|
- Do not call ``get_rt_control_input_version_list``, ``get_rt_control_output_version_list``, ``get_rt_control_input_data_list``, ``get_rt_control_output_data_list`` or ``disconnect_rt_control`` from an RT callback; the call does not return. ``connect_rt_control`` called from an RT callback returns false and prints ``Already connected``.
- Use this callback **only when DRCF_VERSION ≥ 2** and the **UDP interface** is properly initialized.