# Architecture

This document describes the internal architecture of the MARTe2 Integrated Components.

---

## 1. Repository Overview

### DebugService path (legacy introspection / breakpoints)

```
┌────────────────────────────────────────────────────────────────────┐
│                       MARTe2 Application                           │
│  ┌──────────┐   ┌───────────────────────┐   ┌──────────────────┐   │
│  │  GAM(s)  │   │  DebugBrokerWrapper   │   │  FastScheduler   │   │
│  │          │◄──│  (Registry-patched)   │   │  (unmodified)    │   │
│  └──────────┘   └──────────┬────────────┘   └──────────────────┘   │
│                            │ RT-path API                           │
└────────────────────────────┼───────────────────────────────────────┘
                             │
                    ┌────────▼────────┐
                    │  DebugServiceI  │  ← Abstract singleton interface
                    └────────┬────────┘
                    ┌────────▼────────┐
                    │  DebugService   │
                    │  TCP/UDP        │
                    └────────┬────────┘
             ┌───────────────┼──────────────┐
             │               │              │
        TCP 8080         UDP 8081      TCP 8082
        (commands)      (telemetry)    (TcpLogger)
             │               │
    ┌────────▼───────────────▼──────┐
    │     Client/debugger           │
    │     Go web client (browser)   │
    └───────────────────────────────┘
```

### UDPStreamer / StreamHub path (high-throughput signal streaming)

```
┌────────────────────────────────────────────────────────────────────┐
│                       MARTe2 Application                           │
│  ┌─────────────────────────────────────────────┐                   │
│  │  UDPStreamer DataSource                     │                   │
│  │  - Receives signals from GAMs via IOGAM     │                   │
│  │  - Serialises to UDPS binary protocol       │                   │
│  │  - Manages per-client sessions              │                   │
│  └──────────────────────┬──────────────────────┘                   │
└─────────────────────────┼──────────────────────────────────────────┘
                    UDP 44500 (unicast or multicast)
                          │
          ┌───────────────▼───────────────┐
          │       StreamHub               │
          │  Source/Applications/StreamHub│
          │  - N simultaneous sources     │
          │  - Ring buffers per signal    │
          │  - LTTB decimation            │
          │  - Trigger engine (FSM)       │
          │  - M WebSocket clients        │
          └──────────────┬────────────────┘
                   WebSocket 8090
                         │
          ┌──────────────┴──────────────┐
          │                             │
  ┌───────▼──────────┐     ┌────────────▼──────────────┐
  │ Browser (any)    │     │ ImGui Desktop Client       │
  │ Client/udpstreamer│    │ Client/streamhub/          │
  │ Go web server +  │     │ C++ native window          │
  │ JS oscilloscope  │     │ (SDL2 + OpenGL + ImPlot)   │
  └──────────────────┘     └───────────────────────────┘
```

---

## 2. UDPS Binary Protocol

Defined in `Common/UDP/UDPSProtocol.h` and shared between:

- `UDPStreamer` (C++ producer)
- `DebugService` (C++ producer for trace packets)
- `Common/Client/go/udpsprotocol` (Go decoder)
- `Source/Components/Interfaces/UDPStream/UDPSClient` (C++ consumer)

### Packet Header (17 bytes, little-endian, packed)

| Offset | Size | Type   | Field            | Description                                                    |
| ------ | ---- | ------ | ---------------- | -------------------------------------------------------------- |
| 0      | 4    | uint32 | `magic`          | Always `0x53504455` ('UDPS' LE)                                |
| 4      | 1    | uint8  | `type`           | Packet type (DATA=0, CONFIG=1, ACK=2, CONNECT=3, DISCONNECT=4) |
| 5      | 4    | uint32 | `counter`        | Per-update sequence number (same across all fragments)         |
| 9      | 2    | uint16 | `fragmentIdx`    | 0-based fragment index                                         |
| 11     | 2    | uint16 | `totalFragments` | Total fragments for this update                                |
| 13     | 4    | uint32 | `payloadBytes`   | Bytes of payload following this header                         |

### Signal Descriptor (136 bytes, packed)

