feat: standalone C/C++ UDPS client library
Consuming a UDPStreamer feed so far meant either linking MARTe2 (UDPSClient) or writing Go (Common/Client/go/udpsprotocol). Common/Client/c fills the gap for plain C/C++ integrators: two files depending on nothing but libc and BSD sockets, covering the whole receive path — CONNECT, fragment reassembly, CONFIG/DATA decoding with dequantisation, keepalives and silence-triggered reconnect. No threads are spawned; udps_client_poll() does all the work and runs every callback, so it drops into an existing event loop unsynchronised. Verified against run_udp_producer.sh at 1 Msps: unicast (120 MiB, no loss) and multicast with 12-fragment cycles (116k datagrams, no loss). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Martino Ferrari
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
e03c60db25
commit
7c5eb31a52
@@ -0,0 +1,5 @@
|
||||
*.o
|
||||
*.a
|
||||
udps_dump
|
||||
.cxxcheck
|
||||
.cxxcheck.cpp
|
||||
@@ -0,0 +1,46 @@
|
||||
# UDPS C client library — standalone, no MARTe2, no external dependencies.
|
||||
#
|
||||
# make build libudpsclient.a and the example
|
||||
# make example build only the example
|
||||
# make cxxcheck verify the header is usable from C++
|
||||
# make clean
|
||||
|
||||
CC ?= cc
|
||||
CXX ?= c++
|
||||
AR ?= ar
|
||||
CFLAGS ?= -O2 -g
|
||||
WARN = -Wall -Wextra -Wpedantic
|
||||
STD = -std=c99
|
||||
CPPFLAGS += -I.
|
||||
|
||||
# Old glibc (< 2.17) keeps clock_gettime in librt; harmless to add there.
|
||||
LDLIBS ?=
|
||||
|
||||
LIB = libudpsclient.a
|
||||
OBJ = udps_client.o
|
||||
EXAMPLE = udps_dump
|
||||
|
||||
.PHONY: all example cxxcheck clean
|
||||
|
||||
all: $(LIB) $(EXAMPLE)
|
||||
|
||||
$(LIB): $(OBJ)
|
||||
$(AR) rcs $@ $^
|
||||
|
||||
udps_client.o: udps_client.c udps_client.h
|
||||
$(CC) $(STD) $(WARN) $(CFLAGS) $(CPPFLAGS) -c -o $@ $<
|
||||
|
||||
example: $(EXAMPLE)
|
||||
|
||||
$(EXAMPLE): example/udps_dump.c $(LIB)
|
||||
$(CC) $(STD) $(WARN) $(CFLAGS) $(CPPFLAGS) -o $@ $< $(LIB) $(LDLIBS)
|
||||
|
||||
# The header is C++-safe; this target keeps it that way.
|
||||
cxxcheck: udps_client.h
|
||||
echo '#include "udps_client.h"' > .cxxcheck.cpp
|
||||
echo 'int main() { udps_client_config_t c; udps_client_config_init(&c); return 0; }' >> .cxxcheck.cpp
|
||||
$(CXX) -std=c++11 -Wall -Wextra $(CPPFLAGS) -o .cxxcheck .cxxcheck.cpp $(LIB) $(LDLIBS)
|
||||
./.cxxcheck && rm -f .cxxcheck .cxxcheck.cpp
|
||||
|
||||
clean:
|
||||
rm -f $(LIB) $(OBJ) $(EXAMPLE) .cxxcheck .cxxcheck.cpp
|
||||
@@ -0,0 +1,260 @@
|
||||
/**
|
||||
* @file udps_dump.c
|
||||
* @brief Example UDPS client: connects to a UDPStreamer and prints what arrives.
|
||||
*
|
||||
* Build with the Makefile in the parent directory, then for a unicast stream:
|
||||
*
|
||||
* ./udps_dump --host 127.0.0.1 --port 44500
|
||||
*
|
||||
* or, for a multicast one:
|
||||
*
|
||||
* ./udps_dump --host 127.0.0.1 --port 44500 \
|
||||
* --multicast 239.0.0.1 --iface 127.0.0.1
|
||||
*
|
||||
* Ctrl-C prints a summary of what was received.
|
||||
*/
|
||||
|
||||
#define _POSIX_C_SOURCE 200809L
|
||||
|
||||
#include "udps_client.h"
|
||||
|
||||
#include <signal.h>
|
||||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
#include <string.h>
|
||||
#include <time.h>
|
||||
|
||||
static volatile sig_atomic_t g_stop = 0;
|
||||
|
||||
static void on_sigint(int sig) {
|
||||
(void)sig;
|
||||
g_stop = 1;
|
||||
}
|
||||
|
||||
typedef struct {
|
||||
double print_interval; /**< Seconds between frame printouts. */
|
||||
double last_print;
|
||||
uint64_t frames;
|
||||
uint64_t max_frames;
|
||||
} dump_state_t;
|
||||
|
||||
static double now_wall(void) {
|
||||
struct timespec ts;
|
||||
clock_gettime(CLOCK_REALTIME, &ts);
|
||||
return (double)ts.tv_sec + (double)ts.tv_nsec * 1e-9;
|
||||
}
|
||||
|
||||
static const char *time_mode_name(uint8_t m) {
|
||||
switch (m) {
|
||||
case UDPS_TIME_PACKET: return "packet";
|
||||
case UDPS_TIME_FULL_ARRAY: return "full-array";
|
||||
case UDPS_TIME_FIRST_SAMPLE: return "first-sample";
|
||||
case UDPS_TIME_LAST_SAMPLE: return "last-sample";
|
||||
default: return "?";
|
||||
}
|
||||
}
|
||||
|
||||
static const char *publish_mode_name(uint8_t m) {
|
||||
switch (m) {
|
||||
case UDPS_PUBLISH_STRICT: return "strict";
|
||||
case UDPS_PUBLISH_ACCUMULATE: return "accumulate";
|
||||
case UDPS_PUBLISH_DECIMATE: return "decimate";
|
||||
default: return "?";
|
||||
}
|
||||
}
|
||||
|
||||
static void on_config(const udps_signal_t *sigs, uint32_t n, uint8_t mode,
|
||||
void *user) {
|
||||
uint32_t i;
|
||||
(void)user;
|
||||
printf("\nCONFIG: %u signal(s), publish mode %s\n", (unsigned)n,
|
||||
publish_mode_name(mode));
|
||||
printf(" %-3s %-24s %-8s %-10s %-8s %-10s %s\n", "#", "name", "type",
|
||||
"shape", "unit", "rate[Hz]", "time-mode");
|
||||
for (i = 0u; i < n; i++) {
|
||||
char shape[32];
|
||||
const udps_signal_t *s = &sigs[i];
|
||||
if (s->num_cols > 1u) {
|
||||
snprintf(shape, sizeof shape, "%ux%u", (unsigned)s->num_rows,
|
||||
(unsigned)s->num_cols);
|
||||
} else {
|
||||
snprintf(shape, sizeof shape, "%u",
|
||||
(unsigned)udps_signal_num_elements(s));
|
||||
}
|
||||
printf(" %-3u %-24s %-8s %-10s %-8s %-10.6g %s%s\n", (unsigned)i,
|
||||
s->name, udps_type_name(s->type_code), shape,
|
||||
(s->unit[0] != '\0') ? s->unit : "-", s->sampling_rate,
|
||||
time_mode_name(s->time_mode),
|
||||
(s->quant_type != UDPS_QUANT_NONE) ? " (quantised)" : "");
|
||||
}
|
||||
fflush(stdout);
|
||||
}
|
||||
|
||||
static void on_data(const udps_frame_t *f, void *user) {
|
||||
dump_state_t *st = (dump_state_t *)user;
|
||||
uint32_t i;
|
||||
double now;
|
||||
|
||||
st->frames++;
|
||||
now = now_wall();
|
||||
if ((now - st->last_print) < st->print_interval) {
|
||||
return; /* Streams run far faster than a terminal can be read. */
|
||||
}
|
||||
st->last_print = now;
|
||||
|
||||
printf("\nframe #%lu t=%.6f samples=%u (%lu frames so far)\n",
|
||||
(unsigned long)f->counter, f->recv_time, (unsigned)f->num_samples,
|
||||
(unsigned long)st->frames);
|
||||
for (i = 0u; i < f->num_signals; i++) {
|
||||
const double *v = f->values[i].values;
|
||||
uint32_t cnt = f->values[i].count;
|
||||
double lo, hi;
|
||||
uint32_t k;
|
||||
if (cnt == 0u) {
|
||||
continue;
|
||||
}
|
||||
lo = hi = v[0];
|
||||
for (k = 1u; k < cnt; k++) {
|
||||
if (v[k] < lo) {
|
||||
lo = v[k];
|
||||
}
|
||||
if (v[k] > hi) {
|
||||
hi = v[k];
|
||||
}
|
||||
}
|
||||
printf(" %-24s n=%-6u first=%-12.6g last=%-12.6g min=%-12.6g max=%-12.6g %s\n",
|
||||
f->signals[i].name, (unsigned)cnt, v[0], v[cnt - 1u], lo, hi,
|
||||
f->signals[i].unit);
|
||||
}
|
||||
fflush(stdout);
|
||||
}
|
||||
|
||||
static void on_event(udps_event_t ev, const char *detail, void *user) {
|
||||
(void)user;
|
||||
switch (ev) {
|
||||
case UDPS_EVENT_CONNECTED:
|
||||
printf("[connected to %s]\n", detail ? detail : "");
|
||||
break;
|
||||
case UDPS_EVENT_DISCONNECTED:
|
||||
printf("[disconnected: %s]\n", detail ? detail : "");
|
||||
break;
|
||||
case UDPS_EVENT_ERROR:
|
||||
fprintf(stderr, "[error] %s\n", detail ? detail : "");
|
||||
break;
|
||||
default:
|
||||
break;
|
||||
}
|
||||
fflush(stdout);
|
||||
}
|
||||
|
||||
static void usage(const char *argv0) {
|
||||
printf("Usage: %s --host ADDR --port N [options]\n"
|
||||
"\n"
|
||||
" --host ADDR server address (default 127.0.0.1)\n"
|
||||
" --port N server UDP port, or TCP control port in multicast\n"
|
||||
" mode (default 44500)\n"
|
||||
" --multicast GROUP join GROUP for data instead of unicast\n"
|
||||
" --iface ADDR local interface address for the multicast join\n"
|
||||
" --data-port N multicast data port (default: --port + 1)\n"
|
||||
" --silence SEC reconnect after SEC without data (default 1, 0 off)\n"
|
||||
" --interval SEC seconds between printouts (default 1)\n"
|
||||
" --frames N exit after N frames (default: run until Ctrl-C)\n"
|
||||
" --help this text\n",
|
||||
argv0);
|
||||
}
|
||||
|
||||
int main(int argc, char **argv) {
|
||||
udps_client_config_t cfg;
|
||||
udps_client_t *cli;
|
||||
dump_state_t st;
|
||||
udps_stats_t stats;
|
||||
struct sigaction sa;
|
||||
const char *host = "127.0.0.1";
|
||||
int i;
|
||||
|
||||
udps_client_config_init(&cfg);
|
||||
cfg.server_port = 44500u;
|
||||
|
||||
memset(&st, 0, sizeof st);
|
||||
st.print_interval = 1.0;
|
||||
|
||||
for (i = 1; i < argc; i++) {
|
||||
const char *a = argv[i];
|
||||
const char *next = (i + 1 < argc) ? argv[i + 1] : NULL;
|
||||
if (strcmp(a, "--help") == 0) {
|
||||
usage(argv[0]);
|
||||
return 0;
|
||||
}
|
||||
if (next == NULL) {
|
||||
fprintf(stderr, "missing value for %s\n", a);
|
||||
return 2;
|
||||
}
|
||||
if (strcmp(a, "--host") == 0) {
|
||||
host = next;
|
||||
} else if (strcmp(a, "--port") == 0) {
|
||||
cfg.server_port = (uint16_t)atoi(next);
|
||||
} else if (strcmp(a, "--multicast") == 0) {
|
||||
cfg.multicast_group = next;
|
||||
} else if (strcmp(a, "--iface") == 0) {
|
||||
cfg.interface_addr = next;
|
||||
} else if (strcmp(a, "--data-port") == 0) {
|
||||
cfg.data_port = (uint16_t)atoi(next);
|
||||
} else if (strcmp(a, "--silence") == 0) {
|
||||
cfg.silence_timeout_s = atof(next);
|
||||
} else if (strcmp(a, "--interval") == 0) {
|
||||
st.print_interval = atof(next);
|
||||
} else if (strcmp(a, "--frames") == 0) {
|
||||
st.max_frames = (uint64_t)strtoull(next, NULL, 10);
|
||||
} else {
|
||||
fprintf(stderr, "unknown option %s\n", a);
|
||||
usage(argv[0]);
|
||||
return 2;
|
||||
}
|
||||
i++;
|
||||
}
|
||||
cfg.server_addr = host;
|
||||
|
||||
cli = udps_client_create(&cfg);
|
||||
if (cli == NULL) {
|
||||
fprintf(stderr, "could not create client for %s:%u\n", host,
|
||||
(unsigned)cfg.server_port);
|
||||
return 1;
|
||||
}
|
||||
udps_client_set_callbacks(cli, on_config, on_data, on_event, &st);
|
||||
|
||||
memset(&sa, 0, sizeof sa);
|
||||
sa.sa_handler = on_sigint;
|
||||
(void)sigaction(SIGINT, &sa, NULL);
|
||||
(void)sigaction(SIGTERM, &sa, NULL);
|
||||
|
||||
printf("listening to %s:%u%s%s ... (Ctrl-C to stop)\n", host,
|
||||
(unsigned)cfg.server_port,
|
||||
cfg.multicast_group ? " via multicast " : "",
|
||||
cfg.multicast_group ? cfg.multicast_group : "");
|
||||
|
||||
while (!g_stop && (st.max_frames == 0u || st.frames < st.max_frames)) {
|
||||
/* All the work — connecting, receiving, decoding, reconnecting — and
|
||||
* every callback happens inside this call. */
|
||||
(void)udps_client_poll(cli, 200);
|
||||
}
|
||||
|
||||
udps_client_stats(cli, &stats);
|
||||
printf("\n--- summary ---\n"
|
||||
"packets %lu\n"
|
||||
"bytes %.1f MiB\n"
|
||||
"frames %lu\n"
|
||||
"configs %lu\n"
|
||||
"gaps %lu (datagrams lost)\n"
|
||||
"dropped %lu (fragments)\n"
|
||||
"reconnects %lu\n",
|
||||
(unsigned long)stats.packets_received,
|
||||
(double)stats.bytes_received / (1024.0 * 1024.0),
|
||||
(unsigned long)stats.frames_delivered,
|
||||
(unsigned long)stats.config_updates,
|
||||
(unsigned long)stats.counter_gaps,
|
||||
(unsigned long)stats.fragments_dropped,
|
||||
(unsigned long)stats.reconnects);
|
||||
|
||||
udps_client_destroy(cli);
|
||||
return 0;
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,324 @@
|
||||
#ifndef UDPS_CLIENT_H
|
||||
#define UDPS_CLIENT_H
|
||||
|
||||
/**
|
||||
* @file udps_client.h
|
||||
* @brief Standalone UDPS (UDPStreamer) receiver library — C99, no MARTe2.
|
||||
*
|
||||
* Depends only on libc and BSD sockets, so it can be dropped into any C or C++
|
||||
* program that needs to consume a UDPStreamer / DebugService stream. The wire
|
||||
* format is specified in Docs/Protocol.md; the library reference (and a worked
|
||||
* example) is Docs/UDPS-C-Client.md.
|
||||
*
|
||||
* Usage in one paragraph: fill a udps_client_config_t, create a client, install
|
||||
* callbacks, then call udps_client_poll() in a loop. The client owns the
|
||||
* connection state machine — it sends CONNECT, reassembles fragmented packets,
|
||||
* decodes CONFIG and DATA, sends keepalives, and reconnects when the server
|
||||
* goes silent. Nothing is done behind your back: no threads are created and
|
||||
* every callback runs inside your call to udps_client_poll().
|
||||
*
|
||||
* Threading: a udps_client_t must be used from one thread at a time.
|
||||
*/
|
||||
|
||||
#include <stddef.h>
|
||||
#include <stdint.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/* Protocol constants */
|
||||
/*---------------------------------------------------------------------------*/
|
||||
|
||||
/** Magic number: ASCII 'UDPS' stored little-endian. */
|
||||
#define UDPS_MAGIC 0x53504455u
|
||||
|
||||
/** Size of the packed packet header on the wire. */
|
||||
#define UDPS_HEADER_SIZE 17u
|
||||
|
||||
/** Size of one serialised signal descriptor in a CONFIG payload. */
|
||||
#define UDPS_SIGNAL_DESC_SIZE 136u
|
||||
|
||||
/** Value of udps_signal_t::time_signal_idx when the signal has no time reference. */
|
||||
#define UDPS_NO_TIME_SIGNAL 0xFFFFFFFFu
|
||||
|
||||
/** Upper bound on elements per signal; larger descriptors are rejected. */
|
||||
#define UDPS_MAX_ELEMENTS (1u << 20)
|
||||
|
||||
/** Packet types (udps_header_t::type). */
|
||||
enum {
|
||||
UDPS_PKT_DATA = 0, /**< Server -> client: signal samples. */
|
||||
UDPS_PKT_CONFIG = 1, /**< Server -> client: signal metadata. */
|
||||
UDPS_PKT_ACK = 2, /**< Client -> server: keepalive. */
|
||||
UDPS_PKT_CONNECT = 3, /**< Client -> server: open a session. */
|
||||
UDPS_PKT_DISCONNECT = 4 /**< Either direction: close a session. */
|
||||
};
|
||||
|
||||
/** Sample type codes (udps_signal_t::type_code). */
|
||||
enum {
|
||||
UDPS_T_UINT8 = 0,
|
||||
UDPS_T_INT8 = 1,
|
||||
UDPS_T_UINT16 = 2,
|
||||
UDPS_T_INT16 = 3,
|
||||
UDPS_T_UINT32 = 4,
|
||||
UDPS_T_INT32 = 5,
|
||||
UDPS_T_UINT64 = 6,
|
||||
UDPS_T_INT64 = 7,
|
||||
UDPS_T_FLOAT32 = 8,
|
||||
UDPS_T_FLOAT64 = 9,
|
||||
UDPS_T_UNKNOWN = 255
|
||||
};
|
||||
|
||||
/** Quantisation codes (udps_signal_t::quant_type). */
|
||||
enum {
|
||||
UDPS_QUANT_NONE = 0, /**< Raw values in the signal's own type. */
|
||||
UDPS_QUANT_UINT8 = 1, /**< [range_min, range_max] mapped onto uint8. */
|
||||
UDPS_QUANT_INT8 = 2,
|
||||
UDPS_QUANT_UINT16 = 3,
|
||||
UDPS_QUANT_INT16 = 4
|
||||
};
|
||||
|
||||
/** Time-reference modes (udps_signal_t::time_mode). */
|
||||
enum {
|
||||
UDPS_TIME_PACKET = 0, /**< No per-element time; use packet arrival. */
|
||||
UDPS_TIME_FULL_ARRAY = 1, /**< The time signal carries one stamp per element. */
|
||||
UDPS_TIME_FIRST_SAMPLE = 2, /**< Time signal (scalar) stamps element 0. */
|
||||
UDPS_TIME_LAST_SAMPLE = 3 /**< Time signal (scalar) stamps element N-1. */
|
||||
};
|
||||
|
||||
/** Publishing modes (udps_frame_t::publish_mode). */
|
||||
enum {
|
||||
UDPS_PUBLISH_STRICT = 0, /**< One packet per RT cycle. */
|
||||
UDPS_PUBLISH_ACCUMULATE = 1, /**< A batch of cycles per packet. */
|
||||
UDPS_PUBLISH_DECIMATE = 2 /**< One packet every N cycles. */
|
||||
};
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/* Data model */
|
||||
/*---------------------------------------------------------------------------*/
|
||||
|
||||
/** Decoded 17-byte packet header. */
|
||||
typedef struct {
|
||||
uint32_t magic;
|
||||
uint8_t type;
|
||||
uint32_t counter; /**< Same for every fragment of one update. */
|
||||
uint16_t fragment_idx;
|
||||
uint16_t total_fragments; /**< 1 when the update fits in one datagram. */
|
||||
uint32_t payload_bytes;
|
||||
} udps_header_t;
|
||||
|
||||
/** Metadata for one streamed signal, as carried by the CONFIG payload. */
|
||||
typedef struct {
|
||||
char name[65]; /**< NUL-terminated. */
|
||||
uint8_t type_code; /**< UDPS_T_*. */
|
||||
uint8_t quant_type; /**< UDPS_QUANT_*. */
|
||||
uint8_t num_dimensions; /**< 0 scalar, 1 vector, 2 matrix. */
|
||||
uint32_t num_rows;
|
||||
uint32_t num_cols;
|
||||
double range_min; /**< Physical range, used to dequantise. */
|
||||
double range_max;
|
||||
uint8_t time_mode; /**< UDPS_TIME_*. */
|
||||
double sampling_rate; /**< Hz; 0 when unknown. */
|
||||
uint32_t time_signal_idx;/**< Index into the signal list, or UDPS_NO_TIME_SIGNAL. */
|
||||
char unit[33]; /**< NUL-terminated. */
|
||||
} udps_signal_t;
|
||||
|
||||
/**
|
||||
* @brief Decoded values of one signal within a frame.
|
||||
*
|
||||
* Values are always physical doubles: quantised signals are already expanded
|
||||
* back onto [range_min, range_max]. @c count is @c num_samples for a scalar
|
||||
* signal in Accumulate mode (one value per batched cycle) and the signal's
|
||||
* element count in every other case.
|
||||
*/
|
||||
typedef struct {
|
||||
const double *values;
|
||||
uint32_t count;
|
||||
} udps_signal_values_t;
|
||||
|
||||
/** One fully decoded DATA packet. */
|
||||
typedef struct {
|
||||
uint32_t counter; /**< Packet counter; gaps mean lost datagrams. */
|
||||
uint64_t hrt; /**< Producer's high-resolution timer at send. */
|
||||
double recv_time; /**< Wall-clock seconds (CLOCK_REALTIME) at arrival. */
|
||||
uint8_t publish_mode; /**< UDPS_PUBLISH_*. */
|
||||
uint32_t num_samples; /**< Batched cycles; 1 unless Accumulate. */
|
||||
uint32_t num_signals;
|
||||
const udps_signal_t *signals; /**< num_signals entries, CONFIG order. */
|
||||
const udps_signal_values_t *values; /**< num_signals entries, same order. */
|
||||
} udps_frame_t;
|
||||
|
||||
/** Connection lifecycle events reported through udps_event_cb. */
|
||||
typedef enum {
|
||||
UDPS_EVENT_CONNECTED, /**< Sockets are up and CONNECT was sent. */
|
||||
UDPS_EVENT_DISCONNECTED, /**< Session dropped; the client will retry. */
|
||||
UDPS_EVENT_ERROR /**< Recoverable problem; detail says what. */
|
||||
} udps_event_t;
|
||||
|
||||
/** Cumulative counters, never reset. */
|
||||
typedef struct {
|
||||
uint64_t packets_received; /**< Datagrams (and TCP frames) accepted. */
|
||||
uint64_t bytes_received;
|
||||
uint64_t frames_delivered; /**< DATA packets decoded and handed to you. */
|
||||
uint64_t config_updates;
|
||||
uint64_t fragments_dropped; /**< Duplicate, stale or unplaceable fragments. */
|
||||
uint64_t counter_gaps; /**< DATA packets missing from the sequence. */
|
||||
uint64_t reconnects;
|
||||
} udps_stats_t;
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/* Client */
|
||||
/*---------------------------------------------------------------------------*/
|
||||
|
||||
typedef struct udps_client udps_client_t;
|
||||
|
||||
/** Called whenever a CONFIG packet redefines the signal set. */
|
||||
typedef void (*udps_config_cb)(const udps_signal_t *signals,
|
||||
uint32_t num_signals,
|
||||
uint8_t publish_mode,
|
||||
void *user);
|
||||
|
||||
/**
|
||||
* @brief Called for every decoded DATA packet.
|
||||
*
|
||||
* The frame and everything it points at are owned by the client and are only
|
||||
* valid until the callback returns — copy anything you need to keep.
|
||||
*/
|
||||
typedef void (*udps_data_cb)(const udps_frame_t *frame, void *user);
|
||||
|
||||
/** Called on connection state changes and on recoverable errors. */
|
||||
typedef void (*udps_event_cb)(udps_event_t event, const char *detail, void *user);
|
||||
|
||||
/**
|
||||
* @brief Transport configuration.
|
||||
*
|
||||
* Zero-initialise with udps_client_config_init(), then override what you need.
|
||||
* Set @c multicast_group to switch from unicast to multicast: in unicast the
|
||||
* client sends CONNECT over UDP and receives everything on its ephemeral port;
|
||||
* in multicast it joins the group for DATA and opens a TCP control connection
|
||||
* to @c server_port for CONNECT and CONFIG.
|
||||
*/
|
||||
typedef struct {
|
||||
const char *server_addr; /**< IPv4 dotted quad. Required. */
|
||||
uint16_t server_port; /**< UDP port (unicast) or TCP port (multicast). Required. */
|
||||
const char *multicast_group;/**< IPv4 group; NULL selects unicast. */
|
||||
const char *interface_addr; /**< Local IPv4 of the interface to join on. NULL = default route. */
|
||||
uint16_t data_port; /**< Multicast data port; 0 means server_port + 1. */
|
||||
double silence_timeout_s; /**< Reconnect after this long without data. 0 disables. */
|
||||
double reconnect_delay_s; /**< Wait between reconnect attempts. */
|
||||
double keepalive_interval_s;/**< Unicast ACK period. 0 disables. */
|
||||
uint32_t recv_buffer_bytes; /**< SO_RCVBUF; large bursts need a large value. */
|
||||
uint32_t max_packet_bytes; /**< Ceiling on one reassembled payload. */
|
||||
} udps_client_config_t;
|
||||
|
||||
/** Fills @p cfg with the defaults documented in Docs/UDPS-C-Client.md. */
|
||||
void udps_client_config_init(udps_client_config_t *cfg);
|
||||
|
||||
/**
|
||||
* @brief Creates a client. No socket is opened until the first poll.
|
||||
* @return NULL if @p cfg is invalid or memory ran out.
|
||||
*/
|
||||
udps_client_t *udps_client_create(const udps_client_config_t *cfg);
|
||||
|
||||
/** Closes the session (sending DISCONNECT if connected) and frees the client. */
|
||||
void udps_client_destroy(udps_client_t *client);
|
||||
|
||||
/** Installs the callbacks. Any of them may be NULL. */
|
||||
void udps_client_set_callbacks(udps_client_t *client,
|
||||
udps_config_cb on_config,
|
||||
udps_data_cb on_data,
|
||||
udps_event_cb on_event,
|
||||
void *user);
|
||||
|
||||
/**
|
||||
* @brief Drives the client: connects if needed, then waits for and processes
|
||||
* packets for at most @p timeout_ms milliseconds.
|
||||
*
|
||||
* Callbacks fire from inside this call. A negative @p timeout_ms blocks until
|
||||
* something happens. Call it in a loop; it is the only function that does work.
|
||||
*
|
||||
* @return the number of packets processed (0 on timeout), or -1 if the session
|
||||
* broke. -1 is not fatal: the next call retries after reconnect_delay_s.
|
||||
*/
|
||||
int udps_client_poll(udps_client_t *client, int timeout_ms);
|
||||
|
||||
/** Non-zero once the sockets are up (which does not yet imply CONFIG arrived). */
|
||||
int udps_client_is_connected(const udps_client_t *client);
|
||||
|
||||
/**
|
||||
* @brief The current signal set, or NULL before the first CONFIG.
|
||||
* @param num_signals Out; may be NULL.
|
||||
*/
|
||||
const udps_signal_t *udps_client_signals(const udps_client_t *client,
|
||||
uint32_t *num_signals);
|
||||
|
||||
/** The publishing mode from the last CONFIG (UDPS_PUBLISH_*). */
|
||||
uint8_t udps_client_publish_mode(const udps_client_t *client);
|
||||
|
||||
/** Copies the counters into @p out. */
|
||||
void udps_client_stats(const udps_client_t *client, udps_stats_t *out);
|
||||
|
||||
/** Human-readable description of the last failure. Never NULL. */
|
||||
const char *udps_client_last_error(const udps_client_t *client);
|
||||
|
||||
/*---------------------------------------------------------------------------*/
|
||||
/* Stateless helpers */
|
||||
/*---------------------------------------------------------------------------*/
|
||||
|
||||
/** Elements in one sample of @p signal (rows x cols, at least 1). */
|
||||
uint32_t udps_signal_num_elements(const udps_signal_t *signal);
|
||||
|
||||
/** Short name of a type code, e.g. "float32". Never NULL. */
|
||||
const char *udps_type_name(uint8_t type_code);
|
||||
|
||||
/**
|
||||
* @brief Decodes a packet header.
|
||||
* @return 0 on success, -1 if @p len is too small or the magic is wrong.
|
||||
*/
|
||||
int udps_parse_header(const void *buf, size_t len, udps_header_t *out);
|
||||
|
||||
/**
|
||||
* @brief Decodes a reassembled CONFIG payload.
|
||||
* @param signals Out array of at most @p max_signals entries.
|
||||
* @param num_signals Out; the number actually written.
|
||||
* @param publish_mode Out; may be NULL.
|
||||
* @return 0 on success, -1 if the payload is malformed or does not fit.
|
||||
*/
|
||||
int udps_parse_config(const void *payload,
|
||||
size_t len,
|
||||
udps_signal_t *signals,
|
||||
uint32_t max_signals,
|
||||
uint32_t *num_signals,
|
||||
uint8_t *publish_mode);
|
||||
|
||||
/**
|
||||
* @brief One value out of a frame.
|
||||
* @param sample Accumulate batch slot; ignored for non-scalar signals.
|
||||
* @param elem Element within the sample; ignored for accumulated scalars.
|
||||
* @return the value, or 0.0 if any index is out of range.
|
||||
*/
|
||||
double udps_frame_value(const udps_frame_t *frame,
|
||||
uint32_t signal_idx,
|
||||
uint32_t sample,
|
||||
uint32_t elem);
|
||||
|
||||
/**
|
||||
* @brief Arrival-anchored estimate of the wall-clock time of one element.
|
||||
*
|
||||
* Exact only for streams that declare a sampling rate: the packet is assumed to
|
||||
* have arrived as its last element was produced, and earlier elements are dated
|
||||
* backwards by 1/sampling_rate. Signals with UDPS_TIME_PACKET, or without a
|
||||
* sampling rate, all report the arrival time. When the stream carries a time
|
||||
* signal (time_signal_idx != UDPS_NO_TIME_SIGNAL) that signal is the accurate
|
||||
* source — read it like any other signal instead of using this helper.
|
||||
*/
|
||||
double udps_frame_element_time(const udps_frame_t *frame,
|
||||
uint32_t signal_idx,
|
||||
uint32_t elem);
|
||||
|
||||
#ifdef __cplusplus
|
||||
} /* extern "C" */
|
||||
#endif
|
||||
|
||||
#endif /* UDPS_CLIENT_H */
|
||||
Reference in New Issue
Block a user