# 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.)