91 lines
5.0 KiB
Markdown
91 lines
5.0 KiB
Markdown
# 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](synthetic-diagnostics-v1.md): `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.
|