Files

T

Martino Ferrari dd7dd22cb0 Implemented history writer

2026-06-14 14:09:51 +02:00

7.3 KiB

Raw Permalink Blame History

StreamHub — User Guide

StreamHub turns signals streamed by MARTe2 UDPStreamer DataSources into a multi-user oscilloscope. One hub process aggregates any number of sources and serves up to 16 simultaneous clients: a browser SPA and/or the native ImGui desktop client.

MARTe2 app (UDPStreamer) ──UDP 44500──▶ StreamHub ──WebSocket 8090──▶ browser / ImGui

1. Quick start (demo stack)

source env.sh
./run_streamhub.sh -w -g

This builds everything, starts a demo MARTe2 application with three streamers (scalars over multicast, two array streamers), a StreamHub on port 8090, the web UI server on port 8080 (-w) and the ImGui client (-g). Then open:

http://localhost:8080/?hub=localhost:8090

Useful flags: -p <port> WS port, -n <pts> ring size, -s skip rebuild, -h full help (including the list of ports used).

2. Running against your own application

Add a UDPStreamer DataSource to your MARTe2 configuration (see UDPStreamer.md).
Write a hub configuration, e.g. hub.cfg:
```
WSPort   = 8090
Sources = {
    MyApp = { Label = "MyApp" Addr = "192.168.0.10" Port = 44500 }
}
```
For multicast streamers add MulticastGroup = "239.0.0.1" and DataPort = 44503. All keys and defaults: StreamHub-Developer.md §6.

Run the hub and a client:

source env.sh
./Build/x86-linux/StreamHub/StreamHub.ex -cfg hub.cfg

# web UI
cd Client/webui && go build -o streamhub-webui . && ./streamhub-webui
# then browse http://localhost:8080/?hub=<hub-host>:8090

# or native client
./Client/streamhub/build/StreamHubClient -host <hub-host> -port 8090

Sources can also be added at runtime from either client ("Add source": label + host:port, optional multicast group/data port). "Save sources" persists the runtime list to streamhub_sources.json so the hub reloads it on restart.

3. Using the oscilloscope (web UI and ImGui)

Both clients offer the same workflow:

Plotting — drag signals from the source sidebar onto a plot. Choose a grid layout (1×1 … 4×1 / 2×2 / 1×4). Live plots scroll with wall-clock time; pick the time window (1/5/10/30/60 s).
Zoom — scroll/drag to zoom. When zoomed in, the client automatically fetches high-resolution data from the hub for the visible window. Back steps through the zoom history, Fit frames the data, Reset/Live returns to the scrolling live view.
Cursors — enable cursors A/B and drag them; the readout shows ΔT and the value of each trace at both cursors.
V-scale modes — normal, digital (booleans stacked as logic traces), mixed.
Signal styling — per-trace colour, line width, markers.
Stats — per source: packet rate ± std, lost packets, fragments and bytes per cycle, cycle-time min/avg/max/std and a 20-bin cycle-time histogram.

4. Trigger

The trigger runs in the hub, so a capture is identical in every connected client and uses full-rate ring data (not the decimated live stream).

Pick the trigger signal (for array signals: a specific element), the edge (rising/falling/both) and the threshold.
Pick the capture window (100 µs … 10 s) and the pre-trigger percentage (how much of the window precedes the trigger instant).
Mode normal re-arms automatically ~200 ms after each capture (Stop pauses re-arming); mode single captures once and waits for Rearm.
Press Arm. Badge states: IDLE → ARMED → COLLECTING → TRIGGERED.

On capture, the trigger view shows all plotted signals relative to the trigger instant (marker at t = 0) over [-pre, +post].

5. History (disk-backed storage)

StreamHub can store signal data to disk, allowing you to browse hours of past data even after the in-memory ring buffers have wrapped.

Enabling history

Add a +History block to the hub configuration:

Hub = {
    WSPort = 8090
    +History = {
        Directory      = "/data/streamhub_history"
        DurationHours  = 1
        Decimation     = 10
        FlushIntervalSec = 5
        MinDiskFreeMB  = 200
    }
    Sources = { … }
}

Key	Default	Description
`Directory`	(required)	Root directory for `.shist` files. Created automatically. Each source gets a subdirectory; each signal a separate file.
`DurationHours`	1	How many hours of data to keep per signal. The file size is fixed at creation: `duration × samplingRate / decimation × 16 bytes`.
`Decimation`	1	Write every N-th sample (1 = no decimation). Useful for high-rate signals where full-rate disk writes are impractical.
`FlushIntervalSec`	5	How often file headers are flushed to disk (data is written immediately via `pwrite`).
`MinDiskFreeMB`	500	Writing pauses when free disk space drops below this threshold and resumes when space is available again.

Disk usage

Each sample on disk is 16 bytes (8 bytes timestamp + 8 bytes value). Example:

10 signals at 1 ksps, decimation 10, duration 1 hour: 10 × (1000/10) × 3600 × 16 bytes = 57.6 MB
10 signals at 1 Msps, decimation 1000, duration 1 hour: 10 × (1e6/1000) × 3600 × 16 bytes = 576 MB

Files are pre-allocated at creation and never grow. The directory structure is:

/data/streamhub_history/
├── scalar/
│   ├── Sine1.shist
│   └── Sine2.shist
├── med/
│   ├── Ch1.shist
│   └── Ch2.shist
└── fast/
    ├── Ch3.shist
    └── Ch4.shist

Using history in clients

When history is enabled, both the web SPA and ImGui client show a HIST indicator. History data is fetched transparently:

Zoom: when you zoom or pan into a time range that extends beyond the in-memory ring buffer, the client issues a historyZoom request in parallel with the regular zoom request and merges the results — history data fills the older part of the window, ring data the recent part.
Status: the web SPA displays a history badge in the status bar showing the configured duration and decimation factor. The ImGui client shows "HIST" in the plot header when history data is being displayed.

History files survive hub restarts. If a .shist file exists with a matching capacity, the hub reopens it and continues writing where it left off.

6. Troubleshooting

Symptom	Check
Source stuck in connecting	Streamer host/port reachable? For multicast: group/data port match the streamer, and routing allows IGMP
No data but source streaming	`getStats` rate ≈ RT cycle rate? Firewall on UDP data port?
Web UI loads but no signals	Did you pass `?hub=host:8090` (the SPA talks WS directly to the hub, not the web server)?
Trigger never fires	Threshold inside the signal's actual range? Edge direction correct?
Time axis jumps once at start	Normal: first-packet wall-clock calibration; it also re-anchors after a source restart

Hub-side logs go to stdout; the demo scripts write /tmp/streamhub_e2e_{marte,hub}.log.

7. Further reading

StreamHub-API.md — WebSocket protocol (write your own client)
StreamHub-Developer.md — internals, build, tests
UDPStreamer.md — configuring the MARTe2 DataSource
Protocol.md — UDPS wire format

7.3 KiB Raw Permalink Blame History Unescape Escape