| Field          | Type    | Description                                               |
| -------------- | ------- | --------------------------------------------------------- |
| `name`         | char[64]| Null-terminated signal name                               |
| `typeCode`     | uint8   | UDPS_TYPECODE_* (0=u8, 1=i8, … 9=f32, 10=f64)           |
| `quantType`    | uint8   | UDPS_QUANT_* (0=none, 1=u8, 2=i8, 3=u16, 4=i16)         |
| `numDimensions`| uint8   | 0=scalar, 1=array, 2=matrix                               |
| `numRows`      | uint32  | Element count for 1D; rows for 2D                         |
| `numCols`      | uint32  | 1 for scalar/1D; columns for 2D                           |
| `rangeMin`     | float64 | Physical range minimum (for dequantisation)               |
| `rangeMax`     | float64 | Physical range maximum (for dequantisation)               |
| `timeMode`     | uint8   | UDPS_TIMEMODE_* (0=packet, 1=first, 2=last, 3=full_array)|
| `samplingRate` | float64 | Hz; used for first/last sample interpolation              |
| `timeSignalIdx`| uint32  | Index of time-ref signal; 0xFFFFFFFF if none              |
| `unit`         | char[32]| Null-terminated physical unit string                      |

### CONFIG Payload

Sent when the signal set changes or a client connects:

```
[uint32 numSigs]
numSigs × UDPSSignalDescriptor (136 bytes each, packed)
[uint8 publishMode]     0=Strict, 1=Accumulate, 2=Decimate
[uint64 hrtFrequency]   producer's HRT ticks per second; 0 = unknown
```

Everything after the descriptors is an optional trailer: a receiver accepts a
payload that stops early and ignores bytes it does not know. `hrtFrequency` is
what lets a receiver on another host turn the raw counter in DATA into seconds
— without it the only option is the receiver's own timer, which agrees with the
producer only when the two share a machine.

### DATA Payload (Strict / Decimate modes)

```
[uint64 HRT timestamp]
per-signal data in CONFIG order (quantised or raw, no inter-signal padding)
```

### DATA Payload (Accumulate mode)

```
[uint64 HRT timestamp of the first slot in the batch]
[uint32 numSamples]     RT cycles accumulated into this packet
for each signal, in CONFIG order: numSamples × NumElements values
```

### Quantization / Dequantization

When `quantType != QUANT_NONE`, the server maps `[rangeMin, rangeMax]` to the full
integer range. Clients reverse with:

| quantType | Formula |
|-----------|---------|
| QUANT_UINT8  | `rangeMin + (q / 255.0) × (rangeMax − rangeMin)` |
| QUANT_INT8   | `rangeMin + ((q + 127.0) / 254.0) × (rangeMax − rangeMin)` |
| QUANT_UINT16 | `rangeMin + (q / 65535.0) × (rangeMax − rangeMin)` |
| QUANT_INT16  | `rangeMin + ((q + 32767.0) / 65534.0) × (rangeMax − rangeMin)` |

---

## 3. DebugService Architecture

### 3.1 Registry Patching (Zero-Code-Change Instrumentation)

`DebugService::PatchRegistry()` replaces the `ObjectBuilder` for all `MemoryMap*Broker`
types in the MARTe2 `ClassRegistryDatabase`. Any subsequent `ConfigureApplication()` call
will instantiate `DebugBrokerWrapper<T>` objects instead of the originals. No application
source changes are needed.

Wrapped types: `MemoryMapInputBroker`, `MemoryMapOutputBroker`,
`MemoryMapSynchronisedInputBroker`, `MemoryMapSynchronisedOutputBroker`,
`MemoryMapMultiBufferBroker`, `MemoryMapMultiBufferOutputBroker`,
`MemoryMapAsynchronousInputBroker`, `MemoryMapAsynchronousOutputBroker`,
`MemoryMapInterpolatedInputBroker`, `MemoryMapStatefulOutputBroker`,
`MemoryMapStatefulInputBroker`.

### 3.2 Signal Registration

```
ConfigureApplication()
  └─► DebugBrokerWrapper::Init()
        └─► DebugBrokerHelper::InitSignals()
              ├─► DebugServiceI::RegisterSignal()   (canonical + GAM alias)
              └─► DebugServiceI::RegisterBroker()
```

Each signal is registered twice:

1. **Canonical**: `<DataSourcePath>.<SignalName>` (e.g. `App.Data.DDB.Counter`)
2. **GAM alias**: `<GAMPath>.In.<SignalName>` or `<GAMPath>.Out.<SignalName>`

Both map to the same `DebugSignalInfo*`. `AliasMatch()` in `DebugServiceBase.cpp`
performs bidirectional suffix matching so short unqualified names work in commands.

### 3.3 RT Hot Path

```
RealTimeThread::Execute()
  └─► DebugBrokerWrapper::Execute()
        ├─► Base::Execute()                  (actual data movement)
        └─► DebugBrokerHelper::Process()
              ├─► For each active signal:
              │     └─► DebugServiceI::ProcessSignal()
              │           ├─► if isForcing: memcpy forcedValue → signal memory
              │           ├─► if isTracing & decimation fires: push to TraceRingBuffer
              │           └─► if breakOp set: evaluate condition → SetPaused(true)
              └─► (output brokers only) ConsumeStepIfNeeded()
```

