AutoForge/docs/live-dashboard.md

6.3 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 unit. No unit conversion, alias, role-based guessing or fallback is performed. Definitions are process/session memory only; there is no dashboard persistence or import/export format.

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 -10 with low-range status and zero-width geometry; 1100 remains 1100 with high-range status and full-width geometry for a 0..1000 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 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. Hiding or disposing the panel detaches that 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. The dashboard adds no recording, charts, unit conversion, vehicle compatibility, manufacturer prediction, hardware access, calibration editing or physical writes.