kaptan/ground-suite/README.md

Ground Suite

Ground Suite is Kaptan's desktop ground-control software. Its application identifier is com.orkavian.ground_suite.

Current scope

The first vertical slice is a read-only observability console. It uses a deterministic replay fixture to present a vehicle identity, heartbeat state, telemetry presence, ordinary logs, runtime errors, and orderly-shutdown observations. It never sends bytes to a vehicle.

This is deliberate: the current F722 firmware rejects every inbound MAVLink frame, and kaptan-sitl serve has no MAVLink endpoint. A connected-looking UI must not suggest the vehicle is controllable, safe, armed, or writable.

Architecture

VehicleDataPort (replay now; MAVLink adapter later)
        -> typed observation-or-drop updates
        -> Riverpod observability state
        -> Overview / Diagnostics presentation

MavlinkByteSource and MavlinkEventDecoder are receive-only seams. The future decoder must combine pinned MAVLink Common definitions with Kaptan's kaptan.xml root, and preserve the firmware's semantic rules for bounded KAPTAN_LOG, KAPTAN_ERROR, and KAPTAN_SHUTDOWN payloads. Raw severity, shutdown-reason, and diagnostic-flag values remain visible even when an app does not yet recognise them. Expected malformed or unsupported frames become parser/semantic drop updates and never terminate the observation stream.

Development

From the repository root:

nix develop -c flutter analyze ground-suite
nix develop -c dart format --set-exit-if-changed ground-suite
nix develop -c sh -c 'cd ground-suite && flutter test'
nix develop -c sh -c 'cd ground-suite && flutter run -d linux'

Linux is the first tested desktop runner. Native macOS and Windows runners will be added only with their respective CI coverage.

Deliberately deferred work

• TODO(gcs-live-mavlink): generated MAVLink Common plus custom-dialect bindings, a MAVLink 2 receive parser, semantic validation, and serial/UDP/recording endpoints.
• TODO(gcs-connection): endpoint lifecycle, reconnect generation, link-loss policy, and parser/semantic-drop accounting sourced from real frames.
• TODO(gcs-config): descriptor-driven configuration UI only after firmware has authenticated ingress, source binding, persistent anti-replay state, target storage, and a disarmed atomic activation path.
• TODO(gcs-upload): CBOR import/export only through the reviewed transaction protocol; never treat a local file as active vehicle configuration.
• TODO(gcs-control): arm, command, calibration, and shutdown workflows need their own reviewed authority and safety contracts.