AutoForge/docs/live-dashboard.md

167 lines
9.0 KiB
Markdown

# Live dashboard usage and contracts
The shared **Session live dashboard** is available in `/diagnostics` and
`/simulation` after that page has opened its explicit diagnostic session. It
configures numeric or horizontal-bar views over the real session's synthetic
diagnostic signals. It does not open a session, read a simulation engine
directly, or access a physical vehicle.
## Configure and operate
1. Open a static session on `/diagnostics` or a dynamics session on
`/simulation`.
2. Select **Start monitoring**. The first cycle performs discovery and actual
`read.signals` requests. Only identity-verified endpoints advertising that
service are eligible. The initial snapshots populate the editor's verified
module and signal choices.
3. Add a gauge with a trimmed unique identifier, trimmed label, numeric or
horizontal-bar type, explicit module/signal, exact source unit, finite
minimum/maximum, and decimal precision from 0 through 3. Save applies the
complete proposed definition set atomically. Edit and remove operate on the
same in-memory set.
4. Hide the editor or gauges as desired. **Hide gauges** and removal of the last
gauge do not stop monitoring. Use **Stop monitoring** to stop acquisition;
closing/replacing the diagnostic session also ends it.
There may be zero through eight configured gauges. Gauge identifiers are unique
using ordinal case-insensitive comparison. Module identifiers compare
case-insensitively; signal identifiers, units and origins are exact ordinal
values. Labels and gauge identifiers cannot have surrounding whitespace.
Minimum and maximum must be finite, ordered, and have a finite positive span;
the precision is an integer 0..3. Binding validation requires the exact
session-observed module, signal and source unit. Conversion never changes this
binding contract. Definitions are process/session memory only; there is no
dashboard persistence or import/export format.
## Display units
The shared shell exposes one **Unit system** selector (Metric or Imperial (US))
and one **Speed presentation** selector (Road or Engineering), including before
a vehicle session opens. First use defaults to **Imperial (US) / Road**;
ordinary speed therefore displays mph. Road mode selects km/h or mph, while
Engineering selects source m/s or ft/s. Changing the system preserves the
selected speed mode. The native Client persists this small preference with
MAUI's local Preferences store, so it survives route navigation and app restart.
Missing data means the first-use default. Invalid or unreadable data is reported
visibly with the explicitly labeled Imperial/Road default; it is not silently
overwritten. A selection is published only after a successful write, so a
failed save leaves the prior active choice in effect and exposes an error.
Portable test compositions use an isolated store; the UI-only fallback is an
explicit unavailable store, not an in-memory native substitute.
Conversion uses the exact source unit and raw numeric sample, before the
existing display precision. The supported mappings are:
| Exact source unit | Metric | Imperial (US) |
|---|---|---|
| `m/s` | Road `km/h`; Engineering `m/s` | Road `mph`; Engineering `ft/s` |
| `m` | `m` | `ft` |
| `kg` | `kg` | `lb` |
| `kg/s` | `kg/s` | `lb/h` |
| `N*m` | `N*m` | `lbf*ft` |
| `degC` | `degC` | `degF` |
| `m/s^2` | `m/s^2` | `ft/s^2` |
| `rpm`, `V`, `ratio`, `count`, `gear`, `boolean` | Exact source unit | Exact source unit |
The factors use 1 ft = 0.3048 m, 1 mile = 1609.344 m, 1 lb = 0.45359237 kg,
1 lbf = 4.4482216152605 N, and 3600 seconds per hour; temperature uses
`degF = degC * 9/5 + 32`. Other exact source units pass through with an explicit
unconverted notice and are never relabeled. No UK gallons, fuel economy or
other unassigned conversion is inferred.
Dashboard values and display range labels are separate projections. Gauge
definitions, source values, quality/range/freshness, actual sample context and
bar percentage remain canonical. Editor bounds are shown in the draft's
captured units, then converted once to exact source units on a valid edit.
Unedited saves preserve the original source bounds exactly. A unit change while
an editor is open does not reinterpret typed values; the draft states its
captured unit until save/cancel/reset. Temperature bounds use the full affine
conversion, so 0..100 degC displays as 32..212 degF. Failed or overflowing
projections show an unavailable value/error rather than fabricated data or
invalid geometry.
## Readings, ranges and freshness
The display preserves the actual finite numeric measurement. The horizontal
bar alone is clamped to 0..100 percent; the configured low/high boundary is
shown separately, and an out-of-range value is not rewritten into the range.
For example, `-10` remains the corresponding projected reading with low-range
status and zero-width geometry; `1100` remains the corresponding projected
reading with high-range status and full-width geometry for a 0..1000 source
range. Numeric zero remains a real zero reading.
Measurement quality and range are independent. Good, Uncertain, Unknown,
Pending, Stale, Error, Stopped and Unavailable states are visible as text as
well as accessible descriptions. An Unknown/missing/non-numeric/non-finite
value is shown as `--`, never as a fabricated zero. Finite Uncertain values
remain visibly uncertain, not Good. If a previously Good finite sample is
followed by a failed read or terminal owner error, the last finite value can
remain visible only as Stale with its actual sample context and reason. Without
a prior Good finite sample, the value is Error/`--`. A successful later cycle
can restore the current source quality. Stopped values are not labeled live.
Freshness is cycle-based, not a wall-age promise. One owner completes an
initial cycle, then requests a 250 ms wait after each preceding completed cycle
before the next poll; this is a scheduler interval, not a real-time guarantee or
configurable rate. Polls do not overlap. The snapshot reports a completed cycle,
per-module outcomes and errors. A failed module is not silently treated as an
empty successful response.
## Source and sample context
The panel retains provider/kind, exact profile revision, session and available
dynamics configuration identity. Each value carries the actual module, signal,
unit, origin, quality and logical diagnostic request tick. Per-module request
outcomes and diagnostic trace ticks are distinct; modules are read separately,
so captures are not represented as simultaneous.
The static synthetic provider uses protocol v1 and its source-provided static
sample and logical request timing. The dynamics provider uses protocol v2 and
additionally preserves the actual model step/time, configuration fingerprint
and run identifier returned with each sample. Diagnostic request ticks are not
the dynamics model clock. Polling, rendering and gauge configuration do not
advance a paused or stopped dynamics run. See the [v1 protocol](synthetic-diagnostics-v1.md),
[v2 protocol](synthetic-diagnostics-v2.md) and [simulation guide](simulation.md).
## Ownership and cleanup
The Application feed is bound to the page's actual `DiagnosticSession`; repeated
factory access for that session shares its owner. The feed discovers and reads
through the session's verified diagnostic ports and groups each cycle by
eligible module, not by gauge count. The session owns the feed's asynchronous
lifetime resource. Session close/reset and feature-scope disposal cancel and
drain pending acquisition before the source is released. A new session receives
a new feed and empty source context; an old pending response is not published
into it.
The UI panel subscribes to immutable feed snapshots only to schedule rendering
on the component dispatcher. Display-preference notifications also rerender
mounted presentation without requesting data or changing the feed. Hiding or
disposing the panel detaches its feed subscription; it neither starts a second
poller nor stops the session owner.
Explicit monitoring Stop or session/scope lifetime ends acquisition. Cleanup
errors remain visible and do not skip source disposal.
## Reproducible verification
From the repository root in PowerShell, the assigned full verification is
sequential:
```powershell
dotnet build .\src\AutoForge.slnx --configuration Release --no-restore
dotnet test .\src\AutoForge.slnx --configuration Release --no-build
```
Focused coverage is in `LiveDashboardGaugeRenderingTests`,
`LiveDashboardAcquisitionTests` and `DiagnosticUiCompositionTests` under
`src/tests`. Those tests exercise pure-component rendering, the real static v1
and dynamics v2 providers, controlled polling/cancellation barriers, actual
rendered DI composition, and the session-lifetime path. Headless results do not
substitute for a native Client smoke. Current worker evidence and native status
are recorded in the [Step-05A corrective report](../prompts/Step-05A-Report.md).
all signals and dynamics values remain synthetic. Display units are a
presentation-only projection; the dashboard adds no recording, charts, vehicle
compatibility, manufacturer prediction, hardware access, calibration editing
or physical writes.