### 3.4 TraceRingBuffer

Single-producer/single-consumer circular byte buffer (4 MB default).
Entry format: `[ID:4][Timestamp:8][Size:4][Data:N]`.

- `Push()` serialised by `tracePushMutex` (multiple RT threads may write)
- `Pop()` called exclusively by the Streamer thread
- Corrupt entries detected by `size >= bufferSize`; discarded gracefully

### 3.5 DebugService Threads

| Thread       | Role                                                                             |
| ------------ | -------------------------------------------------------------------------------- |
| `Server()`   | Accepts one TCP client; reads text commands; writes JSON/text responses          |
| `Streamer()` | Drains `TraceRingBuffer`; assembles/sends UDP datagrams; polls monitored signals |

### 3.6 DebugServiceI Abstraction

`DebugServiceI.h` defines a pure-virtual singleton so transport implementations
(`DebugService` TCP/UDP, `WebDebugService` HTTP/SSE) share the same broker injection layer.

```cpp
DebugServiceI::SetInstance(this);           // concrete implementation registers itself
DebugServiceI *svc = DebugServiceI::GetInstance(); // broker wrapper retrieves it
```

---

## 4. UDPStreamer DataSource

`UDPStreamer` is a standard MARTe2 `DataSourceI` that:

1. Maintains a list of registered client sessions (UDP source address + port)
2. On each `Synchronise()` call (once per RT cycle):
   - Serialises all configured signals into one or more UDPS DATA packets
   - Sends to all connected clients
3. Handles `CONNECT` / `DISCONNECT` / `ACK` packets from clients
4. Sends `CONFIG` packets when the signal list changes or a new client connects
5. Applies quantization (`QuantizedType`, `RangeMin`, `RangeMax`) per signal
6. Supports unicast and multicast UDP delivery (configurable per instance)

### TCP variant

`TCPStreamer` / `TCPStreamerClient` subclass the UDP DataSources and replace the transport
(`TCPSServer` / `TCPSClient`) behind the `UDPSServerI` / `UDPSClientI` seam
(`UDPSTransportI.h`). Framing is unchanged (`totalFragments` is always 1); each client has
a bounded queue, so a slow client drops only its own frames.

`TCPStreamService` (`Source/Components/Interfaces/TCPStreamService/`) is an optional
in-process server: one acceptor plus `Workers` I/O threads serve many `TCPSServiceStream`s
(one per `TCPStreamer` with `Service=`/`StreamName=`). Producers only copy frames into
per-connection queues and wake the worker via a self-pipe. Lock order: topology, stream,
connection. A client picks streams with a `SUBSCRIBE` frame (type 5):

- **Multiplexing**: the payload may be a comma separated list; each server frame carries the
  stream's list index in `fragmentIdx`; queues are accounted per stream. `TCPSClient`
  demultiplexes into per-stream listeners (`GetStream(i)` facades), and StreamHub creates
  one session per stream over one shared client.
- **Joining**: `TCPStreamJoin` taps several streams (`TCPSStreamTapI`), watches the service
  for (un)registration (`TCPSStreamObserverI`) and publishes a merged Strict stream: CONFIG =
  concatenated descriptors named `<stream>_<signal>`; one DATA frame per master frame with
  the other sources held at their last value. No extra thread. Accumulate sources and
  differing HRT frequencies are refused. Lock order: source tap, join, output stream,
  connection queue.

See `Docs/TCPStreamer.md`.

### Packed Signals (Accumulate mode)

When a signal has `NumberOfElements > 1` and `SamplingRate` is configured:

- `TimeMode = FirstSample`: the `TimeSignal` value anchors the burst timestamp
- Clients interpolate per-sample timestamps as `t0 + e/SamplingRate`
- `UDPStreamer` packs all elements contiguously with no per-element header

---

## 5. StreamHub C++ Application

`StreamHub` (`Source/Applications/StreamHub/`) is a **headless standalone process** that
bridges N MARTe2 UDPStreamer sources to M simultaneous WebSocket clients. It replaces the
Go-based `Client/udpstreamer/` hub for deployments where a Go toolchain is unavailable
or where the hub must run as a C++ service.

### Components

