docs: describe tactical Ground Suite workspace
This commit is contained in:
Onur Özkan committed
1 parent
35e0fd8741
commit
43347c1172
2 files changed
+71
-113
No files matched your search
+63
-39
@@ -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.
|
||||
+8
-74
@@ -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).
|
||||
Reference in new issue
Block a user