uds_stack

The MicroVision UDS diagnostic stack: ISO 14229 and ISO 13400 protocol crates sharing one requirement set.

This documentation set holds the stack’s architecture and requirements. API documentation is generated by rustdoc and published separately; the two are joined by need IDs, which appear in Implements: and Verifies: annotations in the source.

• Architecture
  • Position in the stack
  • One message vocabulary
  • The dispatch pipeline
  • Service traits and identifiers
  • The client surface
  • The seams
  • What this crate does not own
  • Open questions
  • The organising rule
  • What the crate is for
  • The two roles
  • The set as a graph
  • All architecture elements
  • Derived architecture elements
• Requirements
  • Service interface
  • Timer model
  • Server session timer
  • Server response timing
  • Client response timing
  • Client session timer
  • Client request spacing
  • Client error handling
  • Open questions
  • Status of this set
  • All requirements
  • Outstanding integrity gap

The crates

Crate	Standard	ID prefix
uds_protocol	ISO 14229-1 message codec	not yet authored
uds_session	ISO 14229-2 session layer	UDSS_
uds_services	ISO 14229-1 clause 8 dispatch	UDSSVC_
simple_doip	ISO 13400-2 transport	not yet authored
uds_on_ip	ISO 14229-5 profile and mapping	not yet authored

A crate gets its prefix when it authors its first need, not before. An unauthored crate is not a gap in this set; it is a crate whose requirements have not been written.

Building

The documentation environment is managed by uv. The Python version is pinned, and the resolver will refuse an incompatible interpreter rather than fail at build time. --frozen refuses to re-resolve, so these are the same commands CI runs.

$ uv sync --frozen
$ just doctor     # checks for the one tool uv cannot pin
$ just html       # browsable, and how this set is meant to be read
$ just check-docs # the fast gate: policy checks, self-tests, needs build

Every diagram in this set is PlantUML, so the build needs the plantuml command on PATH – brew install plantuml, or the apt package of the same name. It is a Java program invoked as a subprocess, so it cannot live in uv.lock with everything else; just doctor is there because the failure without it is a Sphinx warning about a subprocess rather than anything resembling “install plantuml”.

The needs builder produces needs.json, the machine-readable export of this set. It is consumed through needs_external_needs against a committed snapshot, which is why it is not served from the published site. Its version key is the schema version set in conf.py – currently 0.1.0 – and not any crate’s version. Two crates happen to sit at 0.1.0 as well; that is a coincidence, and this number does not move when they do. It moves when the need types, the ID scheme, the required fields or the link types change, because that is what a consumer pinning to this key depends on.

Reading the set

Two authored need types appear here, and the distinction between them is load-bearing.

An architecture element (arch, <PREFIX>_ARCH_####) is a component, a seam, or a structural decision: what a piece of the stack is, what crosses its boundary, and who owns what on either side. It carries no integrity level, because it is not a claim with evidence behind it.

A requirement (llr, <PREFIX>_LLR_####) is a verifiable statement about behaviour, and carries a pair of integrity levels: integrity_level is what is currently substantiated by evidence, target_level is what it is expected to reach.

Both carry an origin, recording whether the need was transcribed from a standard or derived by us. Where it was transcribed, a source gives the clause, table or figure it came from. A derived need carries no source; it states its reasoning in a Rationale: paragraph instead.

That rule matters most in uds_services. Clause 8.7 fixes the negative response codes and the order the checks run in, but says nothing about trait design, associated types, or macros – so that crate has the highest derived fraction in the stack, and derived reasoning cannot be reconstructed after the fact. just summary reports the split per prefix on every run.

Needs are written to be read without the standard in hand. source records where a need came from, not what it means.

The diagrams come in two kinds, and the difference matters when you are deciding whether to trust one. A hand-drawn diagram is authored PlantUML: it can show things the needs do not model – call direction, message order, what crosses a seam – and it can fall out of step with the prose. A generated diagram is rendered by needflow from the elements and their links, so it cannot disagree with the set, and every node in one is a hyperlink to the element it stands for.

Relationship to the standards

Nothing here grants any right in the ISO standards these needs cite, which remain ISO’s. A source field records a clause reference so a reader holding the standard can check the transcription; it is not a reproduction of the clause.

On this page

• uds_stack
  • The crates
  • Building
  • Reading the set
  • Relationship to the standards