| File | Purpose |
|------|---------|
| `main.cpp` | Entry point; parses `-cfg`, `-port`, `-maxPoints` flags |
| `StreamHub.h/.cpp` | Top-level orchestrator; push loop; WS command dispatch |
| `UDPSourceSession.h/.cpp` | One UDPS source: `UDPSClient` + ring buffers + wall-clock calibration + stats |
| `TriggerEngine.h/.cpp` | FSM: IDLE / ARMED / COLLECTING / TRIGGERED (web-client semantics) |
| `WSServer.h/.cpp` | RFC 6455 WebSocket server; multi-client accept+read threads |
| `WSFrame.h` | WebSocket frame encode/decode helpers |
| `SignalRingBuffer.h` | Thread-safe fixed-capacity circular buffer (float64 t, v) |
| `UDPSourceStats.h` | Per-source statistics struct |
| `LTTB.h` | Largest Triangle Three Buckets decimation (header-only) |
| `SHA1.h` | Inline SHA-1 for WebSocket handshake Accept key |
| `Base64.h` | Inline Base64 encoder for WebSocket handshake |

### Time Base (wall-clock calibration)

All ring-buffer timestamps are **Unix wall-clock seconds** (float64). Each
`UDPSourceSession` calibrates source time to the hub's `CLOCK_REALTIME` on the
first packet (offset = wallNow − sourceTime) and re-anchors automatically if the
computed time drifts more than 2 s from arrival time (source restart). Per-sample
time depends on the signal's UDPS `timeMode`:

| timeMode | Per-sample timestamp |
|----------|---------------------|
| `FirstSample` / `LastSample` | calibrated time-signal anchor ± k/samplingRate |
| `FullArray` | calibrated per-element time-signal array |
| Packet (scalar) | packet arrival wall time |
| Packet (array, n>1) | elements span `(lastPktWall, wallNow]`, interpolated from the inter-packet gap |

### Push Loop

Runs at `PushRate` Hz (default 30 Hz):

1. For each configured source:
   - On first CONFIG: broadcast `sources` + `config`, reset push cursors
   - For each signal: read **only the samples written since the last tick**
     (per-signal monotonic cursor into the ring; overrun clamps to oldest)
   - LTTB-decimate temporal signals to `MaxPushPoints` (default 50); scalars
     and packet-timed arrays go verbatim
   - Serialise one binary v1 frame per source; broadcast to all WS clients
   - Cursors advance even with zero clients (no backlog burst on connect)
2. Trigger servicing (capture finalisation, auto-rearm, state events)
3. Every `PushRate / StatsRate` ticks: broadcast JSON stats frame

Pushing only-new samples is essential: re-reading overlapping windows and
re-LTTBing them picks different points per window and corrupts the traces.

### Trigger Engine

Hub-side trigger with the web client's semantics (config: signal key
`"src:sig"` or `"src:sig[i]"`, edge rising/falling/both, threshold, window
0.1 ms–10 s, pre-trigger percent, mode normal/single):

```
IDLE       →[arm]→                ARMED
ARMED      →[edge crossing]→      COLLECTING   (latches trigTime, pre/postSec)
COLLECTING →[every source produced past the window]→ TRIGGERED  (broadcast binary v2 capture)
TRIGGERED  →[auto-rearm (normal, ~200 ms) | rearm (single)]→ ARMED
any        →[disarm]→             IDLE
```

`CheckSample()` is called from the UDPSClient receive thread for every decoded
sample of the configured signal. The capture is assembled in the push loop from
`ReadSignalRange(trigTime−preSec, trigTime+postSec)` over **all** signals,
LTTB-capped at 20 000 points/signal, and broadcast as a binary version-2 frame.
A `stopped` flag (`trigStop`) freezes auto-rearm.

COLLECTING is left on the **data's** clock, not `clock_gettime()`: `trigTime`
comes from sample timestamps, and a source that free-runs on its own clock sits
seconds away from wall time, so a wall-clock deadline chops exactly that offset
off every capture's tail. `UDPSourceSession::ProducerNewestTime()` reports how
far a source has produced — counting only signals actually timestamped from a
time signal, since PACKET-timed ones (the time array itself included) are
stamped on arrival and would just report "now".

Sources are harvested **one at a time**, each as soon as *it* passes
`trigTime + postSec + 0.15 s` (`BeginTriggerCapture` / `HarvestTriggerCapture` /
`FinishTriggerCapture`, the frame accumulating across push ticks). Making every
source wait for the slowest lets the leaders' rings roll past the pre-trigger
region before it is ever read. A 2 s wall-clock watchdog per capture bounds the
wait for a source that stopped advancing; it is harvested short, with a warning
naming the source and how far it got.

