1. About this document¶

This chapter includes information about the documentation itself, including purpose, terminology used throughout the document, and technical information about the document structure.

1.1. Introduction¶

The Classic Diagnostics Adapters purpose is to provide an SOVD API for legacy ECUs. Communication with legacy ECUs is facilitated by utilizing UDS. It must support DoIP, and may support additional transports in the future.

This documentation also utilizes sphinx-needs for traceability between requirements, architecture, design, implementation and tests.

1.1.1. DoIP Discovery and Connection Establishment¶

DoIP (Diagnostics over IP, ISO 13400) is the transport protocol used by the CDA to communicate with vehicle ECUs. Before diagnostic messages can be exchanged, two phases must complete: discovery and connection establishment.

1.1.1.1. Discovery¶

Discovery uses UDP broadcast to locate DoIP entities (gateways) on the network. The CDA sends a Vehicle Identification Request (VIR) to the broadcast address on the DoIP port (13400). Each DoIP entity that receives the request responds with a Vehicle Announcement Message (VAM) containing its IP address, logical address, and vehicle identification data (VIN, EID, GID). Responses are filtered to only accept entities within the same subnet as the CDA. After initial discovery, a background listener continues to receive spontaneous VAMs so that gateways coming online later are detected automatically.

@startuml
skinparam backgroundColor #FFFFFF

participant "CDA" as CDA
participant "Network\n(UDP broadcast)" as NET
participant "DoIP Entity" as GW

CDA -> NET: Vehicle Identification Request\n(broadcast, port 13400)
NET -> GW: VIR
GW --> CDA: Vehicle Announcement Message\n(IP, logical address, VIN)
CDA -> CDA: Filter by subnet,\nmatch to known ECU databases
@enduml — DoIP Discovery (simplified)¶

1.1.1.2. Connection Establishment¶

Once a DoIP entity is discovered, the CDA establishes a TCP connection to it and performs routing activation to register itself as a diagnostic tester. Only after successful routing activation can UDS diagnostic messages be exchanged. If the entity requires an encrypted connection, the CDA transparently falls back to TLS on port 3496 and repeats the routing activation over the secured channel.

@startuml
skinparam backgroundColor #FFFFFF

participant "CDA" as CDA
participant "DoIP Entity" as GW

CDA -> GW: TCP connect (port 13400)
GW --> CDA: TCP connected

CDA -> GW: Routing Activation Request\n(tester logical address)

alt Activation successful
GW --> CDA: Routing Activation Response\n[SuccessfullyActivated]
note right of CDA: Ready for\ndiagnostic messages
else TLS required
GW --> CDA: Routing Activation Response\n[TLS required]
CDA -> GW: TCP connect (TLS port 3496)
CDA <-> GW: TLS handshake
CDA -> GW: Routing Activation Request
GW --> CDA: Routing Activation Response\n[SuccessfullyActivated]
note right of CDA: Ready for\ndiagnostic messages (TLS)
end
@enduml — DoIP Connection Establishment (simplified)¶

For a detailed description of the DoIP communication layer including message framing, communication parameters, error handling, and alive-check behaviour, see the DoIP Communication section in the Architecture.

1.1.2. UDS Diagnostic Communication¶

UDS (Unified Diagnostic Services, ISO 14229) is the application-layer protocol used to interact with ECUs. It defines a set of services, each identified by a Service Identifier (SID), that allow a tester to read data, write configuration, control ECU functions, and manage diagnostic sessions. The CDA acts as the tester, translating SOVD API calls into UDS requests and forwarding them over the DoIP transport.

1.1.2.1. Data-Driven Approach via MDD¶

The CDA uses a data-driven approach: all knowledge about ECUs – their logical addresses, supported services, data identifiers, routines, communication timing parameters, and session configuration – is loaded at runtime from MDD (Marvelous Diagnostic Description) files. These files are the diagnostic description database for the vehicle and contain the full definition of what each ECU supports.

