98 lines
7.7 KiB
Markdown
98 lines
7.7 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
MARTe2 component library providing real-time signal streaming (`UDPStreamer` DataSource → StreamHub → web/ImGui oscilloscopes) and zero-code-change debugging (`DebugService` Interface: trace/force/breakpoint via registry-patched broker wrappers). See `ARCHITECTURE.md` for full detail and `Docs/` for per-component references.
|
|
|
|
## Build & Test
|
|
|
|
Requires MARTe2 and MARTe2-components built externally; `env.sh` sets `MARTe2_DIR`, `MARTe2_Components_DIR`, `TARGET=x86-linux`, and `LD_LIBRARY_PATH` (needed both for building and for running anything).
|
|
|
|
```bash
|
|
source env.sh
|
|
|
|
make -f Makefile.gcc core # all C++ MARTe2 components
|
|
make -f Makefile.gcc apps # StreamHub standalone app
|
|
make -f Makefile.gcc test # build GTest + Integration tests
|
|
make -f Makefile.gcc clean
|
|
|
|
# Run tests (after source env.sh)
|
|
./Build/x86-linux/GTest/MainGTest.ex # unit tests (UDPStreamer)
|
|
./Build/x86-linux/GTest/MainGTest.ex --gtest_filter='Name*' # single test
|
|
./Build/x86-linux/Test/Integration/Integration/IntegrationTests.ex # DebugService integration tests
|
|
|
|
# Build a single component (each component dir has its own Makefile.gcc)
|
|
make -C Source/Components/DataSources/UDPStreamer -f Makefile.gcc
|
|
|
|
# Go clients
|
|
cd Common/Client/go && go build ./...
|
|
cd Client/debugger && go build ./...
|
|
|
|
# ImGui desktop client (not a MARTe2 component; needs SDL2)
|
|
cd Client/streamhub && cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build
|
|
|
|
# Qt desktop client (not a MARTe2 component; needs Qt5 or Qt6 Widgets + WebSockets)
|
|
cd Client/streamhub-qt && cmake -B build && cmake --build build
|
|
```
|
|
|
|
End-to-end demo script (build + launch full stack, see header for ports/options): `./run_streamhub.sh`.
|
|
|
|
**Streaming-chain E2E suite** (`Test/E2E/suite/`):
|
|
|
|
```bash
|
|
./Test/E2E/suite/run_e2e.sh [flags]
|
|
```
|
|
|
|
Flags:
|
|
|
|
| Flag | Effect |
|
|
|---|---|
|
|
| `--skip-build` | Skip C++ component rebuild |
|
|
| `--only <id>` | Run a single scenario by ID |
|
|
| `--pdf-only` | Just compile the Typst PDF report |
|
|
| `--cpp-coverage` | Instrumented gcov rebuild + lcov capture (on by default) |
|
|
| `--skip-coverage` | Disable the coverage pass |
|
|
| `--skip-stress` | Skip the stress matrix |
|
|
| `--skip-datasources` | Skip `direct` scenarios |
|
|
| `--skip-recorder` | Skip `recorder` scenarios |
|
|
| `--skip-debug` | Skip `debug` and `debug_pause_resume` scenarios |
|
|
| `--skip-tcplogger` | Skip `tcplogger` scenarios |
|
|
|
|
Scenario kinds (defined in `scenarios.py`):
|
|
|
|
- **chain** — full streaming pipeline: MARTe2 → UDPStreamer → StreamHub → Go `chain-client` (live/zoom/window/trigger). Validates recorded waveform against analytic/fed oracle (`validate_waveform.py`: fidelity gates correctness, sine shape-fit is a gross-sanity gate + tracked metric).
|
|
- **direct** — MARTe2 FileReader → FileWriter round-trip, validates binary output.
|
|
- **recorder** — MARTe2 → StreamHub with history recorder, validates recorded `.bin` file.
|
|
- **debug / debug_pause_resume** — DebugService scenarios via the Go `debugclient`.
|
|
- **tcplogger** — TcpLogger scenarios via the Go `debugclient`.
|
|
|
|
After scenarios, the suite runs unit tests + coverage (`collect.py`: C++ GTest, Go, Python; coverage uses lcov restricted to `Source/*` — the `Test/` harness is excluded), consolidates everything into `report_data.json` with per-field progression/regression vs the previous run and trend plots (`report_build.py`, history in `Build/x86-linux/E2E/chain/history.jsonl`), and compiles a Typst PDF (`E2E_Report.typ`). Artifacts go to `Build/x86-linux/E2E/chain/` (report, logs, PDF) and `/tmp/chain_e2e/` (scratch). Results are aggregated into `results.json` with XFAIL/XPASS handling for known issues.
|
|
|
|
Python framework unit tests: `python3 -m unittest tests_py` (in `Test/E2E/suite/`).
|
|
|
|
Build output goes to `Build/x86-linux/` (shared libs per component, `.ex` executables).
|
|
|
|
## Architecture
|
|
|
|
Two independent data paths:
|
|
|
|
1. **Streaming path**: `UDPStreamer` DataSource serialises signals each RT cycle to UDPS binary packets (UDP 44500, unicast/multicast) → `StreamHub` (`Source/Applications/StreamHub/`, headless C++ app: ring buffers, LTTB decimation, trigger FSM) → WebSocket 8090 → browser (`Client/udpstreamer`, Go), native ImGui client (`Client/streamhub`), or native Qt client (`Client/streamhub-qt`).
|
|
2. **Debug path**: `DebugService` patches the `ClassRegistryDatabase` at `Initialise()` so subsequent `ConfigureApplication()` instantiates `DebugBrokerWrapper<T>` around all `MemoryMap*Broker` types — no application changes. RT hot path goes through `DebugServiceI` (abstract singleton in `DebugServiceI.h`) for forcing/tracing/breakpoints. Exposes TCP 8080 (text commands), UDP 8081 (trace telemetry), works with `TcpLogger` on 8082. Web UI: `Client/debugger` (Go).
|
|
|
|
**Shared wire format**: `Common/UDP/UDPSProtocol.h` defines the UDPS binary protocol (17-byte packed header, 136-byte signal descriptors, little-endian). It is deliberately MARTe2-free so it's shared by C++ producers (`UDPStreamer`, `DebugService`), the C++ consumer (`Source/Components/Interfaces/UDPStream/UDPSClient`), and the Go decoder (`Common/Client/go/udpsprotocol`). Changes to the protocol must be mirrored across all of these, plus the JS client parsers.
|
|
|
|
**StreamHub WebSocket protocol**: JSON text frames for commands/events, binary frames for data pushes — spec in `ARCHITECTURE.md` §6. The Go hub (`Client/udpstreamer`) and C++ StreamHub implement the identical protocol; both clients (browser JS and ImGui) must stay compatible with both.
|
|
|
|
**StreamHub History**: `HistoryWriter` (`Source/Applications/StreamHub/HistoryWriter.{h,cpp}`) provides disk-backed circular storage of signal data. Each signal is stored in a separate `.shist` binary file with a 64-byte header and pre-allocated circular data region of `(float64 time, float64 value)` pairs. Configured via a `+History` block in the StreamHub config with keys: `Directory` (required), `DurationHours` (default 1), `Decimation` (default 1), `FlushIntervalSec` (default 5), `MinDiskFreeMB` (default 500). WS commands: `historyInfo` (returns metadata), `historyZoom` (reads time range from disk). Both the web SPA (`Client/udpstreamer/static/app.js`) and ImGui client support history zoom queries alongside in-memory ring zoom.
|
|
|
|
## Conventions
|
|
|
|
- **No STL in MARTe2 components** (`Source/Components/`): use MARTe2 types (`StreamString`, `FastPollingMutexSem`, fixed arrays). STL/C++17 is fine in `Client/streamhub/` and `Source/Applications/StreamHub/` follows MARTe2 style but links MARTe2 core.
|
|
- `FastPollingMutexSem` on RT hot paths (never OS mutexes).
|
|
- Each component dir has `Makefile.gcc` (wrapper), `Makefile.inc` (sources/includes), and `depends.x86-linux`/`dependsRaw.x86-linux` (generated dependency files).
|
|
- EUPL v1.1 license headers on C++ sources.
|
|
|
|
**Qt client** (`Client/streamhub-qt/`): native Widgets oscilloscope, feature/UX-equivalent to the ImGui client, speaking the identical StreamHub WebSocket protocol. CMake autodetects Qt6 (preferred) or Qt5 (`find_package(QT NAMES Qt6 Qt5 ...)` then `Qt${QT_VERSION_MAJOR}::` targets) for old-Linux back-compat. It reuses `../streamhub/Protocol.{h,cpp}` and `SignalBuffer.h` verbatim (framework-free C++17); those structs have members named `signals`, which collide with Qt's `signals`/`slots`/`emit` macros, so the build sets `QT_NO_KEYWORDS` and all Qt classes use `Q_SIGNALS:`/`Q_SLOTS:`/`Q_EMIT`. Single GUI thread (QWebSocket signals arrive on the GUI thread, no locks); a 60 Hz QTimer drives repaint. Plotting is custom QPainter (no QtCharts/QCustomPlot) for ImPlot parity and zero extra deps. Run: `./build/StreamHubQtClient --host HOST --port 8090` (long `--` options; single-dash `-host` is misparsed as clustered short flags).
|