diff --git a/docs/src/ground-suite.md b/docs/src/ground-suite.md index ad012ac..dc5662a 100644 --- a/docs/src/ground-suite.md +++ b/docs/src/ground-suite.md @@ -1,48 +1,72 @@ # Ground Suite -`ground-suite/` is Kaptan's desktop Flutter ground-control application. Its -first implementation is a deterministic, read-only replay console rather than -a vehicle-control or configuration application. +`ground-suite/` is Kaptan's desktop Flutter application. Its primary +workspace is the Tactical Command surface: a spatial local scene, local units, +and session-local drawings and markers. The decoded diagnostic event stream is +always reachable from the tactical header. -It currently presents a received vehicle identity and heartbeat, telemetry -presence, ordinary `KAPTAN_LOG` records, distinct `KAPTAN_ERROR` path/detail -records, and `KAPTAN_SHUTDOWN` observations. It sends no MAVLink bytes. +## Application model -This scope reflects the firmware boundary: the F722 telemetry image discards -every inbound MAVLink frame, and SITL does not yet expose a MAVLink endpoint. -Link presence is never presented as proof of safety, authority, arming state, -or write capability. +The core model keeps these concepts independent: -Ground Suite provides light and dark themes, selecting the operating system's -current preference by default. Its dark theme uses a near-black canvas, -muted-silver text, and restrained green accents. Locally blurred glass is -limited to persistent navigation and session chrome; vehicle facts and the -event stream use opaque instrument surfaces so they remain readable at volume. -The desktop rail and compact session strip offer a current-session System, -Light, or Dark appearance selector. +- **Vehicle definition** — immutable reviewed profile, catalog identity, and + bundled presentation media. +- **Local fleet unit** — an operator-created instance of a vehicle definition. + Local-unit IDs and in-memory planning placements belong to the workspace, + not the vehicle definition. Current placement is local presentation data and + is not yet persisted. +- **Received vehicle data** — transport input and diagnostic events. It cannot + create, position, identify, or authorize a local fleet unit. -The replay shell is organised as an operator scan path: source and authority, -then last reported heartbeat and observed streams, then ingress accounting and -the event stream. It labels reported vehicle state precisely and never infers -current safety, command authority, or configuration capability from a replay -or a received diagnostic record. The event stream keeps ordinary logs, runtime -errors, and orderly shutdown reports visually and semantically distinct. Its -local history is bounded; the interface prioritises runtime errors and orderly -shutdown reports, and reports any local UI eviction independently from -vehicle-side diagnostic loss. +This separation gives the fleet interface a stable path from local planning to +future live operation without coupling visual selection to incoming telemetry. -Ground Suite uses a receive-only source/decoder/classifier boundary. The -replay implementation feeds typed observations today. A future live adapter -must combine pinned MAVLink Common definitions with `kaptan.xml`, reject -MAVLink 1 and invalid MAVLink 2 frames, validate diagnostic length fields -before UTF-8 decoding, retain unknown severity/reason/flag values, and count -unsupported or malformed data as parser/semantic drops without ending a -session. +## Tactical workspace -Configuration screens, CBOR upload, vehicle commands, arm/calibration, and -shutdown controls are deliberately deferred. They require the corresponding -firmware authority, authenticated ingress, replay protection, persistence, -and disarmed activation features first. +The default route is Tactical Command. Its map-edge `UNITS`, `CURSOR`, and +`VIEW` groups are local interactions, not MAVLink controls. `Selection cursor` +is the default mode for map and rectangle selection. `Pencil cursor` creates +session-local freehand strokes; its top toolbar controls hue, saturation, +brightness, and thickness. `Marker cursor` has an independent full-color +style and creates a named local marker only after a map click and explicit +save. The shared disclosure keeps local scene data, +vehicle link state, and command authority separate. Local drawings and markers +are never reported vehicle positions. -See [Ground Suite's README](../../ground-suite/README.md) for its project -layout, development commands, and scoped follow-up work. +`Add local unit` opens the horizontal local hangar. Choosing a definition only +prepares a local unit draft; the explicit setup confirmation creates and +selects a locally scattered scene unit, without asking the operator to click +the map. Local setup currently permits only the workspace label. Vehicle +configuration remains unavailable until verified binding, compatible schema, +command authority, and safe activation are available. This presentation +placement is temporary until reviewed MAVLink position data can drive a +distinct reported-position layer. The right inspector and bottom selection +console are available outside the map for keyboard and assistive-technology +access. These interactions create only session-local workspace data. + +## Architecture + +```text +VehicleDataPort -> typed observation updates -> observability state -> event stream +Vehicle catalog -> local-unit workspace state -> tactical scene and unit inspector +``` + +The transport path and local-fleet path intentionally meet only through future +explicit bindings. A future MAVLink adapter combines pinned MAVLink Common and +Kaptan dialect definitions at the decoding boundary. + +## Follow-up work + +- TODO(gcs-fleet-storage): versioned persistence for local units and catalog + identities. +- TODO(gcs-source-binding): explicit source-to-unit binding. +- TODO(gcs-map-pose): coordinate datum, timestamped pose, uncertainty, and + staleness handling for physical map placement. +- TODO(gcs-map-renderer): owned Linux GPU map host, pinned MapLibre assets, + and reviewed vector/DEM data source. +- TODO(gcs-platform-match): compare reported build/schema metadata to the + local definition. +- TODO(gcs-command-surface): add command interaction only with its reviewed + authority, target-binding, and safety contracts. +- TODO(gcs-catalog): generate installed definitions and category metadata from + reviewed firmware build manifests. diff --git a/ground-suite/README.md b/ground-suite/README.md index b0f0c13..e7c8545 100644 --- a/ground-suite/README.md +++ b/ground-suite/README.md @@ -1,35 +1,6 @@ # 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 reported vehicle identity and -heartbeat, 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 - -> Vehicle observation / Event stream 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. +Ground Suite is Kaptan's desktop ground-control application. ## Development @@ -42,49 +13,12 @@ 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. +## Layout -## Appearance +- `lib/app/` — application shell and appearance. +- `lib/features/fleet/` — fleet canvas and local-unit workspace. +- `lib/features/vehicle_workspace/` — installed vehicle definitions and Add-unit flow. +- `lib/features/diagnostics/` — diagnostic event stream. +- `lib/core/` — transport and MAVLink decoding boundaries. -Ground Suite supplies light and dark themes and follows the operating system -by default. Its dark palette pairs a near-black canvas with muted-silver text -and restrained green accents. The visual system is intentionally layered: -locally blurred glass is reserved for persistent navigation and session -chrome, while vehicle facts and the event stream use opaque instrument -surfaces for reliable scanning at volume. - -Use **Appearance** in the desktop rail or compact session strip to select -**System default**, **Light**, or **Dark**. The choice applies for the current -session only. - -## Replay workspace - -The shell keeps provenance and authority visible before any detail: - -- **Vehicle observation** presents the replay source, last reported heartbeat, - observed data streams, and ingress accounting. Typed replay marks integrity - as not evaluated; reported state is not a current safety authority. -- **Event stream** is a dense, copyable diagnostic timeline. Logs, runtime - errors, and orderly shutdown reports remain distinct, and bounded delivery - flags such as truncation and coalescing remain visible. The app retains a - bounded local history, prioritising runtime errors and shutdown reports, and - discloses local UI evictions separately from vehicle-side delivery loss. -- **Vehicle setup · unavailable** is explanatory text, not a disabled control. - It accurately reflects that this firmware currently accepts no inbound - MAVLink authority. - -## 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. +The durable design and integration notes live in [the documentation](../docs/src/ground-suite.md).