1.. _latmon:
2
3Latmon Network Service
4######################
5
6.. contents::
7    :local:
8    :depth: 2
9
10Overview
11********
12
13Provides the functionality required for network-based latency monitoring, including socket
14management, client-server communication, and data exchange with the Latmus service running
15on the System Under Test (SUT).
16
17The Latmon network service is responsible for establishing and managing network
18communication between the Latmon application (running on a Zephyr-based board) and
19the Latmus service (running on the SUT).
20
21It uses TCP sockets for reliable communication and UDP sockets for broadcasting
22the IP address of the Latmon device.
23
24API Reference
25*************
26
27.. doxygengroup:: latmon
28
29Features
30********
31
32- **Socket Management**: Creates and manages TCP and UDP sockets for communication.
33- **Client-Server Communication**: Handles incoming connections from the Latmus service.
34- **Data Exchange**: Sends latency metrics and histogram data to the Latmus service.
35- **IP Address Broadcasting**: Broadcasts the IP address of the Latmon device to facilitate
36  discovery by the Latmus service.
37- **Thread-Safe Design**: Uses Zephyr's kernel primitives (e.g., message queues and semaphores) for
38  synchronization.
39
40Workflow
41********
42
43Socket Creation
44===============
45
46The :c:func:`net_latmon_get_socket()` function is called to create and configure a TCP socket to
47communicate with the Latmus service. A connection address can be specified as a paramenter to
48bind the socket to a specific interface and port.
49
50Connection Handling
51===================
52
53The :c:func:`net_latmon_connect()` function waits for a connection from the Latmus service.
54If no connection is received within the timeout period, the service broadcasts its IP address
55using UDP and returns ``-EAGAIN``.
56If the broadcast request cannot be sent, the function returns ``-1``, and the client should quit.
57
58Monitoring Start
59================
60
61Once a connection is established, the :c:func:`net_latmon_start()` function is called to
62start the monitoring process. This function uses a callback to calculate latency deltas
63and sends the data to the Latmus service.
64
65Monitoring Status
66=================
67
68The :c:func:`net_latmon_running()` function can be used to check if the monitoring process is active.
69
70Thread Management
71=================
72
73The service uses Zephyr threads to handle incoming connections and manage the monitoring
74process.
75
76Enabling the Latmon Service
77***************************
78
79The following configuration option must be enabled in the :file:`prj.conf` file.
80
81- :kconfig:option:`CONFIG_NET_LATMON`
82
83The following options may be configured to customize the Latmon service:
84
85- :kconfig:option:`CONFIG_NET_LATMON_PORT` - Port number for the Latmon service.
86- :kconfig:option:`CONFIG_NET_LATMON_XFER_THREAD_STACK_SIZE`
87- :kconfig:option:`CONFIG_NET_LATMON_XFER_THREAD_PRIORITY`
88- :kconfig:option:`CONFIG_NET_LATMON_THREAD_STACK_SIZE`
89- :kconfig:option:`CONFIG_NET_LATMON_THREAD_PRIORITY`
90- :kconfig:option:`CONFIG_NET_LATMON_MONITOR_THREAD_STACK_SIZE`
91- :kconfig:option:`CONFIG_NET_LATMON_MONITOR_THREAD_PRIORITY`
92
93Example Usage
94*************
95
96.. code-block:: c
97
98    #include <zephyr/net/latmon.h>
99    #include <zephyr/net/socket.h>
100
101    void main(void)
102    {
103        struct in_addr ip;
104        int server_socket, client_socket;
105
106        /* Create and configure the server socket */
107        server_socket = net_latmon_get_socket(NULL);
108
109        while (1) {
110            /* Wait for a connection from the Latmus service */
111            client_socket = net_latmon_connect(server_socket, &ip);
112            if (client_socket < 0) {
113                if (client_socket == -EAGAIN) {
114                    continue;
115                }
116                goto out;
117            }
118
119            /* Start the latency monitoring process */
120            net_latmon_start(client_socket, measure_latency_cycles);
121        }
122    out:
123        close(server_socket);
124    }
125