Geolocalizador-RT

Geolocalizador-RT is an educational distributed-systems prototype written in C. It models a mobile device sending coordinates to a central server, defines a compact request/response protocol and runs the server under Linux SCHED_RR real-time scheduling.

The project was created to explore three areas together:

• POSIX socket programming in C.
• Client-server protocol design over UDP.
• Real-time process scheduling on Linux with PREEMPT_RT.

The current implementation deliberately simulates the geolocation layer. The client uses test coordinates, while the server generates or returns synthetic positions. A real GPS receiver and persistent database are proposed as future extensions.

• Creating IPv4 UDP sockets with socket, bind, sendto and recvfrom.
• Resolving a server name or IPv4 address from a C client.
• Serving multiple independent datagrams without creating a connection per client.
• Defining four application commands and positive/negative responses.
• Parsing protocol messages and dispatching operations on the server.
• Applying the SCHED_RR policy with a static real-time priority of 85.
• Separating the interactive client from the continuously running server.
• Reasoning about how GPS acquisition and storage could extend a simulation into a complete distributed application.

flowchart LR
    A["Client 1"] -->|"UDP :50005"| C["Geolocation server"]
    B["Client N"] -->|"UDP :50005"| C
    C --> D["Protocol dispatcher"]
    D --> E["SCHED_RR priority 85"]

The client represents a mobile device. It prepares protocol commands, sends them to the server and displays the replies through a terminal menu. The server binds to every local IPv4 interface on UDP port 50005, processes one datagram at a time and replies to the source address.

The original target was a Raspberry Pi running Raspbian with a PREEMPT_RT kernel. Client and server can also communicate through localhost for a controlled demonstration.

The client presents five operations:

Both programs currently use the fixed device ID 373.

Messages are sent as individual UDP datagrams. Although the original report discusses IEEE 754 as a compact representation, the checked-in implementation serializes every command and coordinate as an ASCII string.

LST returns one coordinate datagram per requested result, followed by a final OK. LSL returns one coordinate datagram followed by OK.

The report is the most detailed record of the original experiment. It explains the intended Raspberry Pi setup, every menu operation, the four protocol commands and why round-robin real-time scheduling was selected.

• A Linux system.
• GCC or another C compiler compatible with the POSIX networking interfaces.
• IPv4 connectivity between client and server.
• Permission to use UDP port 50005.

• A Linux kernel configured with PREEMPT_RT.
• Permission to select a real-time scheduling policy, normally through root privileges, CAP_SYS_NICE or a suitable RLIMIT_RTPRIO.
• An isolated test system where a high-priority process cannot disrupt unrelated workloads.

The code requests SCHED_RR unconditionally. If the process lacks the required permission, the server exits with:

sched_setscheduler() failed: Operation not permitted

Containers can produce the same error even when the process appears to run as root, because the required capability may not be available.

Clone the repository and compile both translation units:

git clone https://github.com/jagumiel/Geolocalizador-RT.git
cd Geolocalizador-RT

cc -std=gnu11 -O2 -Wall -Wextra cliente_geo.c -o cliente_geo
cc -std=gnu11 -O2 -Wall -Wextra servidor_geo.c -o servidor_geo

The historical sources compile with a current GCC toolchain, but they produce warnings. Compilation success should not be interpreted as evidence that the known runtime issues have been corrected.

Use two terminals on an isolated Linux system.

The simplest historical reproduction is to run the server with sufficient privileges:

sudo ./servidor_geo

Running an entire network process as root is not an appropriate production design. A modern revision should grant only the required capability, provide a non-real-time fallback and reduce privileges immediately after configuring the scheduler.

Connect through the loopback interface:

./cliente_geo 127.0.0.1

For a second host, replace 127.0.0.1 with the server's IPv4 address or a resolvable hostname. Do not expose the current protocol to an untrusted network.

The active policy and priority can be inspected from another terminal:

server_pid="$(pgrep -n servidor_geo)"
chrt -p "$server_pid"

Stop the server with Ctrl+C when the experiment is complete.

Real time does not simply mean “fast”. It means that timing behaviour is bounded and predictable enough for the application's deadlines.

This prototype asks Linux to schedule the server with:

param.sched_priority = 85;
sched_setscheduler(0, SCHED_RR, &param);

SCHED_RR gives runnable real-time tasks at the same priority a round-robin time quantum. A PREEMPT_RT kernel can reduce operating-system scheduling latency, while the elevated priority allows the server to pre-empt ordinary SCHED_OTHER work.

The current application does not, however, establish an end-to-end real-time guarantee:

• UDP delivery time and packet loss are not controlled.
• No deadline, period or worst-case execution time is defined.
• The client is interactive and is not assigned a real-time policy.
• There is no GPS acquisition loop with deterministic sampling.
• Latency, jitter and deadline misses are not measured.

The repository should therefore be understood as an experiment with a real-time scheduling primitive, rather than a validated hard-real-time geolocation system.

The code is preserved as an educational snapshot. The following limitations are present in the checked-in implementation:

• Coordinates and device identity are simulated; there is no GPS integration.
• SAV and RST acknowledge requests without persisting or deleting data.
• LST generates pseudo-random positions and LSL returns a fixed position.
• The server cannot fall back to normal scheduling when SCHED_RR is denied.
• The input function used to request the list length evaluates strlen on an uninitialized buffer, which is undefined behaviour.
• Received datagrams are not consistently terminated and validated before being treated as C strings.
• One server response sends the complete 1,024-byte buffer instead of the actual payload length.
• Several return values, parsed-field counts and message boundaries are not checked rigorously.
• An unknown command terminates the server instead of returning a protocol error and continuing.
• The client can wait indefinitely because there are no socket timeouts, retries, sequence numbers or duplicate detection.
• The implementation is IPv4-only and uses the legacy gethostbyname resolver.
• The report's proposed binary floating-point representation does not match the ASCII wire format implemented in the source.
• The protocol provides no authentication, encryption, replay protection or access control. Real location data would be sensitive personal data.
• There is no build system, automated test suite, continuous integration or repeatable latency benchmark.

If you are using this repository as a systems-programming lab, useful experiments include:

1. Capture the four commands with Wireshark and document the actual datagrams.
2. Compare UDP with a TCP implementation and explain the reliability trade-off.
3. Add socket receive timeouts and simulate packet loss.
4. Replace the fixed client coordinates with data from a GPS simulator.
5. Measure round-trip latency under CPU and I/O load.
6. Compare SCHED_OTHER, SCHED_RR and a PREEMPT_RT kernel using the same workload.

Este repositorio implementa un prototipo académico cliente-servidor en C para simular el envío de coordenadas mediante sockets UDP. El servidor interpreta un protocolo propio con los comandos SAV, LST, LSL y RST, y solicita una política de planificación Linux SCHED_RR con prioridad 85.

La geolocalización es simulada: no existe integración con GPS ni persistencia en una base de datos. Su valor principal está en mostrar programación de sistemas, diseño de protocolos, comunicaciones distribuidas y una primera aproximación a Linux de tiempo real. La memoria técnica incluida documenta en español la arquitectura, las pruebas originales y la evolución prevista.

• Original project report
• Linux scheduling policies and privileges
• Linux chrt command
• Linux kernel documentation: real-time preemption

This project is distributed under the MIT License.

Jose Ángel Gumiel

• GitHub
• Website and technical blog