This means the CDA itself contains no hard-coded ECU knowledge. Instead it reads the MDD files on startup and configures all communication parameters (timeouts, retry counts, tester present behavior, addressing) per ECU from those files. Adding support for a new ECU or updating its diagnostic description requires only a new or updated MDD file – no code changes.

A client (e.g. a diagnostic tool or test script) communicates with the CDA exclusively through the SOVD REST API using JSON over HTTP. The CDA uses the MDD data to translate each incoming JSON request into the appropriate UDS service call and returns the ECU’s response as a JSON reply – the client never deals with raw UDS bytes directly.

@startuml
skinparam backgroundColor #FFFFFF

participant "Client" as Client
participant "CDA" as CDA
participant "MDD Files" as MDD
participant "ECU" as ECU

CDA -> MDD: Load diagnostic description\n(logical addresses, DIDs, routines,\nCOM parameters)
MDD --> CDA: ECU descriptors + COM parameters

note right of CDA: All subsequent communication\nis parameterized from the MDD data\n(timeouts, retry counts, addresses, ...)

Client -> CDA: SOVD REST request\n(JSON over HTTP)
CDA -> ECU: UDS request (built from MDD knowledge)
ECU --> CDA: UDS response
CDA --> Client: SOVD REST response\n(JSON over HTTP)
@enduml — MDD-driven ECU configuration (simplified)¶

1.1.2.2. Essential UDS Service Identifiers¶

The table below lists the UDS services most relevant to the CDA’s operation. Each service is invoked by sending a request frame whose first byte is the SID; a positive response carries SID + 0x40 as its first byte.

Essential UDS Service Identifiers¶
SID	Service	Purpose
`0x10`	DiagnosticSessionControl	Switch the ECU into a specific diagnostic session (e.g., default, extended, programming). Many services are only available in non-default sessions.
`0x11`	ECUReset	Trigger a hard or soft reset of the ECU.
`0x14`	ClearDiagnosticInformation	Erase stored Diagnostic Trouble Codes (DTCs) from ECU memory.
`0x19`	ReadDTCInformation	Read Diagnostic Trouble Codes and their associated status from the ECU.
`0x22`	ReadDataByIdentifier	Read one or more data values referenced by a 2-byte Data Identifier (DID), such as sensor readings, calibration values, or version strings.
`0x27`	SecurityAccess	Authenticate the tester to unlock ECU functions that require elevated access (seed/key challenge-response).
`0x2E`	WriteDataByIdentifier	Write a value to a DID, such as updating configuration data or calibration parameters.
`0x31`	RoutineControl	Start, stop, or request the result of a named routine on the ECU (identified by a 2-byte Routine Identifier, RID).
`0x34`	RequestDownload	Initiate a data download (flash programming) transfer from the tester to the ECU.
`0x35`	RequestUpload	Initiate a data upload transfer from the ECU to the tester.
`0x36`	TransferData	Transfer a data block as part of an ongoing download or upload sequence.
`0x37`	RequestTransferExit	Conclude a data transfer sequence.
`0x3E`	TesterPresent	Keep the current non-default diagnostic session alive. The CDA sends this periodically while a diagnostic lock is held so the ECU does not time out the session.

1.1.2.3. UDS Request-Response Flow¶

Every UDS exchange follows the same basic pattern: the CDA sends a request frame (SID + payload), the DoIP gateway acknowledges receipt at the transport layer, and the ECU eventually replies with either a positive response (SID + 0x40) or a negative response (0x7F + SID + NRC). Certain Negative Response Codes (NRCs) signal transient conditions – for example, NRC 0x78 (Response Pending) means the ECU needs more time – and the CDA handles these automatically according to configurable policies sourced from the MDD files.

@startuml
skinparam backgroundColor #FFFFFF

participant "CDA" as CDA
participant "DoIP Gateway" as GW
participant "ECU" as ECU