Because `RingTemporal` only holds ~1 s at 1 MSps, `setTrigger` publishes the
requested window and the push loop calls `GrowRingsForTrigger()`: each ring
measures its own rate (`Count() / TimeSpan()` — UDPS sources usually report
`samplingRate = 0`) and is grown in place to `rate × (window + 0.5 s) × 1.2`,
clamped per signal to `RingMaxMB`. `SignalRingBuffer::Grow()` preserves
contents *and* `totalWritten`, so live push cursors stay valid. Without this a
long window only ever captures its tail.

### Configuration File (MARTe2 cfg format)

```
Hub = {
    WSPort        = 8090
    MaxPoints     = 20000      // zoom/live window cap (setMaxPoints)
    PushRate      = 30         // push loop Hz
    MaxPushPoints = 50         // LTTB cap per signal per tick
    StatsRate     = 1          // stats broadcast Hz
    RingTemporal  = 1000000    // initial ring capacity (points) for multi-element signals
    RingScalar    = 100000     // ring capacity (points) for scalar signals
    RingMaxMB     = 128        // per-signal ceiling when a trigger window grows a ring
    SourcesFile   = "streamhub_sources.json"  // dynamic-source persistence
    AllowedOrigins = "http://127.0.0.1:8099,http://localhost:8099"  // see below
    Sources = {
        App1 = {
            Label = "MARTe2 App 1"
            Addr  = "127.0.0.1"
            Port  = 44500
        }
        App2 = {
            Label          = "MARTe2 App 2"
            Addr           = "192.168.1.10"
            Port           = 44501
            MulticastGroup = "239.0.0.1"
            DataPort       = 44504
        }
    }
}
```

A TCP source sets `Transport = "tcp"` and, for a `TCPStreamService`, `StreamName = "<stream>"`;
a comma list (`"a,b"`) takes several streams over one connection and creates one session per
stream (label `<Label>_<stream>`, id `<node>_<stream>`).

Sources added at runtime (`addSource`) get generated ids `s1, s2, …`;
`saveSources` persists them to `SourcesFile` (JSON array of
`{label, addr, multicastGroup?, dataPort?, transport?, streamName?}`), reloaded at start-up.

`AllowedOrigins` is a comma/space-separated allowlist of `scheme://host[:port]`
values accepted in the WebSocket `Origin` header (max 8 entries, 128 chars
each), matching the Go hub's option. Without it the handshake only accepts an
`Origin` whose host matches the request `Host` — so a browser that loaded the
SPA from a *different* port than the hub (the `run_streamhub.sh` layout, SPA on
8099 and hub on 8090) is rejected with 403. Non-browser clients send no `Origin`
and are unaffected. This is the CSWSH guard of RFC 6455 §10.2: browsers attach
cookies to cross-origin WebSocket handshakes, so `Origin` is the only thing
distinguishing a legitimate page from an attacker's.

### Build

```bash
MARTe2_DIR=/path/to/MARTe2 \
  make -C Source/Applications/StreamHub -f Makefile.gcc TARGET=x86-linux
# Produces: Build/x86-linux/StreamHub/StreamHub.ex
```

---

## 6. StreamHub WebSocket Protocol

All client↔hub communication uses WebSocket (RFC 6455). Text frames carry JSON;
binary frames carry data push payloads.

### Commands (client → hub, JSON text frames)

| `type` field     | Additional fields | Action |
|------------------|-------------------|--------|
| `ping`           | — | Hub replies `{"type":"pong"}` |
| `addSource`      | `label`, `addr` (`"host:port"`), `multicastGroup?`, `dataPort?` | Connect to a new UDPS source; hub assigns id `s1, s2, …` |
| `removeSource`   | `id` | Disconnect and remove a source |
| `saveSources`    | — | Persist the dynamic source list **and** the calibration table to `SourcesFile`; replies `configSaved` |
| `setCalibration` | `source` (label), `signal` (base name), `scale`, `offset`, `unit` | Record `value = raw × scale + offset` for one signal; metadata only, the hub never applies it. Identity entries are deleted. Replies with a `calibration` broadcast |
| `reloadConfig`   | — | Re-read `SourcesFile`: calibration replaced wholesale, missing sources added, live sources never touched; replies `configReloaded` |
| `getSources`     | — | Trigger `sources` broadcast |
| `getConfig`      | `sourceId` | Trigger `config` broadcast for one source |
| `getStats`       | — | Trigger `stats` broadcast |
| `setTrigger`     | `signal` (`"src:sig"` or `"src:sig[i]"`), `edge` (`"rising"`\|`"falling"`\|`"both"`), `threshold`, `windowSec`, `prePercent`, `mode` (`"normal"`\|`"single"`) | Configure the hub-side trigger |
| `arm`            | — | IDLE → ARMED |
| `disarm`         | — | Any state → IDLE |
| `rearm`          | — | TRIGGERED → ARMED (used in single mode) |
| `trigStop`       | `stopped?` (bool; absent = toggle) | Suppress auto-rearm in normal mode |
| `zoom`           | `reqId`, `t0`, `t1`, `n?`, `signals?` (comma-separated `"src:sig"` keys; absent = all) | Hi-res window read; reply is **unicast** to the requester. `n` absent → 2400; `n≤0` → no decimation |
| `setMaxPoints`   | `maxPoints` | Resize all ring buffers (applied in push loop; cursors reset) |

