Martino Ferrari
403 lines
20 KiB
C++
403 lines
20 KiB
C++
/**
|
||
* @file UDPStreamer.h
|
||
* @brief Header file for class UDPStreamer
|
||
* @date 13/05/2026
|
||
* @author Martino Ferrari
|
||
*
|
||
* @copyright Copyright 2015 F4E | European Joint Undertaking for ITER and
|
||
* the Development of Fusion Energy ('Fusion for Energy').
|
||
* Licensed under the EUPL, Version 1.1 or - as soon they will be approved
|
||
* by the European Commission - subsequent versions of the EUPL (the "Licence")
|
||
* You may not use this work except in compliance with the Licence.
|
||
* You may obtain a copy of the Licence at: http://ec.europa.eu/idabc/eupl
|
||
*
|
||
* @warning Unless required by applicable law or agreed to in writing,
|
||
* software distributed under the Licence is distributed on an "AS IS"
|
||
* basis, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
|
||
* or implied. See the Licence permissions and limitations under the Licence.
|
||
*
|
||
* @details This header file contains the declaration of the class UDPStreamer
|
||
* with all of its public, protected and private members. It may also include
|
||
* definitions for inline methods which need to be visible to the compiler.
|
||
*/
|
||
|
||
#ifndef UDPSTREAMER_H_
|
||
#define UDPSTREAMER_H_
|
||
|
||
/*---------------------------------------------------------------------------*/
|
||
/* Standard header includes */
|
||
/*---------------------------------------------------------------------------*/
|
||
|
||
/*---------------------------------------------------------------------------*/
|
||
/* Project header includes */
|
||
/*---------------------------------------------------------------------------*/
|
||
#include "CompilerTypes.h"
|
||
#include "EmbeddedServiceMethodBinderI.h"
|
||
#include "EventSem.h"
|
||
#include "FastPollingMutexSem.h"
|
||
#include "MemoryDataSourceI.h"
|
||
#include "SingleThreadService.h"
|
||
#include "StreamString.h"
|
||
#include "UDPSServer.h"
|
||
|
||
/*---------------------------------------------------------------------------*/
|
||
/* Class declaration */
|
||
/*---------------------------------------------------------------------------*/
|
||
|
||
namespace MARTe {
|
||
|
||
/**
|
||
* @brief Publishing mode for the background sender thread.
|
||
*
|
||
* - Strict: send one packet every Synchronise() call (default).
|
||
* - Accumulate: buffer N successive snapshots and flush either when the next
|
||
* snapshot would exceed MaxPayloadSize or when 1/MinRefreshRate
|
||
* has elapsed. Scalars expand to arrays; the first scalar with
|
||
* Unit="us"/"ns" is auto-promoted as the FullArray time reference.
|
||
* - Decimate: send one packet every Ratio Synchronise() calls.
|
||
*/
|
||
typedef enum {
|
||
UDPStreamerPublishStrict = 0u, /**< Send on every RT cycle (default) */
|
||
UDPStreamerPublishAccumulate = 1u, /**< Accumulate until size/time limit; then flush */
|
||
UDPStreamerPublishDecimate = 2u /**< Send 1 packet every Ratio cycles */
|
||
} UDPStreamerPublishMode;
|
||
|
||
/**
|
||
* @brief Quantization types for float signals.
|
||
*/
|
||
typedef enum {
|
||
UDPStreamerQuantNone = 0u, /**< No quantization; raw wire format */
|
||
UDPStreamerQuantUint8 = 1u, /**< Quantize to uint8 [0, 255] */
|
||
UDPStreamerQuantInt8 = 2u, /**< Quantize to int8 [-127, 127] */
|
||
UDPStreamerQuantUint16 = 3u, /**< Quantize to uint16 [0, 65535] */
|
||
UDPStreamerQuantInt16 = 4u /**< Quantize to int16 [-32767, 32767] */
|
||
} UDPStreamerQuantType;
|
||
|
||
/**
|
||
* @brief Time reference modes for signals.
|
||
*/
|
||
typedef enum {
|
||
UDPStreamerTimePacket = 0u, /**< Use the packet-level timestamp (HRT at Synchronise time) */
|
||
UDPStreamerTimeFullArray = 1u, /**< Time signal has same NumberOfElements; one timestamp per element */
|
||
UDPStreamerTimeFirstSample = 2u, /**< Time signal is scalar = timestamp of first element */
|
||
UDPStreamerTimeLastSample = 3u /**< Time signal is scalar = timestamp of last element */
|
||
} UDPStreamerTimeMode;
|
||
|
||
/**
|
||
* @brief Per-signal metadata used at runtime for serialization.
|
||
*/
|
||
struct UDPStreamerSignalInfo {
|
||
StreamString name; /**< Signal name */
|
||
TypeDescriptor type; /**< MARTe2 type descriptor */
|
||
UDPStreamerQuantType quantType; /**< Quantization type (none = raw copy) */
|
||
uint8 numDimensions; /**< Number of dimensions (0=scalar, 1=array, 2=matrix) */
|
||
uint32 numElements; /**< Total number of elements (rows * cols) */
|
||
uint32 numRows; /**< Number of rows */
|
||
uint32 numCols; /**< Number of columns */
|
||
float64 rangeMin; /**< Min of physical range (for quantization) */
|
||
float64 rangeMax; /**< Max of physical range (for quantization) */
|
||
UDPStreamerTimeMode timeMode; /**< How time is encoded for this signal */
|
||
float64 samplingRate; /**< Hz, used for First/LastSample modes */
|
||
uint32 timeSignalIdx; /**< Index of the time-reference signal; 0xFFFFFFFFu = PacketTime */
|
||
StreamString unit; /**< Physical unit string */
|
||
uint32 srcByteSize; /**< Bytes in MARTe2 memory */
|
||
uint32 wireByteSize; /**< Bytes on the wire (may differ when quantized) */
|
||
uint32 bufferOffset; /**< Byte offset in the flat MemoryDataSourceI memory buffer */
|
||
bool accumulated; /**< True when this scalar was expanded to flushCount elements in Auto accumulation mode */
|
||
};
|
||
|
||
/**
|
||
* @brief A DataSource that streams MARTe2 signals to UDP clients.
|
||
*
|
||
* @details This output DataSource accepts signals from GAMs and forwards them
|
||
* asynchronously over the network. A dedicated background thread handles all
|
||
* network I/O so that the real-time thread is only blocked by a fast spinlock
|
||
* and a memcpy during Synchronise().
|
||
*
|
||
* Two operating modes are selected by the presence or absence of MulticastGroup:
|
||
*
|
||
* @par Unicast mode (default — no MulticastGroup)
|
||
* The server opens a single UDP socket on Port. The client initiates the session
|
||
* by sending a CONNECT packet to that port. The server replies with a CONFIG
|
||
* packet on the same socket and subsequently sends DATA packets directly to the
|
||
* client's address. Any number of clients may connect sequentially (one at a
|
||
* time); a new CONNECT evicts the previous client.
|
||
*
|
||
* @par Multicast mode (MulticastGroup specified)
|
||
* The server opens a TCP listener on Port for control traffic and a UDP socket
|
||
* aimed at MulticastGroup:DataPort for data traffic. The client:
|
||
* 1. Connects to Port via TCP and sends a CONNECT packet.
|
||
* 2. Receives the CONFIG packet over TCP.
|
||
* 3. Joins the multicast group (MulticastGroup:DataPort) to receive DATA packets.
|
||
* Multiple clients may receive data simultaneously by joining the same group.
|
||
* A new TCP CONNECT evicts the previous client from the control channel; the
|
||
* multicast data stream continues regardless.
|
||
*
|
||
* @par Packet protocol (both modes)
|
||
* - Client → Server: CONNECT (initiates session), DISCONNECT (terminates session),
|
||
* ACK (optional, for packet-loss monitoring).
|
||
* - Server → Client: CONFIG (signal metadata), DATA (signal values, possibly
|
||
* fragmented into multiple datagrams if payload exceeds MaxPayloadSize).
|
||
*
|
||
* @par Top-level configuration parameters
|
||
* | Parameter | Type | Default | Description |
|
||
* |-----------------|---------|---------|-------------|
|
||
* | Port | uint16 | 44500 | TCP control port (multicast) or UDP server port (unicast). Values ≤ 1024 produce a warning. |
|
||
* | MulticastGroup | string | *(absent)* | **Enables multicast mode.** IPv4 multicast address, e.g. `"239.0.0.1"`. Must be in 224.0.0.0/4. Absent or empty = unicast. |
|
||
* | DataPort | uint16 | Port+1 | UDP port for multicast DATA datagrams. Ignored in unicast mode. Must be non-zero and differ from Port. |
|
||
* | MaxPayloadSize | uint32 | 1400 | Maximum bytes of signal payload per UDP datagram (excluding the 17-byte header). Larger signals are fragmented. |
|
||
* | PublishingMode | string | Strict | `Strict`: send one packet every Synchronise() call. `Auto`: rate-limited; flush only when MinRefreshRate interval has elapsed. |
|
||
* | MinRefreshRate | float64 | — | Required when PublishingMode = Auto. Flush frequency in Hz (e.g. 120.0). |
|
||
* | MaxBatchSize | uint32 | 1 | Optional when PublishingMode = Auto. Number of RT cycles to accumulate before flushing one packet. Scalar signals are expanded to arrays of MaxBatchSize elements; the first scalar with Unit="us" or "ns" is auto-promoted as the per-sample FullArray timestamp reference for all other scalars. When omitted or 1, the most-recent single value is sent at MinRefreshRate. |
|
||
* | CPUMask | uint32 | 0xFFFFFFFF | CPU affinity bitmask for the background thread. |
|
||
* | StackSize | uint32 | (MARTe2 default) | Stack size in bytes for the background thread. |
|
||
*
|
||
* @par Per-signal configuration parameters
|
||
* | Parameter | Type | Default | Description |
|
||
* |------------------|---------|-------------|-------------|
|
||
* | Type | string | — | MARTe2 type name (uint8, int16, float32, float64, …). Mandatory. |
|
||
* | NumberOfDimensions | uint8 | 0 | 0 = scalar, 1 = array, 2 = matrix. |
|
||
* | NumberOfElements | uint32 | 1 | Total element count (rows × cols for matrices). |
|
||
* | Unit | string | "" | Physical unit label, e.g. `"Pa"` or `"m/s"`. Transmitted in CONFIG for display purposes. |
|
||
* | RangeMin | float64 | 0.0 | Minimum of the physical range. Required when QuantizedType is not `none`. |
|
||
* | RangeMax | float64 | 1.0 | Maximum of the physical range. Required when QuantizedType is not `none`. |
|
||
* | QuantizedType | string | none | Wire quantization for float signals: `none` \| `uint8` \| `int8` \| `uint16` \| `int16`. Reduces wire bandwidth at the cost of precision. Only valid for float32/float64 signals. |
|
||
* | TimeMode | string | PacketTime | How the signal's time axis is encoded (see below). |
|
||
* | TimeSignal | string | — | Name of the signal that carries timestamps. Required when TimeMode ≠ PacketTime. |
|
||
* | SamplingRate | float64 | — | Signal sampling rate in Hz. Required when TimeMode = FirstSample or LastSample. |
|
||
*
|
||
* @par TimeMode values
|
||
* | Value | Description |
|
||
* |--------------|-------------|
|
||
* | PacketTime | Uses the HRT counter captured at Synchronise() time as the single packet timestamp. No dedicated time signal needed. |
|
||
* | FullArray | TimeSignal has the same NumberOfElements as this signal; one timestamp per element. |
|
||
* | FirstSample | TimeSignal is a scalar = timestamp of the first element; subsequent elements are spaced by 1/SamplingRate. |
|
||
* | LastSample | TimeSignal is a scalar = timestamp of the last element; elements are spaced backwards by 1/SamplingRate. |
|
||
*
|
||
* @par Example — unicast mode
|
||
* <pre>
|
||
* +Streamer = {
|
||
* Class = UDPStreamer
|
||
* Port = 44500
|
||
* MaxPayloadSize = 1400
|
||
* PublishingMode = "Strict"
|
||
* Signals = {
|
||
* Time = {
|
||
* Type = uint64
|
||
* }
|
||
* Pressure = {
|
||
* Type = float32
|
||
* NumberOfDimensions = 1
|
||
* NumberOfElements = 100
|
||
* Unit = "Pa"
|
||
* RangeMin = 0.0
|
||
* RangeMax = 1000000.0
|
||
* QuantizedType = uint16
|
||
* TimeMode = LastSample
|
||
* TimeSignal = Time
|
||
* SamplingRate = 10000.0
|
||
* }
|
||
* Temperature = {
|
||
* Type = float64
|
||
* Unit = "degC"
|
||
* TimeMode = PacketTime
|
||
* }
|
||
* }
|
||
* }
|
||
* </pre>
|
||
*
|
||
* @par Example — multicast mode
|
||
* <pre>
|
||
* +Streamer = {
|
||
* Class = UDPStreamer
|
||
* Port = 44500 // TCP control port
|
||
* MulticastGroup = "239.0.0.1" // Enables multicast mode
|
||
* DataPort = 44501 // UDP data port (default: Port+1)
|
||
* MaxPayloadSize = 1400
|
||
* PublishingMode = "Auto"
|
||
* MinRefreshRate = 60
|
||
* Signals = {
|
||
* Time = {
|
||
* Type = uint64
|
||
* }
|
||
* Voltage = {
|
||
* Type = float32
|
||
* NumberOfDimensions = 1
|
||
* NumberOfElements = 1000
|
||
* Unit = "V"
|
||
* RangeMin = -10.0
|
||
* RangeMax = 10.0
|
||
* QuantizedType = int16
|
||
* TimeMode = FirstSample
|
||
* TimeSignal = Time
|
||
* SamplingRate = 100000.0
|
||
* }
|
||
* }
|
||
* }
|
||
* </pre>
|
||
*/
|
||
class UDPStreamer : public MemoryDataSourceI, public EmbeddedServiceMethodBinderI {
|
||
public:
|
||
CLASS_REGISTER_DECLARATION()
|
||
|
||
/**
|
||
* @brief Constructor. Initialises all members to safe defaults.
|
||
*/
|
||
UDPStreamer();
|
||
|
||
/**
|
||
* @brief Destructor. Stops the background thread and frees allocated memory.
|
||
*/
|
||
virtual ~UDPStreamer();
|
||
|
||
/**
|
||
* @brief Parses top-level configuration parameters.
|
||
* @details Reads Port, MaxPayloadSize, CPUMask, StackSize, PublishingMode,
|
||
* MinRefreshRate, MulticastGroup, and DataPort from the configuration node.
|
||
* Sets useMulticast and dataPort when MulticastGroup is present and valid.
|
||
* @return true if all mandatory parameters are valid and consistent.
|
||
*/
|
||
virtual bool Initialise(StructuredDataI &data);
|
||
|
||
/**
|
||
* @brief Validates signal types and builds the per-signal metadata array.
|
||
* @details Reads per-signal custom fields (Unit, RangeMin, RangeMax, QuantizedType,
|
||
* TimeMode, TimeSignal, SamplingRate) from signalsDatabase and populates signalInfos[].
|
||
* @return true if all signal configurations are valid.
|
||
*/
|
||
virtual bool SetConfiguredDatabase(StructuredDataI &data);
|
||
|
||
/**
|
||
* @brief Allocates signal memory (via parent) plus readyBuffer, scratchBuffer, wireBuffer.
|
||
* @return true if all memory allocations succeed.
|
||
*/
|
||
virtual bool AllocateMemory();
|
||
|
||
/**
|
||
* @brief Returns the broker name for the given signal direction.
|
||
* @return "MemoryMapSynchronisedOutputBroker" for OutputSignals; "" otherwise.
|
||
*/
|
||
virtual const char8 *GetBrokerName(StructuredDataI &data,
|
||
const SignalDirection direction);
|
||
|
||
/**
|
||
* @brief Called by the RT thread after all GAMs have written output signals.
|
||
* @details Copies signal memory to readyBuffer under a fast spinlock, then posts
|
||
* the dataSem to wake the background thread. Returns immediately.
|
||
* @return true always.
|
||
*/
|
||
virtual bool Synchronise();
|
||
|
||
/**
|
||
* @brief Opens the server socket and starts the background thread.
|
||
* @return true if the socket and thread start successfully.
|
||
*/
|
||
virtual bool PrepareNextState(const char8 *const currentStateName,
|
||
const char8 *const nextStateName);
|
||
|
||
/**
|
||
* @brief Background thread entry point.
|
||
* @details Handles client CONNECT/DISCONNECT/ACK and sends DATA packets.
|
||
*/
|
||
virtual ErrorManagement::ErrorType Execute(ExecutionInfo &info);
|
||
|
||
/**
|
||
* @brief Returns the listening port number.
|
||
*/
|
||
uint16 GetPort() const;
|
||
|
||
/**
|
||
* @brief Returns the maximum payload size per UDP datagram.
|
||
*/
|
||
uint32 GetMaxPayloadSize() const;
|
||
|
||
/**
|
||
* @brief Returns true if a client is currently connected.
|
||
*/
|
||
bool IsClientConnected() const;
|
||
|
||
/**
|
||
* @brief Returns true when multicast mode is active (MulticastGroup was set in config).
|
||
*/
|
||
bool IsMulticast() const;
|
||
|
||
private:
|
||
/**
|
||
* @brief Serializes the CONFIG payload into buf and sets payloadSize.
|
||
* @return true if serialization succeeds.
|
||
*/
|
||
bool BuildConfigPayload(uint8 *buf, uint32 bufSize, uint32 &payloadSize);
|
||
|
||
/**
|
||
* @brief Quantizes and serializes all signals from srcBuf into wireBuffer.
|
||
* @param[in] srcBuf Flat source buffer (signal data in MARTe2 format).
|
||
* @param[in] timestamp HRT counter to embed as packet timestamp.
|
||
*/
|
||
void QuantizeAndSerialize(const uint8 *srcBuf, uint64 timestamp);
|
||
|
||
/**
|
||
* @brief Serializes an accumulated batch into wireBuffer.
|
||
* @param src Flat buffer [numSamples × totalSrcBytes], slot 0 = oldest.
|
||
* @param timestamps HRT counters per slot; timestamps[0] is the packet timestamp.
|
||
* @param numSamples Actual number of filled slots to serialize.
|
||
*/
|
||
void SerializeAccumulated(const uint8 *src, const uint64 *timestamps, uint32 numSamples);
|
||
|
||
/**
|
||
* @brief Maps a MARTe2 TypeDescriptor to the UDPS_TYPECODE_* constants.
|
||
*/
|
||
static uint8 TypeDescriptorToCode(TypeDescriptor td);
|
||
|
||
/* Configuration parameters */
|
||
uint16 port; /**< UDP server port */
|
||
uint32 maxPayloadSize; /**< Max payload bytes per UDP packet (excluding header) */
|
||
uint32 cpuMask; /**< Background thread CPU affinity */
|
||
uint32 stackSize; /**< Background thread stack size */
|
||
UDPStreamerPublishMode publishMode; /**< Strict or Auto publishing mode */
|
||
float64 minRefreshRate; /**< Minimum flush rate (Hz) for Auto mode */
|
||
uint64 flushPeriodTicks; /**< HRT ticks per flush interval (computed from minRefreshRate) */
|
||
/* Accumulate mode — dynamic batch parameters */
|
||
uint32 maxBatchCount; /**< Max snapshots that fit in MaxPayloadSize (Accumulate) */
|
||
uint32 singleCycleWireBytes; /**< Wire bytes for all accumulated signals per snapshot */
|
||
uint32 fixedWireBytes; /**< Wire bytes for non-accumulated signals (arrays, once per packet) */
|
||
volatile uint64 lastPublishTs; /**< HRT counter of last successful flush (Accumulate mode) */
|
||
uint8 *accumBuffer; /**< Heap: [maxBatchCount × totalSrcBytes] linear fill */
|
||
uint64 *accumTimestamps; /**< Heap: [maxBatchCount] HRT counter per snapshot */
|
||
uint32 accumFill; /**< Slots filled in accumBuffer (0..maxBatchCount) */
|
||
uint64 *readyTimestamps; /**< Heap: [maxBatchCount] HRT for completed ready batch */
|
||
uint64 *scratchTimestamps; /**< Heap: [maxBatchCount] background-thread local copy */
|
||
uint32 readyFill; /**< Snapshot count in the ready batch */
|
||
/* Decimate mode */
|
||
uint32 decimateRatio; /**< Send 1 packet every decimateRatio Synchronise() calls */
|
||
uint32 decimateCounter; /**< Current decimate cycle counter */
|
||
|
||
/* Signal metadata */
|
||
uint32 numSigs; /**< Number of signals */
|
||
UDPStreamerSignalInfo *signalInfos; /**< Per-signal metadata array */
|
||
|
||
/* Double-buffering for RT safety */
|
||
uint8 *readyBuffer; /**< Protected copy of signal memory for background thread */
|
||
uint8 *scratchBuffer; /**< Local copy used during serialization (avoids holding lock) */
|
||
uint32 totalSrcBytes; /**< Total bytes of signal data (= stateMemorySize) */
|
||
FastPollingMutexSem bufMutex; /**< Protects readyBuffer against concurrent access */
|
||
EventSem dataSem; /**< Wakes background thread when new data is ready */
|
||
volatile uint64 syncTimestamp; /**< HRT counter captured in Synchronise() */
|
||
|
||
/* Wire serialization buffer */
|
||
uint8 *wireBuffer; /**< Pre-allocated buffer for the serialized DATA payload */
|
||
uint32 totalWireBytes; /**< Total bytes of all signals after quantization + 8-byte timestamp prefix */
|
||
|
||
/* Networking — handled by UDPSServer */
|
||
UDPSServer server; /**< Multi-client session manager (unicast and multicast) */
|
||
|
||
/* Thread management */
|
||
SingleThreadService executor; /**< Background thread service */
|
||
|
||
/* Packet sequencing */
|
||
uint32 packetCounter; /**< Incremented for each DATA update sent */
|
||
};
|
||
|
||
} /* namespace MARTe */
|
||
|
||
#endif /* UDPSTREAMER_H_ */
|