3.5. Diagnostic Tester¶
The Diagnostic Tester component provides the core functionality for communicating with vehicle ECUs using UDS (Unified Diagnostic Services) over DoIP (Diagnostics over IP). This document defines its architecture.
3.5.1. Startup Behavior¶
3.5.1.1. Startup Sequence¶
The CDA startup is orchestrated by the main application entry point, which coordinates initialization of all subsystems in a defined order to ensure proper dependency resolution and graceful degradation on partial failures. Component Initialization Order The startup sequence proceeds through the following phases:
Shutdown Signal Handling A shareable shutdown signal is created and propagated to all long-running tasks. This enables coordinated shutdown when receiving SIGTERM or Ctrl+C at any startup phase, including during database loading and DoIP initialization.
Startup Component Interaction¶ |
3.5.1.2. Database Loading¶
Diagnostic databases (MDD files) are loaded in parallel to minimize startup time, with careful handling of duplicates and failures to ensure robust operation. Note Database loading always occurs during startup, regardless of the initialization mode. Even when deferred initialization is configured, MDD files are loaded immediately so that the SOVD API can expose ECU metadata (names, capabilities) before communication is established. Only the DoIP gateway creation and variant detection are deferred. Parallel Loading Strategy The database loader discovers all chunk_size = file_count / (parallel_load_tasks + 1)
The number of parallel load tasks is configurable. Processing larger files first ensures optimal utilization of parallel workers, as smaller files naturally fill remaining capacity. Per-File Processing For each MDD file, the loader:
Duplicate ECU Handling When multiple MDD files define the same ECU name:
After loading, ECUs sharing the same logical address (from different database files with different ECU names) are identified and tracked for variant detection disambiguation. Health Status Integration When health monitoring is enabled (see Health Monitoring (arch~dt-health-monitoring)), a database health provider is registered with initial status “Starting”. After loading completes:
Failure Isolation Individual MDD file loading failures are logged but do not prevent other files from loading. The loader continues processing all discovered files regardless of individual failures. |
3.5.1.3. DoIP Gateway Initialization¶
The DoIP gateway establishes communication with vehicle DoIP entities through a discovery and connection establishment protocol defined in ISO 13400. Note When deferred initialization is configured (see Communication Initializatio... (arch~dt-deferred-initialization)), the entire DoIP gateway initialization described below is postponed until a trigger event occurs. When health monitoring is enabled, the health provider for the DoIP component remains in “Pending” state until initialization is triggered. Socket Creation A UDP socket is created and bound to the configured tester address and gateway port. The socket is configured with:
Vehicle Identification The gateway broadcasts a Vehicle Identification Request (VIR) to Subnet Filtering VAM responses are filtered based on the configured subnet mask. Only responses from IP addresses
within the tester’s subnet (determined by Gateway-to-ECU Mapping For each discovered gateway (identified by its logical address in the VAM), the system:
Spontaneous VAM Listener After initial discovery, a background task continuously listens for spontaneous VAM broadcasts. This handles scenarios where:
When a new VAM is received, the system establishes a connection (if not already connected) and triggers variant detection for the associated ECUs.
DoIP Gateway Discovery and Connection¶ |
3.5.1.4. Communication Initialization Mode¶
The CDA supports a configurable Dynamic Router Architecture The HTTP server is launched with a dynamic router that supports adding routes after the server has started. This enables:
``init_mode`` Values
OnDemand and Disabled always behave like WhenNotPersisted once triggered (at whichever scope applies), rather than offering their own Always/WhenNotPersisted choice, since these modes exist specifically to minimize vehicle network traffic until explicitly authorized.
WhenNotPersisted – Reconnect to a Persisted Gateway¶ Pre-initialization State While initialization is deferred (
Initialization Sequence Once triggered, initialization proceeds identically to the immediate initialization path (subject to
the Always/WhenNotPersisted distinction described above, and, for OnDemand, scoped to a
single gateway or all gateways depending on which trigger fired): DoIP gateway creation (broadcast
discovery or direct reconnect), TCP connection establishment, UDS manager creation, and variant
detection. Upon completion, SOVD routes are registered and, when health monitoring is enabled, health
status transitions to “Up” (for OnDemand’s single-ECU trigger, this refers to the routes/health of
the affected gateway only). The resulting topology is persisted as described in
ECU List Persistence (arch~dt-ecu-list-persistence), so that subsequent startups can reuse it (unless |
3.5.1.5. Health Monitoring¶
Health monitoring is an optional build-time feature that provides an HTTP endpoint for querying the aggregate and per-component health status of the CDA. Health status is only retrievable through the health endpoint when this feature is enabled at build time. Feature Enabled Behavior When the health feature is enabled:
Feature Disabled Behavior When the health feature is disabled at build time:
Component Health Providers When enabled, the following component health providers are registered:
Health Status Transitions
Component Health State Transitions¶ |
![@startuml
skinparam backgroundColor #FFFFFF
skinparam stateArrowThickness 2
[*] --> Pending : Component registered\n(initialization not yet started)
Pending --> Starting : Initialization begins
Starting --> Up : Initialization successful
Starting --> Failed : Initialization failed
state Pending {
}
state Starting {
}
state Up {
}
state Failed {
}
note right of Pending
Used for components whose initialization
is deferred (e.g., DoIP gateway when
deferred initialization is configured).
Pending and Starting both contribute to
an overall "Starting" aggregate status.
end note
@enduml](../_images/plantuml-7a2532ed7f4e18ca7fcc5fd545d9eba27eb01a3b.png)
3.5.2. ECU Detection and Variant Detection¶
3.5.2.1. ECU Discovery¶
ECU discovery establishes the mapping between diagnostic database definitions (MDD files) and physical DoIP communication endpoints. Database-to-Gateway Mapping During database loading, each ECU’s logical gateway address is extracted from the MDD. A mapping structure is built that associates each gateway logical address with the list of ECU logical addresses accessible through it. VAM Matching When a VAM is received, its logical address is matched against the ECU addresses from loaded databases. A match indicates that the ECU defined in the MDD is physically present and reachable through the responding gateway. Connection Association For discovered ECUs, the system maintains:
This structure enables routing diagnostic messages to the correct gateway and ECU. ECU Name Mapping A secondary mapping tracks ECU names to logical addresses for supporting SOVD API requests that reference ECUs by name rather than address. This associates each gateway logical address with the list of ECU names accessible through it. Duplicate Address Detection ECUs sharing the same logical address (from different MDD files with different ECU names) are tracked as potential duplicates. Each ECU manager stores references to other ECU names that share the same address. Variant detection determines which ECU definition is correct for the physical ECU. |
3.5.2.2. Variant Detection¶
Variant detection identifies the correct ECU software variant from multiple possible definitions by querying the ECU and matching responses against defined patterns. Detection Request Channel A message channel connects the DoIP gateway to the UDS manager for variant detection coordination. When a VAM is received (either during startup or from spontaneous announcements), the gateway sends a list of ECU names requiring variant detection through this channel. Asynchronous Detection Variant detection runs asynchronously to avoid blocking startup. A dedicated task receives ECU names from the channel and spawns individual detection tasks per ECU. This enables parallel variant detection across multiple ECUs. Detection Process For each ECU requiring variant detection:
Duplicate Resolution When multiple ECU definitions share the same logical address, variant detection determines which definition matches the physical ECU. The matching ECU transitions to Online state; non-matching ECUs with the same address transition to Duplicate state and their databases are effectively disabled. Fallback Behavior When variant detection fails to find a matching pattern:
|
3.5.2.3. ECU States¶
ECU state management tracks the lifecycle of each ECU from registration through variant detection and ongoing communication. States The following states are maintained:
The distinction between Offline and Disconnected reflects whether the ECU has ever been successfully communicated with. An ECU that fails its first contact attempt transitions to Offline; an ECU that was previously Online, NoVariantDetected, Disconnected, or AssumedOnline and loses (or fails to establish) communication transitions to Disconnected – since, in all of these cases, the ECU is known to have been reachable at some point (either in the current session, or, for AssumedOnline, according to the persisted topology from a previous session). External Representation The AssumedOnline state is an internal-only distinction. Externally, via the SOVD API (see
Components Entity Collection (arch~sovd-api-components-entity-collection) and
Vehicle Topology Plugin - R... (arch~plugin-vehicle-topology-retrieval)), an ECU in the AssumedOnline state is reported with
connectivity state State Storage ECU state is maintained within the ECU manager structure, which wraps the diagnostic database and adds runtime state information. The state is queryable through the SOVD API component endpoints. In addition to the state enum, each ECU manager stores a State Transitions State transitions are triggered by:
Concurrent Access ECU state is protected by a read-write lock to enable concurrent read access from multiple API handlers while ensuring exclusive write access during state transitions. The database map associates each ECU name with its concurrency-protected state manager. State Query The SOVD API exposes ECU state through the component collection endpoint. Clients can
query individual ECU status or list all ECUs with their current states. The state (with AssumedOnline
mapped to Online) and the |
3.5.3. ECU List Persistence¶
3.5.3.1. ECU List Persistence¶
The detected ECU/gateway topology is persisted on top of the generic Persistence API (see Persistence API (arch~system-persistence-api)), so that the CDA does not have to unconditionally rediscover it on every startup. Enable/Disable Configuration A configuration flag ( Bucket Layout A dedicated Bucket (e.g.
ECU Topology Persistence¶ Write Timing The persisted topology is written after a detection run completes – both after the initial startup
detection (unless deferred/disabled without a trigger having fired yet, see
Communication Initializatio... (arch~dt-deferred-initialization)) and after a Read Timing The persisted topology is read once, early during the Vehicle Data Loading Phase of
Startup Sequence (arch~dt-startup-sequence), before deciding whether to perform a full broadcast discovery or reuse
the persisted data (relevant for When ECUs are registered from a persisted topology, an ECU whose persisted state was Online is
registered in the AssumedOnline state (see ECU States (arch~dt-ecu-states)), with its |
3.5.3.2. ECU List Persistence - Shutdown Update¶
The Instead, the in-memory
last_seen Persistence at Shutdown¶ Rationale Deferring the persistence of |
3.5.4. Error Handling¶
The CDA implements graceful degradation during startup to maximize availability even when individual components fail. Error Type Hierarchy Application errors are categorized through a structured error type hierarchy. The following error types are relevant during startup:
Additionally, the following error types may occur during runtime after startup has completed:
Component Health Integration When health monitoring is enabled (see Health Monitoring (arch~dt-health-monitoring)), component failures are reflected through health provider status transitions. Health providers and their status transitions are defined in the health monitoring architecture. Graceful Degradation Behaviors
Shutdown Handling Shutdown signals (SIGTERM, Ctrl+C) are handled gracefully at any startup phase:
All shutdown paths ensure resources are properly released through structured cleanup and tracing guards that flush logs on drop. |