AutoForge/docs/live-dashboard.md

10 KiB

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. Undefined proposals are rejected before preference initialization or storage access. Both selectors are bound to the committed selection, so a failed save rerenders them to the last active choice; a later successful change clears the error.

Diagnostics and simulation primary readouts use the same typed presentation boundary. Missing/null/undefined values and Unknown quality show --; a wrong JSON type for a known numeric unit also shows -- with an explicit error. The separately labeled source value, exact unit, quality and sample context remain visible (null is written explicitly rather than rendered blank). Finite Uncertain numbers remain numeric and retain an Uncertain notice/state. Numeric zero and boolean false remain distinct real values. Unsupported units retain their exact source value and unit with an explicit unconverted notice, including non-numeric text; they are not treated as a converted measurement.

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, v2 protocol and simulation guide.

Ownership and cleanup

The recorded replay route reuses the same validated 0..8 definitions, pinned-unit editor, display conversion and numeric/bar renderer. It supplies a distinct archive-only source, never a fake live session/feed. Every replay card and accessible reading is explicitly recorded, including Good, Paused, Completed and last-known Stale values. Its page owns playback; hide/show, unit changes and gauge remounts do not own a timer or operate a source. Before-first has no values even though positive archived binding metadata is available to configure gauges.

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:

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.

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.