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.