AutoForge/docs/synthetic-diagnostics-v2.md

5.0 KiB

Synthetic diagnostics protocol v2: dynamics telemetry

Compatibility boundary

Protocol v2 is an explicit UTF-8 JSON extension for the separate autoforge.simulation.dynamics provider. It does not reinterpret or weaken protocol v1: autoforge.simulation.synthetic continues to require v1 static semantics, including origin SYNTHETIC_STATIC and the request-start logical tick. A static session cannot acquire dynamics controls, and a dynamics session must be opened with a validated immutable format-v1/model-v1 DynamicsConfiguration. This protocol is synthetic in-process JSON, not CAN/ISO-TP/UDS/OBD-II or a manufacturer protocol.

The request envelope has the same required top-level fields as v1, but its version is exactly 2 and its configurationIdentifier binds the selected profile revision and stable dynamics fingerprint. sessionIdentifier and the separate dynamics run identifier provide operational isolation. The request's logicalTimeTicks is the diagnostic capture/request clock; it is not model time.

Dynamic read.signals payload

All v2 response envelopes retain the strict v1 envelope/correlation fields, with version: 2. The read.signals data object has exactly these required fields:

Field Meaning
moduleIdentifier Exact requested engine or transmission module
configurationIdentifier Stable sha256:v1:<hex> configuration fingerprint
runIdentifier Operational dynamics-run ID bound to this session
modelStepIndex Nonnegative integer fixed-step count
modelTimeSeconds Virtual model time, equal to step index times configured step seconds
origin Exactly SYNTHETIC_DYNAMIC
captureLogicalTimeTicks Diagnostic logical start tick, exactly matching the request
signals Exact source module signal list, with identifier, JSON value, unit and quality

Signal identifiers and units are validated exactly. Engine signals are engine.running (boolean), engine.speed (rpm), vehicle.speed (m/s), engine.throttle (ratio), engine.load (ratio), engine.torque (N*m), engine.fuel-rate (kg/s), engine.fuel-consumed (kg), engine.temperature (degC), vehicle.distance (m), vehicle.acceleration (m/s^2), and driver.brake (ratio). Transmission signals are transmission.gear (gear), transmission.shift-count (count), transmission.coupling-slip (ratio), vehicle.speed (m/s), and engine.speed (rpm). Numeric dynamic values must be finite JSON numbers; identifiers, source module, units, quality, origin and model/run/configuration identity are retained in the typed snapshot.

The receiver rejects duplicate/unknown/missing fields, unsupported versions, invalid correlation/envelope identity, wrong module, unexpected dynamic signal or unit, non-finite numeric telemetry, wrong capture tick, invalid model step/ time, and configuration/run mismatch as ProtocolError with no partial value. The configured step size is used to validate modelTimeSeconds = modelStepIndex * stepSeconds. Positive replies preserve the transport's elapsed diagnostic ticks in bounded trace timing; those ticks remain independent from model step/time.

Every request samples the engine once under its state lock and serializes that snapshot. A paused or explicitly stepped run therefore returns the same step/time from engine and transmission reads until a control step occurs. While the asynchronous scenario pacer is running, separate requests can capture different steps; each response reports its actual step/time and does not imply simultaneous capture. Reads themselves never advance the engine.

A faulted run never serializes a positive dynamic snapshot: read.signals returns a correlated v2 negative response with failure code DYNAMICS_RUN_FAULTED and the retained lifecycle reason. It does not replace a failed computation with zero-valued or empty Good signals. The UI preserves that terminal failure and clears any previously displayed rows so older successful values cannot be mistaken for current post-fault telemetry.

Probe, identity, DTC and clear service names retain their v1 service-level shapes inside a v2 envelope. Dynamics module services are still checked against their explicit endpoint advertisement; provider selection never falls back to the static provider. Static protocol clients and static provider response versions remain v1. The actual strict client and provider implementation is in AutoForge.Diagnostics and AutoForge.Simulation; Application/UI telemetry still traverses encoded diagnostic frames rather than a model-state oracle.

Limitations

The origin means generated by this AutoForge synthetic model only. Quality Good means the deterministic synthetic computation completed, not sensor quality or real vehicle truth. The model omits detailed engine combustion, torque-converter dynamics, tire/road conditions, gearshift transient mechanics, thermal circuits, emissions, manufacturer calibration and uncertainty quantification. Protocol v2 is not evidence of compatibility, prediction accuracy, safe tuning or physical authorization.