### Events (hub → client, JSON text frames)

| `type` field       | Fields | When sent |
|--------------------|--------|-----------|
| `sources`          | `sources:[{id, label, addr:"host:port", state}]` | On connect; after add/remove/getSources; on first CONFIG |
| `config`           | `sourceId`, `publishMode`, `signals:[{name, typeCode, quantType, numDimensions, numRows, numCols, rangeMin, rangeMax, timeMode, samplingRate, timeSignalIdx, unit}]` | After CONFIG received from source |
| `stats`            | `sources:{id:{state, totalReceived, totalLost, rateHz, rateStdHz, fragsPerCycle, bytesPerCycle, cycleAvgMs, cycleStdMs, cycleMinMs, cycleMaxMs, cycleHistMin, cycleHistMax, cycleHist:[20]}}` | At `StatsRate` Hz |
| `triggerState`     | `state` (`"idle"`\|`"armed"`\|`"collecting"`\|`"triggered"`), `mode`, `stopped`, `trigTime?`, `preSec?`, `postSec?` | On any trigger FSM transition |
| `zoom`             | `reqId`, `signals:{"src:sig":{t:[…], v:[…]}}` (`t` printed `%.17g`, `v` `%.9g`) | Unicast reply to `zoom` |
| `maxPointsUpdated` | `maxPoints` | After ring buffer resize |
| `calibration`      | `cal:[{source, signal, scale, offset, unit}]` | On connect; after an accepted `setCalibration`; after a successful `reloadConfig` |
| `configSaved`      | `ok`, `path`, `error?` | In reply to `saveSources` |
| `configReloaded`   | `ok`, `path`, `error?` | In reply to `reloadConfig` |
| `pong`             | — | In reply to `ping` |

### Config File Format

`SourcesFile` is a flat JSON array of flat objects; `addr` marks a source,
`signal` marks a calibration entry.

```json
[
  {"label": "wave", "addr": "127.0.0.1:44500"},
  {"source": "wave", "signal": "Adc", "scale": 0.00030518, "offset": -1.25, "unit": "V"}
]
```

Flatness is a hard constraint: `StreamHub::LoadSourcesFile` scans from each `{`
to the next `}`, so a nested object would truncate the parse. Both hubs read and
write this format identically, and pre-calibration files load unchanged.

Calibration is applied **client-side only**. Rings, history, `zoom` replies, both
binary frames and the trigger comparator are all in raw units.

### Binary Push Frame (version 1, hub → client, binary WS frame)

Little-endian throughout. Sent at `PushRate` Hz per source; contains **only
samples new since the previous push** (per-signal cursors), decimated to
`MaxPushPoints` per signal.

```
[1]  version = 1
[1]  sourceIdLen (L)
[L]  sourceId (UTF-8, no null terminator)
[4]  numSignals (uint32 LE)

Per signal:
  [2]  keyLen (uint16 LE) (K)
  [K]  key = signal name (UTF-8; "name[i]" per element for multi-element PACKET signals)
  [4]  pairCount (uint32 LE) (N)
  [N×8] time array (float64 LE, Unix wall-clock seconds)
  [N×8] value array (float64 LE, physical units)
```

### Binary Capture Frame (version 2, hub → client, binary WS frame)

Broadcast once per trigger capture (FSM COLLECTING → TRIGGERED). Each signal is
LTTB-decimated to at most 20 000 points.

```
[1]  version = 2
[8]  trigTime (float64 LE, Unix seconds)
[8]  preSec   (float64 LE)
[8]  postSec  (float64 LE)
[4]  numSignals (uint32 LE)

Per signal:
  [2]  keyLen (uint16 LE) (K)
  [K]  fullKey = "src:sig" (UTF-8)
  [4]  pairCount (uint32 LE) (N)
  [N×8] time array (float64 LE, Unix seconds)
  [N×8] value array (float64 LE)
```

---

## 7. ImGui Desktop Client

`Client/streamhub/` is a **native C++ desktop oscilloscope** that connects directly to
StreamHub via WebSocket and provides the same feature set as the browser client.

