169 lines
8.3 KiB
Markdown
169 lines
8.3 KiB
Markdown
# 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:
|
|
|
|
1. `SyntheticDiagnosticProtocolClient` builds and encodes a request.
|
|
2. The encoded bytes cross `IDiagnosticTransport.SendAsync`.
|
|
3. 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.
|
|
4. The protocol client validates the response envelope/correlation and decodes
|
|
service data into typed results. Identity is compared with the exact selected
|
|
profile snapshot.
|
|
5. 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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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.
|