First commit
This commit is contained in:
125
README.md
Normal file
125
README.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# Telemetry Monitor
|
||||
|
||||
A Flutter application for visualizing real-time telemetry streams over WebSocket.
|
||||
Targets: Linux desktop, Android, and Web browsers (Flutter 3.41+).
|
||||
|
||||
## What it does
|
||||
|
||||
Connects to a WebSocket server, decodes Protocol Buffer packets carrying up to
|
||||
16 channels of `double` data plus 8 status integers and a pause flag, and renders
|
||||
them as rolling time-series charts at 60 Hz. Also receives log packets with
|
||||
severity, error number, timestamp, and description.
|
||||
|
||||
Key features:
|
||||
|
||||
- 4–16 simultaneous charts in a configurable grid.
|
||||
- 1 kHz packet rate with batched per-frame rendering.
|
||||
- Min/max decimation for smooth display at any zoom level.
|
||||
- Hatched regions for missing-data gaps; thin markers for sub-pixel gaps.
|
||||
- Scrollback through the configured packet buffer (default 10 minutes).
|
||||
- Shared X-zoom across charts; per-chart Y-zoom.
|
||||
- Two-tab UI: dashboard with errors-only mini log, plus a full filterable log.
|
||||
- CSV export for both packet data and log entries.
|
||||
- Pause from UI button or from a proto field.
|
||||
- 8 named status indicators with 4-state color coding (gray / red / yellow / green).
|
||||
|
||||
## Quick start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Flutter 3.41 or later.
|
||||
- Protocol Buffers compiler (`protoc`) version 3.x.
|
||||
- The Dart `protoc_plugin` package (installed automatically via `pubspec.yaml`).
|
||||
|
||||
### Generating Protobuf bindings
|
||||
|
||||
The `messages.proto` file lives in `proto/`. After cloning, run:
|
||||
|
||||
mkdir -p lib/proto
|
||||
protoc --dart_out=lib/proto/ -Iproto/ proto/messages.proto
|
||||
|
||||
This produces `lib/proto/messages.pb.dart` and friends. The generated files are
|
||||
gitignored; regenerate after any schema change.
|
||||
|
||||
### Running
|
||||
|
||||
flutter pub get
|
||||
flutter run -d linux # Linux desktop
|
||||
flutter run -d <device-id> # Android
|
||||
flutter run -d chrome # Web (CanvasKit recommended)
|
||||
|
||||
For Web, prefer the CanvasKit renderer for chart performance:
|
||||
|
||||
flutter run -d chrome --web-renderer canvaskit
|
||||
|
||||
### First-run configuration
|
||||
|
||||
The app starts with a default WebSocket URL of `ws://localhost:9000`. Open
|
||||
**Settings** to change it. Open **Layout** to assign channels to grid cells and
|
||||
name them.
|
||||
|
||||
## Architecture overview
|
||||
|
||||
See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the full design. Brief summary:
|
||||
|
||||
- **Transport** owns the WebSocket and reconnection.
|
||||
- **Decoder** turns raw frames into `Envelope` messages (isolate on native,
|
||||
inline on Web).
|
||||
- **Session** owns ring buffers for packets and logs, the view-state machine,
|
||||
and the per-frame Ticker that drives all rendering.
|
||||
- **Layout** owns the grid configuration, channel assignments, channel names,
|
||||
and status indicator names. Persisted via `shared_preferences`.
|
||||
- **Export** writes CSV files (path_provider on native, Blob download on Web).
|
||||
- **UI** is a `CustomPainter`-based chart grid plus the toolbar, status bar,
|
||||
tabs, and dialogs.
|
||||
|
||||
## Key invariants
|
||||
|
||||
These are the design rules that keep the app correct. Don't violate them
|
||||
without re-reading `ARCHITECTURE.md`.
|
||||
|
||||
1. **Single source of truth.** Sample data lives only in the packet ring
|
||||
buffer. Log entries live only in the log ring buffer. Status snapshots
|
||||
are *derived* from the packet buffer each frame, not latched.
|
||||
|
||||
2. **Producer/consumer decoupling.** WebSocket packets write into ring buffers
|
||||
eagerly. Charts repaint only on the per-frame Ticker. The two are decoupled
|
||||
by design — never call repaint from a packet handler.
|
||||
|
||||
3. **Disabled channels still record.** Toggling a channel "off" hides it on
|
||||
the dashboard but does not stop recording or change the CSV output.
|
||||
|
||||
4. **Buffer is authoritative for export.** CSV always reads from the buffer,
|
||||
never from cached UI snapshots.
|
||||
|
||||
5. **Window state is shared, Y state is per-chart.** All charts share one
|
||||
X-axis window (zoom + pan + anchor). Each chart owns its own Y-mode and
|
||||
Y-range.
|
||||
|
||||
## Project layout
|
||||
|
||||
lib/
|
||||
main.dart # Entry point
|
||||
app.dart # MaterialApp, top-level wiring
|
||||
proto/ # Generated from messages.proto
|
||||
config/ # AppConfig, Settings (persisted)
|
||||
transport/ # WebSocket abstraction
|
||||
decoder/ # Protobuf decoding
|
||||
session/ # Ring buffers, view state, controller
|
||||
layout/ # Grid + chart config
|
||||
export/ # CSV exporter
|
||||
ui/ # Widgets, dialogs, painters
|
||||
proto/
|
||||
messages.proto # Protocol Buffer schema
|
||||
|
||||
## Build targets
|
||||
|
||||
| Target | Notes |
|
||||
| ------- | -------------------------------------------------------- |
|
||||
| Linux | Primary development target. Full feature set. |
|
||||
| Android | Same code as Linux. Uses `IOWebSocketChannel`. |
|
||||
| Web | Decoder runs inline (no isolates). CanvasKit recommended. CSV export uses Blob downloads. |
|
||||
|
||||
## License
|
||||
|
||||
(Add as appropriate.)
|
||||
Reference in New Issue
Block a user