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
|
||||||
|
|
||||||
`ground-suite/` is Kaptan's desktop Flutter ground-control application. Its
|
`ground-suite/` is Kaptan's desktop Flutter application. Its primary
|
||||||
first implementation is a deterministic, read-only replay console rather than
|
workspace is the Tactical Command surface: a spatial local scene, local units,
|
||||||
a vehicle-control or configuration application.
|
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
|
## Application model
|
||||||
presence, ordinary `KAPTAN_LOG` records, distinct `KAPTAN_ERROR` path/detail
|
|
||||||
records, and `KAPTAN_SHUTDOWN` observations. It sends no MAVLink bytes.
|
|
||||||
|
|
||||||
This scope reflects the firmware boundary: the F722 telemetry image discards
|
The core model keeps these concepts independent:
|
||||||
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.
|
|
||||||
|
|
||||||
Ground Suite provides light and dark themes, selecting the operating system's
|
- **Vehicle definition** — immutable reviewed profile, catalog identity, and
|
||||||
current preference by default. Its dark theme uses a near-black canvas,
|
bundled presentation media.
|
||||||
muted-silver text, and restrained green accents. Locally blurred glass is
|
- **Local fleet unit** — an operator-created instance of a vehicle definition.
|
||||||
limited to persistent navigation and session chrome; vehicle facts and the
|
Local-unit IDs and in-memory planning placements belong to the workspace,
|
||||||
event stream use opaque instrument surfaces so they remain readable at volume.
|
not the vehicle definition. Current placement is local presentation data and
|
||||||
The desktop rail and compact session strip offer a current-session System,
|
is not yet persisted.
|
||||||
Light, or Dark appearance selector.
|
- **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,
|
This separation gives the fleet interface a stable path from local planning to
|
||||||
then last reported heartbeat and observed streams, then ingress accounting and
|
future live operation without coupling visual selection to incoming telemetry.
|
||||||
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.
|
|
||||||
|
|
||||||
Ground Suite uses a receive-only source/decoder/classifier boundary. The
|
## Tactical workspace
|
||||||
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.
|
|
||||||
|
|
||||||
Configuration screens, CBOR upload, vehicle commands, arm/calibration, and
|
The default route is Tactical Command. Its map-edge `UNITS`, `CURSOR`, and
|
||||||
shutdown controls are deliberately deferred. They require the corresponding
|
`VIEW` groups are local interactions, not MAVLink controls. `Selection cursor`
|
||||||
firmware authority, authenticated ingress, replay protection, persistence,
|
is the default mode for map and rectangle selection. `Pencil cursor` creates
|
||||||
and disarmed activation features first.
|
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
|
`Add local unit` opens the horizontal local hangar. Choosing a definition only
|
||||||
layout, development commands, and scoped follow-up work.
|
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
|
||||||
|
|
||||||
Ground Suite is Kaptan's desktop ground-control software. Its application
|
Ground Suite is Kaptan's desktop ground-control 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.
|
|
||||||
|
|
||||||
## Development
|
## 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'
|
nix develop -c sh -c 'cd ground-suite && flutter run -d linux'
|
||||||
```
|
```
|
||||||
|
|
||||||
Linux is the first tested desktop runner. Native macOS and Windows runners
|
## Layout
|
||||||
will be added only with their respective CI coverage.
|
|
||||||
|
|
||||||
## 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
|
The durable design and integration notes live in [the documentation](../docs/src/ground-suite.md).
|
||||||
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.
|
|
||||||
Reference in new issue
Block a user