Martino Ferrari
229 lines
6.9 KiB
Markdown
229 lines
6.9 KiB
Markdown
# 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`.
|
|
|
|
### 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 |
|
|
| `ARCHITECTURE.md` | System architecture overview |
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Licensed under the EUPL v1.1 (see individual source files for copyright notices).
|