Martino Ferrari
201 lines
7.7 KiB
Markdown
201 lines
7.7 KiB
Markdown
# UDPStreamer DataSource
|
||
|
||
`UDPStreamer` is a MARTe2 output DataSource that streams signals from a real-time application
|
||
to a single connected UDP client. It is fully asynchronous from the RT thread: the RT cycle
|
||
only performs a fast spinlock + memcpy, while all network I/O runs on a dedicated background
|
||
thread.
|
||
|
||
## Key Features
|
||
|
||
- **Zero-copy RT path** — `Synchronise()` only locks, copies signal memory, and posts a semaphore.
|
||
- **Single-client model** — one client at a time; a new CONNECT replaces the previous session.
|
||
- **Packet fragmentation** — large payloads are split into ≤ `MaxPayloadSize`-byte datagrams,
|
||
each with a header carrying fragment index and total count so the client can reassemble them.
|
||
- **Signal quantization** — `float32`/`float64` signals can be linearly quantized to
|
||
`uint8`, `int8`, `uint16`, or `int16` on the wire, reducing bandwidth significantly.
|
||
- **Temporal arrays** — signals with `NumberOfElements > 1` can carry per-sample time
|
||
metadata via `TimeMode` and `TimeSignal`, enabling high-frequency burst transmission
|
||
(e.g. 1 000 samples per RT cycle at 1 MSps).
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
```
|
||
+Streamer = {
|
||
Class = UDPStreamer
|
||
|
||
// Network
|
||
Port = 44500 // UDP port the server listens on (default: 44500)
|
||
MaxPayloadSize = 1400 // Maximum bytes per UDP datagram (default: 1400)
|
||
// Must be > 17 (header size). Tune for MTU.
|
||
|
||
// Background thread (optional)
|
||
CPUMask = 0x2 // CPU affinity mask for the network thread
|
||
StackSize = 1048576 // Stack size in bytes (default: 1 MiB)
|
||
|
||
Signals = {
|
||
// ── Scalar signal ────────────────────────────────────────────────────
|
||
Time = {
|
||
Type = uint32
|
||
Unit = "us" // Optional: physical unit string (informational)
|
||
}
|
||
|
||
// ── Float signal with quantization ───────────────────────────────────
|
||
Pressure = {
|
||
Type = float32
|
||
Unit = "Pa"
|
||
RangeMin = 0.0 // Required when QuantizedType is set
|
||
RangeMax = 1000000.0 // Required when QuantizedType is set
|
||
QuantizedType = uint16 // none | uint8 | int8 | uint16 | int16
|
||
}
|
||
|
||
// ── Temporal array (packed burst) ────────────────────────────────────
|
||
Channel1 = {
|
||
Type = float32
|
||
NumberOfDimensions = 1
|
||
NumberOfElements = 1000 // N samples per RT cycle
|
||
Unit = "V"
|
||
TimeMode = FirstSample // see Time Modes below
|
||
TimeSignal = Time // name of a scalar signal in this DataSource
|
||
SamplingRate = 1000000.0 // Hz — used by client to reconstruct timestamps
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Top-level Parameters
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `Port` | uint16 | 44500 | UDP server port |
|
||
| `MaxPayloadSize` | uint32 | 1400 | Max payload bytes per UDP datagram (min 18) |
|
||
| `CPUMask` | uint32 | 0 (any) | Background thread CPU affinity |
|
||
| `StackSize` | uint32 | 1 048 576 | Background thread stack size in bytes |
|
||
|
||
### Per-signal Parameters
|
||
|
||
| Parameter | Type | Default | Applies to |
|
||
|-----------|------|---------|------------|
|
||
| `Unit` | string | `""` | Any type — informational, forwarded to client in CONFIG |
|
||
| `RangeMin` | float64 | 0.0 | float32/float64 with `QuantizedType` |
|
||
| `RangeMax` | float64 | 1.0 | float32/float64 with `QuantizedType` |
|
||
| `QuantizedType` | string | `none` | float32/float64 only |
|
||
| `TimeMode` | string | `PacketTime` | Signals with `NumberOfElements > 1` |
|
||
| `TimeSignal` | string | — | Required when `TimeMode` ≠ `PacketTime` |
|
||
| `SamplingRate` | float64 | 0.0 | Required when `TimeMode` = `FirstSample` or `LastSample` |
|
||
|
||
### Quantization Types
|
||
|
||
| Value | Wire type | Bit depth | Notes |
|
||
|-------|-----------|-----------|-------|
|
||
| `none` | same as source | — | Raw copy, no quantization |
|
||
| `uint8` | uint8 | 8-bit | Maps `[RangeMin, RangeMax]` → `[0, 255]` |
|
||
| `int8` | int8 | 8-bit | Maps `[RangeMin, RangeMax]` → `[-127, 127]` |
|
||
| `uint16` | uint16 | 16-bit | Maps `[RangeMin, RangeMax]` → `[0, 65 535]` |
|
||
| `int16` | int16 | 16-bit | Maps `[RangeMin, RangeMax]` → `[-32 767, 32 767]` |
|
||
|
||
Quantization formula (unsigned, e.g. uint16):
|
||
|
||
```
|
||
normalized = clamp((value - RangeMin) / (RangeMax - RangeMin), 0.0, 1.0)
|
||
wire_value = (uint16)(normalized × 65535)
|
||
```
|
||
|
||
### Time Modes
|
||
|
||
| Value | Meaning | Requirements |
|
||
|-------|---------|--------------|
|
||
| `PacketTime` | The HRT counter captured at `Synchronise()` time is used as the packet timestamp. No per-signal time metadata. | — |
|
||
| `FullArray` | `TimeSignal` carries one timestamp per element (same `NumberOfElements`). | `TimeSignal` must have the same `NumberOfElements`. |
|
||
| `FirstSample` | `TimeSignal` is a scalar giving the timestamp of element `[0]`. Elements `[1..N-1]` are inferred at `1/SamplingRate` intervals. | Scalar `TimeSignal`; `SamplingRate > 0`. |
|
||
| `LastSample` | Same as `FirstSample` but `TimeSignal` is the timestamp of element `[N-1]`. | Scalar `TimeSignal`; `SamplingRate > 0`. |
|
||
|
||
---
|
||
|
||
## Broker
|
||
|
||
UDPStreamer uses `MemoryMapSynchronisedOutputBroker` for output signals. This broker is
|
||
called automatically by the MARTe2 scheduler after all GAMs in the thread have executed.
|
||
|
||
> **Note:** Input signals are not supported — `GetBrokerName()` returns `""` for
|
||
> `InputSignals`.
|
||
|
||
---
|
||
|
||
## Lifecycle
|
||
|
||
```
|
||
PrepareNextState() ← opens UDP server socket, starts background thread
|
||
↓
|
||
[RT thread, each cycle]
|
||
GAMs execute ← write into Streamer signal memory via broker
|
||
Synchronise() ← spinlock + memcpy to readyBuffer + post dataSem
|
||
↓
|
||
[Background thread]
|
||
Poll serverSocket ← receive CONNECT / DISCONNECT / ACK
|
||
Wait dataSem ← woken by Synchronise()
|
||
QuantizeAndSerialize() ← build wire payload
|
||
SendFragmented() ← send DATA fragments to client
|
||
```
|
||
|
||
---
|
||
|
||
## Performance Notes
|
||
|
||
- The RT path (`Synchronise()`) performs only: `FastLock()` + `memcpy` + `FastUnLock()` + `EventSem.Post()`.
|
||
No socket calls, no heap allocation.
|
||
- `readyBuffer` and `wireBuffer` are allocated once in `AllocateMemory()`.
|
||
- If no client is connected the background thread skips serialisation entirely.
|
||
- Packet loss is tolerated silently. ACK tracking is reserved for future use.
|
||
|
||
---
|
||
|
||
## Example: minimal scalar streaming
|
||
|
||
```
|
||
+Data = {
|
||
Class = ReferenceContainer
|
||
|
||
+Streamer = {
|
||
Class = UDPStreamer
|
||
Port = 44500
|
||
Signals = {
|
||
Counter = { Type = uint32 }
|
||
Voltage = { Type = float32; Unit = "V"; RangeMin = -10.0; RangeMax = 10.0; QuantizedType = uint16 }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Example: high-frequency burst
|
||
|
||
```
|
||
+Streamer = {
|
||
Class = UDPStreamer
|
||
Port = 44500
|
||
MaxPayloadSize = 1400
|
||
|
||
Signals = {
|
||
T0 = { Type = uint32; Unit = "us" }
|
||
|
||
Ch1 = {
|
||
Type = float32
|
||
NumberOfDimensions = 1
|
||
NumberOfElements = 1000 // 1000 samples per RT cycle
|
||
Unit = "V"
|
||
TimeMode = FirstSample
|
||
TimeSignal = T0
|
||
SamplingRate = 1000000.0 // 1 MSps
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
With `MaxPayloadSize = 1400`, a single 1000-element float32 signal produces:
|
||
|
||
```
|
||
payload = 8 B (HRT timestamp) + 4 B (T0/uint32) + 4000 B (float32×1000) = 4012 B
|
||
fragments = ceil(4012 / 1383) = 3
|
||
```
|