MARTe-Integrated-Components/README.md

# MARTe2 Integrated Components

A unified MARTe2 library providing real-time signal streaming and on-the-fly debugging
for control applications built with [MARTe2](https://vcis.f4e.europa.eu/marte2-docs/).

---

## Overview

This repository integrates two complementary capabilities:

| Capability | Component | Purpose |
|---|---|---|
| **Signal streaming** | `UDPStreamer` DataSource | Continuously stream selected signals to a browser-based oscilloscope over UDP |
| **Signal debugging** | `DebugService` Interface | On-demand signal tracing, value forcing, and conditional breakpoints — zero application code changes required |
| **Sine generation** | `SineArrayGAM` | Generate continuous sine-wave arrays for testing and simulation |
| **Time stamping** | `TimeArrayGAM` | Provide time-reference arrays aligned to an RT cycle |
| **Log forwarding** | `TCPLogger` Interface | Forward `REPORT_ERROR` log events to TCP clients in real time |
| **Integrated client** | `Common/Client/go` | Go packages for UDPS protocol and WebSocket hub |
| **Debug web client** | `Client/debugger` | Browser-based debug UI communicating with `DebugService` |

---

## Repository Structure

```
MARTe_Integrated_components/
├── Common/
│   ├── UDP/                        UDPS binary protocol header (shared by all components)
│   └── Client/go/                  Go packages: udpsprotocol, wshub
├── Source/Components/
│   ├── DataSources/UDPStreamer/     Real-time UDP signal streaming DataSource
│   ├── GAMs/SineArrayGAM/          Sine-wave array generator GAM
│   ├── GAMs/TimeArrayGAM/          Time-reference array GAM
│   ├── Interfaces/DebugService/    Signal tracing/forcing/breakpoint Interface
│   └── Interfaces/TCPLogger/       TCP log-forwarding LoggerConsumerI
├── Test/
│   ├── GTest/                      GTest harness for UDPStreamer unit tests
│   ├── Integration/                Integration tests for DebugService
│   ├── Components/DataSources/UDPStreamer/  UDPStreamer unit tests
│   └── Configurations/             MARTe2 config files for tests and demos
├── Client/debugger/                Go web client for DebugService
└── Docs/                           Documentation
```

---

## Components

### UDPStreamer DataSource

Streams MARTe2 signals over UDP using the UDPS binary protocol.  Clients register by
sending a `CONNECT` packet; the server then sends `CONFIG` (signal metadata) and continuous
`DATA` packets.  Features:

- Optional 16-bit quantization (configurable per signal: `QuantizedType`)
- Packed high-frequency bursts (`NumberOfElements > 1` with `SamplingRate`)
- Automatic packet fragmentation for payloads exceeding `MaxPayloadSize`

See `Docs/UDPStreamer.md` and `Docs/Protocol.md`.

### SineArrayGAM

Generates a continuous float32 sine-wave array every RT cycle.  Used as a signal
source for testing and demo applications.  Configurable: `Frequency`, `Amplitude`,
`Phase`, `SamplingRate`, `NumberOfElements`.

See `Docs/SineArrayGAM.md`.

### TimeArrayGAM

Generates a time-reference float64 array. Each element holds the timestamp of the
corresponding sample in a packed burst, computed from the RT cycle timestamp and the
configured `SamplingRate`.

### DebugService Interface

Instruments a running MARTe2 application **without modifying its source code**.  On
`Initialise()` it patches the `ClassRegistryDatabase` to wrap all standard
`MemoryMap*Broker` types.  When `RealTimeApplication::ConfigureApplication()` runs
afterward the application transparently uses the wrapped brokers.

Capabilities accessible over TCP (port 8080 by default):
- `DISCOVER` — enumerate all signals with type and alias metadata
- `TRACE` — enable/disable high-speed UDP telemetry per signal (with decimation)
- `FORCE` / `UNFORCE` — inject persistent values into signals on the RT path
- `BREAK` — set conditional breakpoints (`>`, `<`, `==`, etc.)
- `PAUSE` / `RESUME` / `STEP` — execution stepping
- `TREE` / `INFO` / `LS` — live ORD navigation
- `VALUE` — read current signal value on demand
- `MSG` — send MARTe2 `Message` to any ORD object

High-speed signal telemetry is streamed as UDP binary datagrams (port 8081).
Logs are forwarded via `TcpLogger` (port 8082).

See `Docs/DebugService.md`.

### TCPLogger Interface

A `LoggerConsumerI` that forwards every MARTe2 `REPORT_ERROR` call to up to 8 TCP
clients on a configurable port.  Works as a sidecar to `DebugService`.

### StreamHub Application

Headless C++ hub (`Source/Applications/StreamHub/`) that aggregates multiple
UDPStreamer sources and serves them to oscilloscope clients over WebSocket
(port 8090): ring buffers with wall-clock time calibration, LTTB decimation,
hub-side trigger engine, per-window zoom. Clients: browser SPA
(`Client/webui` + `Client/udpstreamer/static`) and native ImGui desktop client
(`Client/streamhub`). Demo: `./run_streamhub.sh -w -g`; E2E test:
`Test/E2E/suite/run_e2e.sh`.

See `Docs/StreamHub-UserGuide.md`, `Docs/StreamHub-API.md` and
`Docs/StreamHub-Developer.md`.

### UDPS Protocol

The `Common/UDP/UDPSProtocol.h` header defines the shared binary wire format used by
both `UDPStreamer` and `DebugService`.  It is intentionally free of MARTe2-specific
dependencies so it can also be used by Go clients (via `Common/Client/go/udpsprotocol`).

See `Docs/Protocol.md`.

---

## Build

### Prerequisites

- MARTe2 built and installed (set `MARTe2_DIR`)
- MARTe2-components built and installed (set `MARTe2_Components_DIR`)
- GCC toolchain, make
- Go 1.21+ (for clients)

### Setup

```bash
# Edit env.sh to set MARTe2_DIR and MARTe2_Components_DIR, then:
source env.sh
```

### Build all C++ components

```bash
make -f Makefile.gcc core
```

### Build and run tests

```bash
make -f Makefile.gcc test
source env.sh
./Build/x86-linux/Test/Integration/IntegrationTests
```

### Build Go clients

```bash
# Integrated UDPS web client
cd Common/Client/go && go build ./...

# Debug web client
cd Client/debugger && go build ./...
```

### Clean

```bash
make -f Makefile.gcc clean
```

---

## Quick Start

### 1. Stream signals with UDPStreamer

Add to your MARTe2 config:

```text
+Streamer = {
    Class          = UDPStreamer
    Port           = 44500
    MaxPayloadSize = 1400
    Signals = {
        Voltage = { Type = float32; Unit = "V" }
    }
}
```

Launch the web client:

```bash
cd Common/Client/go
./udpstreamer-webui --streamer 127.0.0.1:44500 --listen :8080
```

Open `http://localhost:8080` and drag signals onto plots.

### 2. Debug a running application with DebugService

Add to your MARTe2 config (as a sibling of `+App`):

```text
+DebugService = {
    Class       = DebugService
    ControlPort = 8080
    UdpPort     = 8081
    LogPort     = 8082
}
+Logger = { Class = TcpLogger; Port = 8082 }
```

Launch the debug client:

```bash
cd Client/debugger
./debugger --listen :9090
```

Open `http://localhost:9090`, explore the object tree, trace signals, force values.

---

## Documentation

| Document | Contents |
|---|---|
| `Docs/Protocol.md` | UDPS binary wire protocol specification |
| `Docs/UDPStreamer.md` | UDPStreamer DataSource configuration reference |
| `Docs/SineArrayGAM.md` | SineArrayGAM configuration reference |
| `Docs/DebugService.md` | DebugService TCP API and architecture |
| `Docs/Tutorial.md` | Step-by-step tutorial covering both components |
| `Docs/WebUI.md` | Web client user guide |
| `Docs/StreamHub-UserGuide.md` | StreamHub oscilloscope user guide (web + ImGui clients) |
| `Docs/StreamHub-API.md` | StreamHub WebSocket protocol (commands, events, binary frames) |
| `Docs/StreamHub-Developer.md` | StreamHub internals, threading, time base, build & E2E tests |
| `ARCHITECTURE.md` | System architecture overview |

---

## License

Licensed under the EUPL v1.1 (see individual source files for copyright notices).