### Technology Stack

| Component | Library | Notes |
|-----------|---------|-------|
| UI framework | Dear ImGui (v1.91.x) | Fetched by CMake FetchContent |
| Time-series plots | ImPlot (v0.17.x) | Fetched by CMake FetchContent |
| Window + input | SDL2 | System package (`sdl2`) |
| GPU rendering | OpenGL 3.3 core | System package |
| WebSocket client | Custom (POSIX) | Reuses `WSFrame.h`, `SHA1.h`, `Base64.h` from StreamHub |

### Features

| Feature | Implementation |
|---------|---------------|
| Source sidebar | `ImGui::TreeNodeEx` per source; draggable signal leaves |
| Drag & drop signals | `ImGui::BeginDragDropSource` → `ImGui::BeginDragDropTarget` on plots |
| Multi-plot layout | 1×1, 1×2, 2×1, 1×3, 3×1, 2×2, 1×4, 4×1 grid; `ImGui::BeginTable` |
| Live data streaming | Binary v1 frame parser → per-signal ring buffer → ImPlot; live x-axis follows wall clock |
| LTTB decimation | Client-side, before plotting |
| Pause / resume | Per-plot toggle; frozen data still rendered |
| Zoom | ImPlot scroll+drag with history stack (Back / Fit / Reset-to-live); hub WS `zoom` for hi-res when zoomed in |
| Cursor A / B | ImPlot `DragLineX` annotations + ΔT and per-trace readouts |
| Trigger panel | Signal/edge/threshold/window/pre%/mode controls; Arm/Disarm/Rearm/Stop; badge (IDLE/ARMED/COLLECTING/TRIGGERED) |
| Trigger capture view | Binary v2 frames rendered relative to trigTime in `[-preSec, +postSec]`, marker at 0 |
| V-scale modes | normal / digital / mixed normalisation (parity with web client) |
| Stats panel | Per-source rate/cycle stats + 20-bin cycle-time histogram (`ImPlot::PlotBars`) |
| Add / remove source | Modal dialog; sends `addSource` / `removeSource` JSON |
| Signal styles | Per-signal color picker, line width, markers |
| Auto-reconnect | WSClient receive thread retries every 3 s |

### Build

```bash
# Install SDL2 (Arch Linux)
sudo pacman -S sdl2

cd Client/streamhub
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
# Produces: build/StreamHubClient

# Run (StreamHub must already be running on port 8090)
./build/StreamHubClient -host 127.0.0.1 -port 8090
```

---

## 7b. Qt Desktop Client

`Client/streamhub-qt/` is a **native Qt Widgets desktop oscilloscope** — a
feature/UX-equivalent alternative to the ImGui client, speaking the identical
StreamHub WebSocket protocol. It targets deployments that prefer a system Qt
runtime over bundled ImGui/SDL2/OpenGL, and it builds against either Qt6
(preferred) or Qt5 for old-Linux back-compatibility.

### Technology Stack

| Component | Library | Notes |
|-----------|---------|-------|
| UI framework | Qt Widgets | Autodetect Qt6 → Qt5 via `find_package(QT NAMES Qt6 Qt5 ...)`, then `Qt${QT_VERSION_MAJOR}::` targets |
| Time-series plots | Custom `QPainter` (`PlotWidget`) | No QtCharts/QCustomPlot — for ImPlot parity, zero extra deps, EUPL-clean |
| WebSocket client | `QtWebSockets` `QWebSocket` (`WsClient`) | Signals delivered on the GUI thread |
| Wire layer | Reused verbatim from `../streamhub/` | `Protocol.{h,cpp}`, `SignalBuffer.h` (framework-free C++17) |

### Threading & keyword model

- **Single GUI thread.** `QWebSocket` text/binary signals arrive on the GUI
  thread, so no locks are needed (unlike the ImGui client's background receive
  thread + drain). A 60 Hz `QTimer` (16 ms) drives repaint and panel refresh.
- **`QT_NO_KEYWORDS`.** The reused `Protocol.h`/`Model.h` structs have members
  named `signals` (e.g. `ZoomResponse::signals`), which collide with Qt's
  `signals`/`slots`/`emit` macros. The build defines `QT_NO_KEYWORDS`; all Qt
  classes here use `Q_SIGNALS:` / `Q_SLOTS:` / `Q_EMIT` instead. This keeps the
  shared wire layer unmodified.

### Components

