274 lines
16 KiB
Markdown
274 lines
16 KiB
Markdown
# Synthetic simulation definitions and state
|
|
|
|
## Definition boundary
|
|
|
|
Vehicle-profile JSON remains the strict schema-v1 metadata contract. Endpoint
|
|
addresses, implemented services, initial DTC state, static signals, response
|
|
latency and deterministic faults live in a separate source-controlled
|
|
`SimulationDefinition`, not in profile JSON.
|
|
|
|
The `SyntheticDiagnosticExamples` catalog contains two inventories:
|
|
|
|
- `autoforge.synthetic.test-truck` revision 1: a synthetic engine controller,
|
|
transmission controller and cabin/body controller.
|
|
- `autoforge.synthetic.orchard-cart` revision 1: an alternate inventory with a
|
|
custom experimental sensor-bridge role.
|
|
|
|
IDs, names, identities and declared configuration are intentionally synthetic.
|
|
The truck has no-response configured for the transmission probe to demonstrate
|
|
that expected inventory is not the same as actual discovery. The body module
|
|
returns an explicit unsupported negative response to virtual DTC clear. The
|
|
engine has one initial virtual DTC and supports virtual clear.
|
|
|
|
`SimulationDefinition.ValidateAgainst` requires the exact profile identifier
|
|
and revision, one unique mapping for every profile module and matching role,
|
|
name and supplied hardware/software/firmware/calibration identity. Endpoint
|
|
addresses and module IDs are unique. Service identifiers must be known protocol
|
|
v1 synthetic services; signal IDs, units, JSON values, DTC values and fault
|
|
entries are validated. Profile capability/provenance declarations do not
|
|
enable or prove a virtual service.
|
|
|
|
Definitions may advertise `probe` without `read.identity`. Discovery then
|
|
retains the validated probe and its advertised services, marks identity as not
|
|
attempted with an explicit reason, and does not synthesize identity from the
|
|
matching profile entry. Expected endpoints, positive probes and identities
|
|
verified against the selected profile are counted separately. Advertised
|
|
read/clear services do not enable UI actions until runtime identity is verified.
|
|
|
|
## Session state
|
|
|
|
Opening a new Simulation session creates independent DTC state for each virtual
|
|
module from its configured initial values. A successful `clear.dtcs` response
|
|
acknowledges the request but is not itself proof of a state change. The
|
|
Application clear-and-verify use case issues a fresh `read.dtcs` request and
|
|
reports success only for a valid empty readback. A nonempty readback remains
|
|
visible and fails verification; timeout, cancellation, closed session,
|
|
no-response or malformed/negative readback is explicit uncertainty, never
|
|
verified success. An already-empty module can still verify successfully even
|
|
when the acknowledgement count is zero. These semantics concern virtual
|
|
in-memory state only; no physical write occurs.
|
|
|
|
An accepted clear changes only that module in that session. Opening a second
|
|
session starts with the definition's original initial values.
|
|
Reset explicitly closes the old session and opens a new one against the same
|
|
exact profile revision/provider/configuration, thereby restoring initial state
|
|
and starting a new trace. Closing releases the old transport and its trace/state.
|
|
No profile metadata or another session is mutated.
|
|
|
|
Normal Application/UI consumers see state only through encoded diagnostic
|
|
requests and typed responses. An internal simulation oracle is granted only to
|
|
the IntegrationTests assembly so tests can independently assert clear/reset/
|
|
isolation behavior; it is not a public provider or application service.
|
|
|
|
## Static signals
|
|
|
|
Signals are configured JSON values with a source module, identifier, unit and
|
|
quality. In this example, engine speed is the fixed synthetic value 850 rpm,
|
|
engine supply voltage is fixed at 12.6 V, transmission state is the string
|
|
`parked-static`, and the body module reports a static synthetic door count.
|
|
Replies carry the logical request tick and origin `SYNTHETIC_STATIC`.
|
|
|
|
These are reproducible fixture values, not dynamic model output, current sensor
|
|
data, a vehicle capture, compatibility evidence or operational advice. Unknown
|
|
values remain unknown. This static provider does not generate motion, fuel,
|
|
road-load or scenario physics; those capabilities are isolated in the explicitly
|
|
selected dynamics provider below.
|
|
|
|
## Fixed-step dynamics configuration
|
|
|
|
The separate `DynamicsConfiguration` document is format version 1 and model
|
|
version 1; it does not change profile schema v1. It binds an exact profile ID,
|
|
revision, vehicle ID, engine/transmission module IDs and calibration references
|
|
to explicit model parameters, initial conditions, and five ordered finite
|
|
scenario phases. Configuration JSON uses exact camelCase member names, string
|
|
scenario enums, and strict required/unknown/duplicate-member validation at every
|
|
object level. Missing values are not defaulted. Input ranges include fixed
|
|
steps from 0.01 to 0.5 s, mass 100-100,000 kg, wheel radius 0.05-2 m, drag area
|
|
0-20 m2, rolling coefficient 0-0.2, ambient density 0.1-2 kg/m3, gravity 1-20
|
|
m/s2, engine speed up to 12,000 rpm, 2-12 strictly descending positive forward
|
|
gear ratios, and finite strictly increasing torque-curve points. Scenario speeds
|
|
are bounded at 150 m/s and durations at 86,400 s; the cruise phase must be at
|
|
least 300 s and return-idle at least 10 s. Initial conditions are copied and
|
|
validated against the model and exact profile.
|
|
|
|
The `sha256:v1:<lowercase hex>` configuration identifier is SHA-256 over stable
|
|
camelCase JSON serialization of the immutable configuration (the derived
|
|
identifier itself is omitted). The catalog is in-memory. Import validates exact
|
|
profile/module/calibration references before registration; export followed by
|
|
import preserves the identifier. A diagnostic run ID is separate from this
|
|
stable configuration fingerprint and is bound into its session identity.
|
|
Reset closes the existing session and opens a new one with the exact original
|
|
immutable configuration object, regardless of later catalog selections.
|
|
|
|
The explicit warmed example uses SI units internally:
|
|
|
|
| Input | Value |
|
|
|---|---:|
|
|
| Fixed virtual step | 0.1 s |
|
|
| Vehicle mass | 1,800 kg |
|
|
| Wheel radius | 0.34 m |
|
|
| Aerodynamic drag area (CdA) | 0.68 m2 |
|
|
| Rolling resistance coefficient | 0.012 |
|
|
| Air density / gravity | 1.2 kg/m3 / 9.80665 m/s2 |
|
|
| Drivetrain efficiency / final drive | 0.9 / 3.6 |
|
|
| Maximum brake force | 10,000 N |
|
|
| Idle / warm target / maximum engine speed | 650 / 650 / 5,000 rpm |
|
|
| Launch slip end speed | 2.5 m/s |
|
|
| Idle fuel flow / fuel mass per joule | 0.00045 kg/s / 1.2e-7 kg/J |
|
|
| Ambient / initial / equilibrium engine temperature | 20 / 88 / 90 degC |
|
|
| Thermal response rate | 0.015 per second |
|
|
| Forward gear ratios | 3.5, 2.2, 1.4, 0.9 |
|
|
| Upshift / downshift schedules | 4,000 / 1,450 rpm per gear |
|
|
|
|
Torque curve points are `(rpm, N*m)`: `(650,240)`, `(1000,300)`,
|
|
`(2000,360)`, `(3200,350)`, `(4200,300)`, `(5000,180)`. Torque is linearly
|
|
interpolated between points and held at endpoint values outside the curve.
|
|
Automatic shifts use the configured schedule and hysteresis; launch coupling
|
|
slip is limited to first gear below the configured launch speed. When locked,
|
|
reported engine speed follows
|
|
|
|
`engineRPM = speed_mps / (2*pi*wheelRadius_m) * 60 * gearRatio * finalDrive`.
|
|
|
|
The launch torque-transfer factor is speed-based and is not the reported slip
|
|
fraction. Reported slip is the normalized engine/wheel RPM discrepancy, so it
|
|
cannot claim zero slip when those speeds differ. Wheel force is
|
|
`engineTorque * gearRatio * finalDrive * efficiency / wheelRadius *
|
|
couplingFactor`. Rolling and aerodynamic loads are `m*g*Crr` and
|
|
`0.5*rho*CdA*v^2`; brake force is configured maximum force times brake ratio.
|
|
Longitudinal acceleration is `(wheelForce - roadLoad - brakeForce)/mass`.
|
|
Each fixed step updates speed using forward Euler with a zero lower bound;
|
|
distance uses trapezoidal integration of the old/new nonnegative speed. Scenario
|
|
controllers adjust bounded throttle/brake commands but never assign vehicle
|
|
speed.
|
|
|
|
An initial running in-gear condition is supported only when engine RPM equals
|
|
the wheel/gear-derived RPM within `1e-8` rpm and remains within the engine
|
|
limits. The initial-condition contract does not invent an unprovided clutch-slip
|
|
input. Scenario targets and initial speed must also fit the top-gear redline
|
|
envelope:
|
|
|
|
`maximumEngineRPM * (2*pi*wheelRadius) / (60*topGearRatio*finalDrive)`.
|
|
|
|
The engine does not independently clamp RPM while keeping an unchanged,
|
|
contradictory wheel speed. The phase throttle is instead bounded to the target
|
|
speed/redline envelope for each fixed step. Inputs outside the documented
|
|
envelope fail validation rather than producing healthy contradictory telemetry.
|
|
|
|
Fuel power is `torque * engineAngularVelocity`; fuel rate is idle flow plus
|
|
nonnegative power times the configured mass-per-joule coefficient. Fuel and
|
|
distance integrate from the fixed step. Engine-off RPM/fuel are zero. The
|
|
thermal approximation is a first-order response toward the greater of ambient
|
|
and configured equilibrium temperature, with a bounded additional target
|
|
increase from modeled power; it is not coolant-flow or component simulation.
|
|
All model state is checked for finiteness/domain violations and a failed run is
|
|
explicitly marked `Faulted`. An arithmetic/domain failure rolls state and
|
|
samples back to the last valid fixed-step snapshot before publishing the
|
|
terminal reason.
|
|
|
|
Configuration import converts unavailable profile/revision, missing module and
|
|
calibration-conflict references to the typed configuration-validation error
|
|
contract. Validation precedes catalog registration; a rejected import preserves
|
|
the selected configuration and any active run binding.
|
|
|
|
The ordered baseline scenario has 10 s warm idle, acceleration to 20.1168 m/s
|
|
(45 MPH) with a 60 s maximum, a full 300 s target-speed hold, braking to 0.1 m/s
|
|
with a 60 s maximum, and at least 10 s stationary return-idle. Headless stepping
|
|
uses virtual steps only. `RunScenarioAsync` has an optional real-time pacer;
|
|
0.25x-1000x changes delay scheduling only, not the numerical step. Start,
|
|
pause, resume, stop, reset, and explicit stopped/paused stepping are serialized.
|
|
Diagnostic reads never advance model state. The numerical test independently
|
|
checks the 650 +/- 5 rpm idle gate, 45 MPH <=60 s with shift activity, all 3,000
|
|
cruise samples with >=95% inside +/-0.44704 m/s, coupled cruise RPM relation,
|
|
braking/return-idle limits, finite/nonnegative monotonic fuel, and exact
|
|
same-input sampled-state reproducibility. Exact run outputs are recorded in
|
|
the Step-04 worker report.
|
|
|
|
Overall scenario progress is cumulative elapsed scenario time divided by total
|
|
configured phase duration; completed phase duration is retained across phase
|
|
transitions. Current-phase progress is elapsed time divided by that phase's
|
|
configured duration and is displayed separately. Both are bounded to `[0,1]`;
|
|
reset starts both at zero and successful completion sets both to one. A missed
|
|
phase target by its deadline ends in `Faulted` with the phase and reason
|
|
preserved. Faulted dynamic signal reads return protocol-v2 negative response
|
|
`DYNAMICS_RUN_FAULTED`, not a positive `Good` snapshot. The UI preserves the
|
|
failure notice and clears previously good telemetry rows so they are not
|
|
mistaken for a current healthy sample.
|
|
|
|
Each running controller owns one cancellable advancement task. Start/resume
|
|
performs the first fixed step and then waits on the configured pacer; pacing
|
|
changes delay only. Pause, stop, reset and dispose cancel and await that owner
|
|
before returning, so a pending delay cannot advance a stale session. The
|
|
simulation project exposes a narrow `IDynamicsPacer` seam for deterministic
|
|
controlled-scheduler tests; it is not a general clock framework. UI operations
|
|
also guard session/run generations after awaits. A stale open/reset/run result
|
|
is discarded and disposed rather than published into a later session.
|
|
|
|
Start and resume validate that no prior advancement owner remains active or is
|
|
settling before changing lifecycle state. If pause, stop or reset has cancelled
|
|
an owner but its cleanup has not completed, a concurrent start/resume is
|
|
rejected immediately with an explicit error and leaves lifecycle, model time,
|
|
step, progress, configuration and ownership unchanged. The caller can retry
|
|
after the cancelling operation completes. The command gate is not held while
|
|
waiting for runner cleanup, so the owner can finish its cleanup path.
|
|
|
|
## Static versus dynamic diagnostic providers
|
|
|
|
The existing `autoforge.simulation.synthetic` provider remains the static
|
|
protocol-v1 baseline, including its fixed 850 rpm engine signal, original fault
|
|
behavior and original tests. Dynamics is a separate
|
|
`autoforge.simulation.dynamics` factory requiring `OpenDynamicsAsync` and an
|
|
exact selected configuration; the static-open path cannot acquire dynamics
|
|
controls. It exposes only the configured engine and transmission endpoint map.
|
|
The engine and transmission telemetry are both snapshots from the same
|
|
thread-safe engine state. While paused/stopped, reads across modules preserve
|
|
the step/time; while the runner is active, each response advertises its actual
|
|
sample step/time rather than pretending multiple requests are simultaneous.
|
|
Each dynamic signal carries source module, unit, quality, `SYNTHETIC_DYNAMIC`
|
|
origin and model/config/run metadata. Diagnostic capture ticks remain separate
|
|
from the model clock. See [protocol v2](synthetic-diagnostics-v2.md) for wire
|
|
fields and strict validation.
|
|
|
|
The `/simulation` route requires explicit profile revision, dynamics provider
|
|
and configuration selection. User-triggered example creation/import does not
|
|
open or start a run. Controls and JSON interchange coordinate through
|
|
Application; the telemetry table calls the actual protocol client, not the
|
|
engine API. Values are synthetic behavior, not firmware, calibration, safe
|
|
tuning guidance, validated manufacturer prediction or physical vehicle data.
|
|
The route also hosts the shared configurable dashboard. It reads the same
|
|
session-bound v2 source and reports per-response model step/time separately from
|
|
diagnostic request ticks; polling and rendering do not advance the fixed-step
|
|
model. Scenario target speeds and decoded numeric telemetry use the shared
|
|
Imperial (US)/Metric display preference; each decoded row retains its exact
|
|
source value and unit beside the display projection. Missing/Unknown readings
|
|
are shown as `--`; invalid types for known numeric units are explicit display
|
|
errors, while the separate source column retains their raw value. Uncertain
|
|
quality stays visible, boolean `false` is not treated as missing, and
|
|
unsupported content remains unchanged with an unconverted notice. Scenario
|
|
definitions, configuration JSON, SI model state and fingerprints are unchanged.
|
|
Static trace payloads and configuration interchange are source data, not
|
|
converted output.
|
|
See the [live dashboard guide](live-dashboard.md) for mappings, preference
|
|
persistence/error handling, editor range policy and freshness contract.
|
|
|
|
## Reproducible faults and lifecycle
|
|
|
|
`VirtualModuleDefinition` accepts a validated fault map keyed by a defined
|
|
synthetic service, plus non-negative logical response latency. Fault modes are:
|
|
|
|
- `NoResponse`: no response payload arrives.
|
|
- Latency above the protocol deadline: explicit `Timeout`, no response payload.
|
|
- `MalformedResponse`: response bytes are retained but protocol decoding fails.
|
|
- `WrongCorrelation`: response does not match request correlation.
|
|
- `WrongIdentity`: identity reply names an unexpected module.
|
|
- `HoldUntilCancelled`: pending transport work completes only on request
|
|
cancellation or session close.
|
|
|
|
Fault maps are data, not random scheduling. The default truck definition
|
|
reproducibly demonstrates a missing transmission probe response; tests construct
|
|
other explicit vectors and assert their exact outcomes and trace records.
|
|
|
|
There is no physical/replay provider in this implementation. The Simulation
|
|
provider will reject unknown or incompatible profile revisions and target
|
|
selection does not automatically open an operational session. No simulation
|
|
state is persisted beyond the current process/session.
|