CDA -> GW: UDS Request\n[SID + payload]
GW --> CDA: DoIP ACK
GW -> ECU: Forward request

alt Positive response
ECU --> GW: [SID+0x40 + data]
GW --> CDA: UDS Response
note right of CDA: Success
else Negative response
ECU --> GW: [0x7F, SID, NRC]
GW --> CDA: UDS Negative Response
note right of CDA: Error or retry\ndepending on NRC
else Response pending (NRC 0x78)
ECU --> GW: [0x7F, SID, 0x78]
GW --> CDA: ResponsePending
note right of CDA: Wait with extended\ntimeout, keep listening
ECU --> GW: Final response
GW --> CDA: UDS Response
end
@enduml — UDS request-response (simplified)¶

For a detailed description of the UDS communication layer including NRC handling policies, tester present behavior, functional group communication, and all communication parameters, see the UDS Communication section in the Architecture.

1.2. Terminology¶

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

1.3. Conventions¶

1.3.1. Sections¶

Section headers (ref) are created by underlining (and optionally overlining) the section title with a punctuation character, at least as long as the text:

# with overline, for components (e.g. classic diagnostic adapter, odx-converter)
* with overline, for parts (about, requirements, architecture, design, implementation, tests)
= for chapters within parts
- for sections within chapters
^ for subsections
" for subsubsections
~ for subsubsubsections

1.4. Traceability¶

Traceability in software development refers to the ability to link various artifacts and components of a software project throughout its lifecycle. This includes requirements, architecture, design documents, code and tests.

In this project, traceability is achieved through the use of sphinx-needs tools.

1.5. Conventions¶

1.5.1. Types¶

Need Types and ID Patterns¶
Need Type	Description	ID Pattern
req	Software Requirement	`req~<short-description>`
arch	Software Architecture	`arch~<short-description>`
impl	Implementation	`impl~<short-description>`
dimpl	Detailed Design & Implementation	`dimpl~<short-description>`
dsgn	Detailed Design	`dsgn~<short-description>`
test	Unit Test	`test~<short-description>`
itest	Integration Test	`itest~<short-description>`

Short description must only contain letters, numbers, and hyphens.

Generally speaking every requirement should be traced through architecture, design, implementation and tests. The design and implementation can be combined if desired. In trivial cases, it is acceptable to skip architecture and/or design.

Rationale

Combining design and implementation reduces overhead, and is acceptable when the design is straightforward, and it’s easier to show the design in code comments than in separate documents.

1.5.2. Properties¶

This section documents the metadata properties used on sphinx-needs items to support Automotive SPICE (ASPICE) process compliance. These properties enable consistent classification, maturity tracking, and review workflows across all documentation artifacts.

1.5.2.1. Status¶

The :status: option tracks the maturity of each documentation item through its lifecycle. It applies to all need types (req, arch, dsgn, impl, dimpl, test, itest).

Allowed Status Values¶
Status	Description	Applies To
`draft`	Item is being written or is incomplete. Content may change significantly. This is the default status for newly created items.	All need types
`valid`	Item has been reviewed and is considered correct and complete. Content accurately reflects the intended behavior or design.	All need types
`approved`	Item has been formally approved by a reviewer or stakeholder. Content is frozen and may only change through a formal change request.	All need types
`rejected`	Item has been reviewed and rejected. The item needs rework before it can be accepted.	All need types
`obsolete`	Item is no longer applicable. It is retained for historical reference but should not be relied upon.	All need types

Items without an explicit :status: should be treated as draft.

1.5.2.2. Lifecycle¶

The typical status progression for an item is:

draft --> valid --> approved

Items may transition to rejected from draft or valid during review. Items may transition to obsolete from any status when they are superseded or no longer needed.

Usage Example

.. req:: Example Requirement
    :id: req~example
    :status: draft

    The system must do something.

1.5.3. Requirement Type¶

The :type: option classifies requirements by their nature. This is primarily relevant for req needs, but may optionally be applied to arch and dsgn items for additional classification.