| File | Responsibility |
|------|----------------|
| `Hub.{h,cpp}` | Domain model + command builders; owns `WsClient`; re-emits parsed events as Qt signals |
| `WsClient.{h,cpp}` | `QWebSocket` wrapper; auto-reconnect (3 s timer) |
| `PlotWidget.{h,cpp}` | One QPainter plot; live/stored/trigger modes, cursors, zoom cache |
| `PlotGrid.{h,cpp}` | Persistent pool of 8 `PlotWidget`s mounted into nested `QSplitter`s per layout |
| `SourceSidebar.{h,cpp}` | `QTreeWidget` of sources/signals; drag source = mime `application/x-shq-signal` carrying `qint32[2]` {srcIdx, sigIdx} (LittleEndian) |
| `TriggerBar.{h,cpp}` | Trigger config/arm controls + state badge |
| `StatsDialog.{h,cpp}` | Per-source stats table + 20-bin QPainter histogram |
| `HistoryBar.{h,cpp}` | Live / pan / jump-ago / show-all history navigation |
| `MainWindow.{h,cpp}` | Toolbars, docks, layout menu, connection controls, 60 Hz tick |

### Build & run

```bash
cd Client/streamhub-qt
cmake -B build              # autodetects Qt6, falls back to Qt5
cmake --build build -j$(nproc)
# Produces: build/StreamHubQtClient

# Run (StreamHub must already be running on port 8090)
./build/StreamHubQtClient --host 127.0.0.1 --port 8090
```

> Use long `--host`/`--port` (or short `-H`/`-p`). A single-dash `-host` is
> misparsed by `QCommandLineParser` as clustered short flags.

Verified: builds and links cleanly against both Qt6 (6.11) and Qt5 (5.15); the
Qt6 binary connects to a live StreamHub (server logs *"WebSocket client
connected"*) and runs without error.

---

## 8. Go Client Packages

### `Common/Client/go/udpsprotocol`

Pure Go decoder for UDPS packets:

- `Decoder` — reassembles fragments; returns complete CONFIG or DATA payloads
- `SignalDescriptor` — mirrors `UDPSSignalDescriptor` from C++
- `DataPacket` — decoded signal values with per-sample timestamps

### `Common/Client/go/wshub`

WebSocket broadcast hub:

- Multiple browser clients share one UDP → WebSocket relay
- JSON-encodes signal samples and broadcasts to all connected browsers

### `Client/debugger`

Go HTTP server providing the debug web UI:

- `main.go` — CLI entry point; starts TCP relay and HTTP server
- `martecontrol.go` — TCP client to `DebugService`; routes commands from browser
- `static/` — Single-page application (HTML/JS/CSS) with Chart.js plots

### `Client/udpstreamer`

Go HTTP server providing the UDP streamer oscilloscope web UI:

- `main.go` — CLI entry point; connects to one or more UDPStreamer ports
- `static/` — Full-featured SPA (uPlot plots, LTTB decimation, trigger UI, zoom)
- Compatible with StreamHub's WebSocket protocol (identical binary frame format)

---

## 9. Key Design Decisions

| Decision | Rationale |
|----------|-----------|
| Shared `UDPSProtocol.h` in `Common/UDP/` | Eliminates duplication between `UDPStreamer`, `UDPSClient`, and any future UDPS producer; Go packages decode the same binary layout |
| `DebugServiceI` abstract interface | Allows `DebugService` (TCP/UDP) and `WebDebugService` (HTTP/SSE) to share broker injection without coupling |
| No STL in C++ MARTe2 components | MARTe2 coding convention; `FastPollingMutexSem` and fixed arrays used throughout |
| STL allowed in ImGui client | `Client/streamhub/` is not a MARTe2 component; C++17 + STL reduce boilerplate without any architectural conflict |
| `FastPollingMutexSem` on hot path | Lowest-latency synchronisation primitive available in MARTe2; avoids OS scheduler involvement |
| Separate `TCPLogger` component | Decoupled from `DebugService`; can be used with any MARTe2 application independently |
| C++ StreamHub instead of Go hub | Single binary, no Go toolchain required on deployment host; reuses MARTe2 `UDPSClient` directly; embeds trigger engine |
| ImPlot for time-series in native client | Best-in-class ImGui plotting extension; handles millions of points with GPU acceleration; native zoom/pan without custom code |
| Reuse `WSFrame.h` / `SHA1.h` / `Base64.h` in ImGui client | Avoids duplicating the WebSocket framing implementation; CMake include path points directly at `Source/Applications/StreamHub/` |
| POSIX WebSocket client (no external library) | Keeps the client self-contained; RFC 6455 frame parsing is already implemented in `WSFrame.h`; only handshake SHA-1 and Base64 are needed |
| Go for browser-based clients | Minimal dependencies, single binary, easy cross-compilation; no Node/npm toolchain required for the web UI path |