72 lines
3.0 KiB
Markdown
72 lines
3.0 KiB
Markdown
# Ground Suite
|
|
|
|
Ground Suite is Kaptan's desktop ground-control software. Its application
|
|
identifier is `dev.kaptan.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
|
|
|
|
```text
|
|
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:
|
|
|
|
```sh
|
|
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.
|
|
|
|
## Appearance
|
|
|
|
Ground Suite supplies light and dark themes and follows the operating system
|
|
by default. Its dark palette uses near-black, muted-silver, and restrained
|
|
green accents; translucent, locally blurred panels keep operational content
|
|
legible without turning diagnostics into decoration.
|
|
|
|
Use the appearance button in the observation bar to select **System default**,
|
|
**Light**, or **Dark**. The choice applies for the current session only.
|
|
|
|
## 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.
|