Allowed Requirement Type Values¶
Type	Description
`functional`	Describes a behavior or capability the system must provide. Functional requirements define what the system does in response to inputs or conditions.
`non-functional`	Describes a quality attribute such as performance, reliability, availability, security, or maintainability. Non-functional requirements define how well the system performs.
`interface`	Describes an external interface or API contract. Interface requirements define the boundaries and communication protocols between the system and external entities.
`constraint`	Describes a design or implementation constraint imposed by the environment, standards, or organizational policies. Constraints limit the solution space without describing system behavior.

Usage Example

.. req:: HTTP-Server
    :id: req~sovd-api-http-server
    :status: valid
    :type: functional

    The CDA must provide an HTTP- or HTTPS-server.

1.5.3.1. Code¶

Code can be added to the traceability by utilizing sphinx-codelinks. The short format in a comment is as follows:

[[ <ID of the need>, <title>, <type>, <links> ]]

One-Line Example:

/// [[ dimpl~sovd.api.https.certificates, Handle HTTPS Certificates, dimpl, test~sovd.api.https.certificates ]]
/// description of the function
fn test {
    ...
}

Note

type and links are optional, if left empty, type will be dimpl

multi-line definitions are not supported at the time of writing by the src-trace directive.

1.5.4. Overviews¶

Software Requirements

Software Requirements overview¶
ID	Title	Status
req~doip-alive-check	Alive Check	draft
req~doip-communication-parameters	DoIP Communication Parameters	draft
req~doip-connection-management	DoIP Connection Management	draft
req~doip-diagnostic-message	Diagnostic Message Exchange	draft
req~doip-error-handling	DoIP Error Handling	draft
req~doip-message-framing	DoIP Message Framing	draft
req~doip-protocol-versions	DoIP Protocol Version Support	draft
req~doip-routing-activation	Routing Activation	draft
req~doip-tls	DoIP TLS Communication	draft
req~doip-vehicle-identification	Vehicle Identification	draft
req~dt-database-loading	Database Loading	draft
req~dt-deferred-initialization	Deferred Initialization	draft
req~dt-doip-gateway-init	DoIP Gateway Initialization	draft
req~dt-ecu-discovery	ECU Discovery	draft
req~dt-ecu-states	ECU States	draft
req~dt-error-handling	Startup Error Handling	draft
req~dt-startup-sequence	Startup Sequence	draft
req~dt-variant-detection	Variant Detection	draft
req~plugin-diagnostic-database-update	Diagnostic Database Update Plugin	draft
req~plugin-diagnostic-database-update-authentication	Diagnostic Database Update Plugin - Authentication	draft
req~plugin-diagnostic-database-update-downgrade-protection	Diagnostic Database Update Plugin - Downgrade Protection	draft
req~plugin-diagnostic-database-update-safety	Diagnostic Database Update Plugin - Safety	draft
req~plugin-diagnostic-database-update-verification	Diagnostic Database Update Plugin - Verification	draft
req~plugin-dlt-logging	DLT Logging	draft
req~plugin-dlt-logging-context-identification	DLT Logging - Context Identification	draft
req~plugin-dlt-logging-feature-gate	DLT Logging - Compile-Time Feature Gate	draft
req~plugin-dlt-logging-log-level-mapping	DLT Logging - Log Level Mapping	draft
req~plugin-dlt-logging-runtime-configuration	DLT Logging - Runtime Configuration	draft
req~sovd-api-bytefield-as-hex	Data Type A_BYTEFIELD as Hex	draft
req~sovd-api-comparams	Communication Parameters API	draft
req~sovd-api-component-sdgsd	Component SDG/SDs	draft
req~sovd-api-components-entity-collection	Components Entity Collection	draft
req~sovd-api-data-types-mapping-iso17978	Entity Data Types	draft
req~sovd-api-ecu-variant-detection	Explicit ECU Variant Detection	draft
req~sovd-api-faults-endpoint	Faults Endpoint	draft
req~sovd-api-flashing	Flash API	draft
req~sovd-api-flashing-security	Flash API - Data Source Restriction	draft
req~sovd-api-functional-communication	Functional Communication	draft
req~sovd-api-health-endpoint	Health Monitoring Endpoint	draft
req~sovd-api-http-server	HTTP-Server	draft
req~sovd-api-http-server-port	HTTP-Server-Port	draft
req~sovd-api-https-server-configuration	HTTPS-Server configuration	draft
req~sovd-api-mdd-embedded-files	MDD Embedded files	draft
req~sovd-api-octet-stream-support	Support for mimetype application/octet-stream	draft
req~sovd-api-openapi-documentation	OpenAPI Documentation	draft
req~sovd-api-openapi-schema	OpenAPI Schema	draft
req~sovd-api-operations-handling	Operations Handling	draft
req~sovd-api-routine-operation-out-of-order	Support for non-standard operation order	draft
req~sovd-api-standalone-openapi-generator	Standalone OpenAPI Generator	draft
req~sovd-api-standardized-resource-collection-mapping	Standardized Resource Collection Mapping	draft
req~sovd-api-vehicle-level-operations	Vehicle Level Operations	draft
req~sovd-api-version-endpoint	Version Data Endpoint	draft
req~sovd-api-version-info-endpoint	Version Info Endpoint	draft
req~sovd-api-version-registration-function	Version Registration Function	draft
req~system-default-local-file-system-storage-access	Local File System Storage Access Implementation	draft
req~system-default-redb-persistence-provider	Default redb Persistence Provider	draft
req~system-persistence-api	Persistence API	draft
req~system-sd-notify-watchdog-integration	Systemd Watchdog Integration	draft
req~system-storage-access-abstraction	Storage Access Abstraction	draft
req~uds-communication-parameters	The CDA must support configuration of UDS communication as defined in the following table.	draft
req~uds-functional-communication	UDS Functional Communication	draft
req~uds-nrc-handling	UDS Negative Response Code Handling	draft
req~uds-request-response	UDS Request-Response Flow	draft
req~uds-tester-present	UDS Tester Present	draft

