8.3 KiB
Synthetic diagnostics protocol v1
Purpose and limitations
Protocol v1 is a small, explicit JSON request/reply contract used only between the provider-neutral diagnostic protocol client and the in-process synthetic simulation transport. The frames are UTF-8 JSON. They are not CAN, ISO-TP, UDS, OBD-II, a manufacturer protocol, or a claim of vehicle compatibility. No physical transport or vehicle operation is implemented.
The actual capability path is:
SyntheticDiagnosticProtocolClientbuilds and encodes a request.- The encoded bytes cross
IDiagnosticTransport.SendAsync. - The simulation transport decodes the request, checks its bound session and profile/configuration, selects a configured virtual endpoint by address and service, and creates a response or explicit transport outcome.
- The protocol client validates the response envelope/correlation and decodes service data into typed results. Identity is compared with the exact selected profile snapshot.
- The exchange is added to that session's bounded trace with copied payloads and logical timing.
The application and UI never read the simulation module objects directly.
Request
The request contains protocol version, session/profile/configuration identity, correlation identifier, target address, service identifier, logical start tick and logical timeout:
{
"version": 1,
"sessionIdentifier": "diagnostic-session-000001",
"profileIdentifier": "autoforge.synthetic.test-truck",
"profileRevision": 1,
"configurationIdentifier": "profile:autoforge.synthetic.test-truck@revision:1",
"correlationIdentifier": "diagnostic-session-000001-000001",
"targetAddress": "10",
"service": "probe",
"logicalTimeTicks": 0,
"timeoutTicks": 5
}
All ten top-level fields shown are required on the wire. Protocol fields use
exact camelCase spelling; names are case-sensitive. The decoder rejects a
missing field rather than filling it from a C# initializer or primitive
default. An explicitly supplied logicalTimeTicks: 0 is valid. Unknown fields,
case variants and duplicate properties are rejected recursively before session
binding, endpoint selection or service dispatch. A malformed request receives
the transport's explicit no-response outcome; it does not dispatch a service,
and no response correlation is fabricated from ambiguous input. A complete
request with explicit version 2 remains distinguishable and receives the
typed UNSUPPORTED_VERSION negative response.
The address is a one-to-four digit hexadecimal text value. Module IDs are
separate diagnostic context and are never inferred from an address alone. The
current service identifiers are probe, read.identity, read.dtcs,
clear.dtcs and read.signals. These are AutoForge's synthetic service names,
not standardized vehicle commands.
Reply and failures
Every received reply includes version, session/configuration, correlation, target address, service, a success flag, optional error code/message and data. A positive example:
{
"version": 1,
"sessionIdentifier": "diagnostic-session-000001",
"configurationIdentifier": "profile:autoforge.synthetic.test-truck@revision:1",
"correlationIdentifier": "diagnostic-session-000001-000001",
"targetAddress": "10",
"service": "probe",
"success": true,
"errorCode": null,
"error": null,
"data": {
"moduleIdentifier": "module.engine.primary",
"implementedServices": ["probe", "read.identity", "read.dtcs", "clear.dtcs", "read.signals"]
}
}
A negative service reply uses success: false, a typed error code/message and
data: null; an unsupported operation is never represented as a successful
empty collection. Wrong version, session/configuration, correlation, address or
service is rejected. Malformed JSON or required fields produce
ProtocolError. A valid DTC reply with an empty codes array is distinct from
all failures.
Discovery records the validated probe and identity exchange as separate
results. A positive probe retains its validated module ID and immutable
advertised service list even if identity is later unavailable, negative,
malformed, mismatched, timed out or cancelled. If read.identity was not
advertised, the client does not send that unsupported request and records an
explicit not-attempted reason. A failed probe has no advertised services and
identity remains not attempted. The result exposes expected endpoint count,
validated positive probe count and profile-verified identity count separately.
Profile metadata never fills an absent runtime identity or grants permission.
The UI shows partial probe evidence, but identity-dependent read/clear actions
remain disabled until identity is validated against the selected profile.
The receiver requires every envelope field shown, exact camelCase spelling,
unique properties at every object level and no unknown fields. Positive replies
must carry an object data and null errorCode/error; negative replies must
carry nonblank errorCode/error and null data. Each interpreted service
object has its own exact required-field set. Identifiers/text must be nonblank
and trimmed; DTC codes, advertised services and signal identifiers are unique.
Probe replies must name the requested module and advertise only known, unique
v1 service tokens, including probe. Identity is compared with the selected
profile snapshot. Static-signal source/module and quality are validated; the
snapshot logical tick must equal the request start tick. Any invalid or
ambiguous response produces ProtocolError with no partial result value.
Signal value remains an explicit arbitrary JSON value, including null for
unknown; protocol envelope/service objects themselves reject unknown members.
No-response, timeout and cancellation are transport outcomes, not fabricated JSON replies. Their trace record has the immutable request bytes and no response payload. A configured no-response endpoint is not counted as a validated probe; an earlier successful probe remains positive in its own trace record even when the subsequent identity exchange fails.
An accepted clear.dtcs positive response is only an acknowledgement. The
Application clear-and-verify use case performs a fresh read.dtcs request and
reports verified success only when that valid response contains an empty code
set. A nonempty readback is retained as observed data and reported as a
verification failure; any failed/uncertain readback is not a verified clear.
This result describes in-memory Simulation state only; it is not a physical
write.
Logical timing and concurrency
The logical clock is injected per diagnostic session. Successful transport delivery advances it by deterministic configured response ticks; no wall-clock-based fault choice or random delay is used. A request includes a logical timeout of five ticks. A virtual latency greater than the deadline returns Timeout without a response. The protocol client serializes exchanges per session so correlation sequence, logical time and retained trace order stay consistent.
HoldUntilCancelled is a deterministic blocking fault released only by
cancellation or session close. No Thread.Sleep is used. The logical clock is
for diagnostics only; it is not the Step-04 dynamics/scenario clock.
Trace
Each session keeps at most 200 in-memory records. Every record contains session
identity (including exact target/profile/revision/configuration), module/address,
correlation, service, start/end logical ticks, copied request bytes, optional
copied response bytes, typed outcome, decoded summary and explicit error text.
The oldest entry is dropped at capacity and DroppedRecordCount increases.
The response is validated completely before positive result and trace commitment;
semantic probe failures therefore have one ProtocolError record with the
actual raw reply instead of a positive record followed by a contradictory
discovery result.
The trace is session-local, not persistent logging, telemetry recording or
replay. Closing the session releases the trace with its transport state.
Cancellation after a successful probe retains that phase's probe/service facts
and records cancellation only for the pending identity exchange; closing the
session suppresses stale UI updates and releases the active session results.
The UI renders decoded summaries and lets the user inspect raw UTF-8 request and response JSON. It labels synthetic operation results and never describes them as live vehicle capture.