Martino Ferrari
135 lines
8.1 KiB
Markdown
135 lines
8.1 KiB
Markdown
# StreamHub Qt Client — Design Spec
|
||
|
||
**Date:** 2026-06-25
|
||
**Sub-project:** D (port `Client/streamhub/` ImGui/SDL2/ImPlot desktop client to Qt5/6)
|
||
**Status:** Approved-by-default (user away; standing instruction: "implement the specs, do not wait for my approval").
|
||
|
||
> Decisions below were made autonomously per the standing instruction. They are
|
||
> recorded with rationale so they can be revisited.
|
||
|
||
## Goal
|
||
|
||
Produce a native Qt desktop oscilloscope client (`Client/streamhub-qt/`) that is
|
||
feature- and UX-equivalent to the existing ImGui client, talking the identical
|
||
StreamHub WebSocket protocol (JSON commands/events + binary v1 push / v2 trigger
|
||
capture frames), and builds against **either Qt5 or Qt6** (autodetected), for
|
||
back-compatibility with older Linux distributions.
|
||
|
||
The existing ImGui client (`Client/streamhub/`) stays untouched as a reference.
|
||
|
||
## Framework decisions (with rationale)
|
||
|
||
1. **Qt Widgets, not QML/Qt Quick.**
|
||
The client is a dense desktop tool: multi-panel layouts, drag-and-drop of
|
||
signals, context menus, splitters, modal dialogs. Widgets is the natural fit,
|
||
renders without a GPU/OpenGL pipeline (important on old hardware), and has the
|
||
most stable API surface shared between Qt5 and Qt6.
|
||
|
||
2. **Custom `QPainter`-based `PlotWidget`, not QCustomPlot/QtCharts.**
|
||
The oscilloscope plotting is highly bespoke (fixed ±4-division Y space,
|
||
wall-clock live X, LTTB decimation, normal/digital/mixed band normalization,
|
||
per-trace V/div + screen position, A/B cursors, box/scroll zoom + pan, zoom
|
||
history, drag-drop, hi-res WS zoom overlay, trigger-capture view). Replicating
|
||
this on top of a general charting library fights the library as much as it
|
||
helps. A focused `QPainter` widget:
|
||
- gives exact behavioral parity with the ImPlot version;
|
||
- adds **zero external dependencies** (max portability on old Linux);
|
||
- avoids GPL/commercial licensing entanglement (repo is EUPL v1.1);
|
||
- is straightforward to test in isolation.
|
||
|
||
3. **`QtWebSockets` (`QWebSocket`), not the hand-rolled POSIX RFC6455 client.**
|
||
`QWebSocket` integrates with the Qt event loop, exposes
|
||
`textMessageReceived`/`binaryMessageReceived` signals, and removes the need
|
||
for a manual receive thread + mutex-guarded queue. Auto-reconnect is a 3 s
|
||
`QTimer`. Both Qt5 and Qt6 ship the WebSockets module (verified present).
|
||
|
||
4. **Qt5/6 autodetect in CMake.**
|
||
`find_package(QT NAMES Qt6 Qt5 REQUIRED COMPONENTS Widgets WebSockets)` then
|
||
`find_package(Qt${QT_VERSION_MAJOR} ...)`; link `Qt${QT_VERSION_MAJOR}::*`.
|
||
This is the upstream-recommended idiom; prefers Qt6 when present, falls back
|
||
to Qt5. `CMAKE_AUTOMOC ON`.
|
||
|
||
5. **Reuse, do not fork, the wire layer.**
|
||
`Protocol.h`, `Protocol.cpp`, and `SignalBuffer.h` in `Client/streamhub/` are
|
||
pure C++17/STL with **no ImGui/SDL dependency** (verified). The Qt project
|
||
compiles `../streamhub/Protocol.cpp` directly and adds `../streamhub` to its
|
||
include path. Single source of truth for the protocol — any future protocol
|
||
change is picked up by both clients. The only ImGui type leaking into the
|
||
reference *domain* model is `ImVec4 color`; the Qt project defines its own
|
||
domain model (`Model.h`) using `QColor` instead.
|
||
|
||
## Threading model
|
||
|
||
Single-threaded around the Qt event loop:
|
||
- `QWebSocket` delivers frames as signals on the GUI thread → parsed via the
|
||
reused `Protocol` functions → mutate the model directly (no locks needed,
|
||
unlike the ImGui version whose WS ran on a background thread).
|
||
- A `QTimer` at ~60 Hz calls `update()` on visible `PlotWidget`s for smooth
|
||
live scrolling (decoupled from data arrival rate).
|
||
|
||
This is simpler and safer than the ImGui client's background-thread + drain-queue
|
||
model, and is the idiomatic Qt approach.
|
||
|
||
## Module / file structure (`Client/streamhub-qt/`)
|
||
|
||
| File | Responsibility |
|
||
|------|----------------|
|
||
| `CMakeLists.txt` | Qt5/6 autodetect, sources, reuse `../streamhub/Protocol.cpp`, install rules |
|
||
| `main.cpp` | `QApplication`, arg parse (`-host`/`-port`), apply dark theme, show `MainWindow` |
|
||
| `Theme.h/.cpp` | Catppuccin-Mocha `QPalette` + stylesheet, trace color palette |
|
||
| `Model.h` | Domain types: `Signal` (with `QColor`), `Source`, `TriggerCfgState`, `VScale`, `PlotAssignment`, `PlotLayout` enum + dims |
|
||
| `Hub.h/.cpp` | `QObject` controller: owns `QWebSocket`, model (`std::vector<Source>`), trigger state, capture, zoom caches, history info. Parses WS messages (reused `Protocol`), exposes command senders, emits Qt signals (`sourcesChanged`, `configChanged`, `statsChanged`, `triggerStateChanged`, `captureReceived`, `zoomReceived`, `historyInfoChanged`, `connectedChanged`). |
|
||
| `WsClient.h/.cpp` | Thin `QWebSocket` wrapper: connect/reconnect (`QTimer`), `sendText`, `textReceived`/`binaryReceived`/`connectedChanged` signals |
|
||
| `PlotWidget.h/.cpp` | Custom `QPainter` oscilloscope panel (one per grid cell). Owns per-plot view state (live/window, stored X range, zoom history, vMode, active slot, zoom caches, paused snapshot, trig-zoom). Renders, handles mouse zoom/pan + drag-drop, draws cursors, requests hi-res/history zoom through `Hub`. |
|
||
| `PlotGrid.h/.cpp` | Grid of `PlotWidget`s using nested `QSplitter`s per `PlotLayout`; rebuilds on layout change; routes drops |
|
||
| `SourceSidebar.h/.cpp` | `QTreeWidget` of sources→signals (drag source), connect/remove, "Add source" dialog launcher |
|
||
| `TriggerBar.h/.cpp` | Trigger config widgets (signal combo, edge, threshold, window combo, pre% slider, normal/single) + Arm/Disarm/Rearm/Stop + state badge |
|
||
| `StatsDialog.h/.cpp` | Per-source metrics table + 20-bin histogram (custom `QPainter` bar widget) |
|
||
| `HistoryBar.h/.cpp` | Live/range/pan/jump-preset/All history navigation |
|
||
| `MainWindow.h/.cpp` | `QMainWindow`: toolbar (sidebar toggle, layout picker, pause, cursors, trigger, history, window presets, stats, connection, status LED), assembles sidebar + grid + bars, owns `Hub`, the 60 Hz repaint `QTimer`, and the add-source dialog |
|
||
|
||
## Feature parity checklist (must match the ImGui client)
|
||
|
||
- Live wall-clock X window with presets {1,5,10,30,60 s} + Ctrl+scroll resize.
|
||
- Plot layouts {1×1, 2×1, 1×2, 3×1, 1×3, 2×2, 4×1, 1×4} via splitters.
|
||
- Drag a signal from the sidebar onto a plot; per-trace color/width/marker via
|
||
context menu; remove-from-plot; "active" trace selection.
|
||
- V-scale per trace: Auto / Range / Manual (V/div, offset, screen pos); Y ticks
|
||
labelled from the active trace; ±4-division fixed Y space.
|
||
- Per-plot V-mode: Normal / Digital / Mixed band normalization (ports
|
||
`applyDigitalNorm`/`applyMixedNorm` math already in `PlotPanel.cpp`).
|
||
- Mouse: scroll = Y zoom of active trace (or X zoom if none); Ctrl+scroll = X
|
||
zoom / window resize; Shift+scroll = Y pan; right-drag = X pan (live→non-live).
|
||
- Zoom history Back / Fit / Live per plot.
|
||
- Global pause (freeze view snapshot; rings keep filling); global A/B cursors
|
||
with ΔT, 1/ΔT, per-trace A/B/Δ readouts.
|
||
- Hi-res zoom over WS (`zoom` cmd, 2400 pts) for live-narrow and zoomed views;
|
||
history zoom (`historyZoom`) for disk-backed ranges; "HIST" indicator.
|
||
- Trigger: full config → `setTrigger`; Arm/Disarm/Rearm/Stop; state badge
|
||
(idle/armed/collecting/triggered); v2 capture frame → capture view rendered in
|
||
`[-pre,+post]` with trigger marker at t=0; capture-view zoom + Reset.
|
||
- Stats dialog: state, totalReceived, totalLost, rateHz±std, frags/bytes per
|
||
cycle, cycle avg/std/min/max ms, 20-bin cycle-time histogram.
|
||
- Add/remove source; connection host/port edit + reconnect; status LED.
|
||
- LTTB decimation to ≤2400 pts/trace before drawing (reuse `LTTBDecimate`).
|
||
|
||
## Build & run
|
||
|
||
```bash
|
||
cd Client/streamhub-qt
|
||
cmake -B build -DCMAKE_BUILD_TYPE=Release
|
||
cmake --build build -j
|
||
./build/StreamHubQtClient -host 127.0.0.1 -port 8090
|
||
```
|
||
|
||
Verification: run `./run_streamhub.sh` (or the recorder E2E streamer) to get a
|
||
live hub, then confirm live streaming, zoom (live + box), trigger capture, stats
|
||
histogram, and history browse all behave like the ImGui client.
|
||
|
||
## Out of scope
|
||
|
||
- No new protocol features; byte-for-byte the same WS protocol.
|
||
- Sub-project E (Go `Client/debugger/` → Qt) is a separate spec.
|
||
- Font Awesome glyph icons are replaced by Qt standard icons / unicode; exact
|
||
icon glyphs are not required for parity.
|