167 lines
9.0 KiB
Markdown
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.
|