Software Architecture

Software Architecture overview¶
ID	Title	Status
arch~doip-alive-check	Alive Check	draft
arch~doip-communication-parameters	DoIP Communication Parameters	draft
arch~doip-connection-establishment	DoIP Connection Establishment	draft
arch~doip-connection-management	DoIP Connection Management	draft
arch~doip-diagnostic-message	Diagnostic Message Exchange	draft
arch~doip-error-handling	DoIP Error Handling	draft
arch~doip-message-framing	DoIP Message Framing	draft
arch~doip-protocol-versions	DoIP Protocol Version Support	draft
arch~doip-routing-activation	Routing Activation	draft
arch~doip-tls	TLS Connection Support	draft
arch~doip-vehicle-identification	Vehicle Identification	draft
arch~dt-database-loading	Database Loading	draft
arch~dt-deferred-initialization	Deferred Initialization	draft
arch~dt-doip-gateway-init	DoIP Gateway Initialization	draft
arch~dt-ecu-discovery	ECU Discovery	draft
arch~dt-ecu-states	ECU States	draft
arch~dt-error-handling	Startup Error Handling	draft
arch~dt-health-monitoring	Health Monitoring	draft
arch~dt-startup-sequence	Startup Sequence	draft
arch~dt-variant-detection	Variant Detection	draft
arch~functional-communication-api	Functional Communication API	draft
arch~functional-communication-data	Functional Communication - Data	draft
arch~functional-communication-dd-configuration	Diagnostic description & Configuration	draft
arch~functional-communication-locks	Functional Communication ECU-Lock behavior	draft
arch~functional-communication-modes	Functional Communication - Modes	draft
arch~functional-communication-operations	Functional Communication - Operations	draft
arch~plugin-diagnostic-database-update	Diagnostic Database Update Plugin	draft
arch~plugin-dlt-logging	DLT Logging	draft
arch~plugin-dlt-logging-configuration	DLT Logging - Configuration	draft
arch~plugin-dlt-logging-context-annotation	DLT Logging - Context Annotation	draft
arch~sovd-api-authentication-modes	Authentication Endpoints	draft
arch~sovd-api-bulk-data	Bulk-Data Endpoints	draft
arch~sovd-api-communication-control-modes	Communication Control Endpoints	draft
arch~sovd-api-comparams	Communication Parameters API	draft
arch~sovd-api-comparams-without-lock	Retrieve Communication Parameters without Lock	draft
arch~sovd-api-component-sdgsd	Component SDG/SDs	draft
arch~sovd-api-components-entity-collection	Components Entity Collection	draft
arch~sovd-api-configuration-resources	Configuration Resources	draft
arch~sovd-api-data-identifier-categories	Data Identifier Categories	draft
arch~sovd-api-data-resources	Data Resources	draft
arch~sovd-api-data-types-mapping-iso17978	ODX to JSON data type mapping	draft
arch~sovd-api-dtc-setting-modes	DTC Setting Endpoints	draft
arch~sovd-api-ecu-resource-collection	ECU Resource Collection	draft
arch~sovd-api-ecu-variant-detection	ECU Variant Detection via SOVD-API	draft
arch~sovd-api-faults-endpoint	Faults endpoint	draft
arch~sovd-api-flash-data-transfer	Flash data transfer	draft
arch~sovd-api-flash-file-management	Management of flash files	draft
arch~sovd-api-flash-folder-configuration	Flash folder configuration	draft
arch~sovd-api-http-server	SOVD-API over HTTP	draft
arch~sovd-api-mdd-embedded-files	MDD Embedded Files API	draft
arch~sovd-api-operations-handling	Synchronous and Asynchronous Operations	draft
arch~sovd-api-security-access-modes	Security Access Endpoints	draft
arch~sovd-api-session-management	Session Endpoints	draft
arch~sovd-api-single-ecu-jobs	Single ECU Jobs Extension	draft
arch~sovd-api-standardized-resource-collection-mapping	Standardized Resource Collection Mapping	draft
arch~sovd-api-version-registration-function	API Version Endpoint Registration Function	draft
arch~system-default-redb-persistence-provider	Default redb Persistence Provider	draft
arch~system-persistence-api	Persistence API	draft
arch~system-sd-notify-watchdog-integration	Systemd Watchdog Integration	draft
arch~system-storage-access-abstraction	Storage Access API	draft
arch~uds-communication-parameters	UDS Communication Parameters	draft
arch~uds-functional-communication	UDS Functional Communication	draft
arch~uds-nrc-handling	UDS NRC Handling	draft
arch~uds-request-response	UDS Request-Response Flow	draft
arch~uds-tester-present	UDS Tester Present	draft

Detailed Design

Detailed Design¶
ID	Title	Status
dimpl~sovd-api-http-server	Starts HTTP Server
dimpl~sovd-api-version-endpoint	Register Version Endpoint
dimpl~system-sd-notify-watchdog-integration	Systemd Watchdog Integration
itest~sovd-api-version-endpoint	Version Endpoint Integration Test
test~system-sd-notify-watchdog-integration	Systemd Watchdog Health Aggregation Tests

Implementation

Implementation¶
ID	Title	Status
dimpl~sovd-api-http-server	Starts HTTP Server
dimpl~sovd-api-version-endpoint	Register Version Endpoint
dimpl~system-sd-notify-watchdog-integration	Systemd Watchdog Integration
itest~sovd-api-version-endpoint	Version Endpoint Integration Test
test~system-sd-notify-watchdog-integration	Systemd Watchdog Health Aggregation Tests

Unit Tests

No needs passed the filters

Integration Tests