3.3.11.2. Functional communication

Software Architecture: Diagnostic description & Configuration arch~sovd-api-functional-communication-dd-configuration
status: draft
links incoming: req~sovd-api-functional-communication

Information about the available functional groups, the available services in those groups, and their communication parameters must be provided in a separate diagnostic description.

The diagnostic description’s MDD filename, in which the information for functional communication is contained, must be configurable. When no file is configured, functional communication is not available.

A configuration option in the CDA can further filter the available functional groups from the diagnostic description.

Rationale

Extracting a standardized resource collection for functional communication from individual ECU descriptions is challenging and non-transparent when extracting common functional services from all ECU files. Therefore, we chose to do this via a separate diagnostic description file.

This also follows the general pattern of one MDD file to an available standardized resource collection.

3.3.11.2.1. API

Software Architecture: Functional Communication API arch~sovd-api-functional-communication-api
status: draft
links outgoing: arch~sovd-api-functional-communication-locks, arch~sovd-api-functional-communication-data, arch~sovd-api-functional-communication-operations, arch~sovd-api-functional-communication-modes

Functional group functionality - if available - must be available in the /functions/functionalgroups/{group-name} path.

Within that path, a standardized resource collection (chapter 5.4.2 in ISO/DIS 17978-3) must be available, with the linked semantics.

' SPDX-FileCopyrightText: 2026 Copyright (c) Contributors to the Eclipse Foundation ' ' See the NOTICE file(s) distributed with this work for additional ' information regarding copyright ownership. ' ' This program and the accompanying materials are made available under the ' terms of the Apache License Version 2.0 which is available at ' https://www.apache.org/licenses/LICENSE-2.0 ' ' SPDX-License-Identifier: Apache-2.0 @startuml title Functional Communication API -- Overview participant Client participant "HTTP Server\n(Axum)" as HTTP participant "Security\nMiddleware" as SEC participant "Functional\nComm Handler" as HANDLER participant "Diagnostic\nKernel" as DIAG Client -> HTTP : GET /functions/functionalgroups activate HTTP HTTP -> SEC : authenticate & authorize activate SEC SEC -> HTTP : OK deactivate SEC HTTP -> HANDLER : route to functional comm handler activate HANDLER HANDLER -> DIAG : list functional groups\n(from dedicated MDD file) activate DIAG DIAG -> HANDLER : available functional groups deactivate DIAG HANDLER -> HTTP : JSON body deactivate HANDLER HTTP -> Client : HTTP 200 OK\n{ "items": [ { "id": "<group-name>", ... }, ... ] } deactivate HTTP @enduml

Software Architecture: Functional Communication ECU-Lock behavior arch~sovd-api-functional-communication-locks
status: draft
links incoming: arch~sovd-api-functional-communication-api

Locking a functional group will start sending functional Tester Presents to the functional DoIP addresses of all DoIP Entities, and stop sending non-functional Tester Presents.

Component Lock Takeover

For every ECU covered by the functional group on which the same client already holds a component (ECU) lock, that component lock’s physical Tester Present is stopped once the functional group lock’s acquisition commits. The component lock itself is not released: it remains valid and renewable on its own, but it no longer runs its own Tester Present or responds independently to release; the functional group lock now owns both.

Releasing, expiring, or preempting the functional group lock also releases every component lock it replaced the Tester Present of, running each one’s own cleanup (Tester Present stop, session and security access reset) as well as its own. Releasing or expiring one of those component locks on its own, while the functional group lock still covers that ECU, runs no cleanup at all; the functional group lock still owns the ECU until it is itself released.

A component lock acquired while the same client already holds a functional group lock covering that ECU starts no physical Tester Present of its own, for the same reason.

' SPDX-FileCopyrightText: 2026 Copyright (c) Contributors to the Eclipse Foundation ' ' See the NOTICE file(s) distributed with this work for additional ' information regarding copyright ownership. ' ' This program and the accompanying materials are made available under the ' terms of the Apache License Version 2.0 which is available at ' https://www.apache.org/licenses/LICENSE-2.0 ' ' SPDX-License-Identifier: Apache-2.0 @startuml title Functional Communication -- ECU-Lock participant Client participant "HTTP Server\n(Axum)" as HTTP participant "Security\nMiddleware" as SEC participant "Functional\nComm Handler" as HANDLER participant "Lock Manager" as LOCK participant "UDS / DoIP" as COMM participant "ECUs\n(functional)" as ECUS == Lock functional group == Client -> HTTP : PUT /functions/functionalgroups/{group}/lock activate HTTP HTTP -> SEC : authenticate & authorize activate SEC SEC -> HTTP : OK deactivate SEC HTTP -> HANDLER : route to functional comm handler activate HANDLER HANDLER -> LOCK : lock functional group activate LOCK LOCK -> LOCK : stop non-functional\nTester Presents LOCK -> LOCK : take over covered component\nlocks' physical Tester Present LOCK -> COMM : start functional Tester Presents\nto all DoIP entities activate COMM COMM -> ECUS : functional TesterPresent (3E) deactivate COMM LOCK -> HANDLER : lock acquired deactivate LOCK HANDLER -> HTTP : success deactivate HANDLER HTTP -> Client : HTTP 200 OK deactivate HTTP == Unlock functional group == Client -> HTTP : DELETE /functions/functionalgroups/{group}/lock activate HTTP HTTP -> SEC : authenticate & authorize activate SEC SEC -> HTTP : OK deactivate SEC HTTP -> HANDLER : route to functional comm handler activate HANDLER HANDLER -> LOCK : unlock functional group activate LOCK LOCK -> LOCK : stop functional Tester Presents LOCK -> LOCK : release component locks replaced\n(with their own cleanup) LOCK -> HANDLER : lock released deactivate LOCK HANDLER -> HTTP : success deactivate HANDLER HTTP -> Client : HTTP 200 OK deactivate HTTP @enduml

Software Architecture: Functional Communication - Data arch~sovd-api-functional-communication-data
status: draft
links incoming: arch~sovd-api-functional-communication-api

Data

Since functional communication returns data from multiple ECUs, the /data/{data-identifier} endpoint must return, within the top level of data, the name of the ECU as the key, and only then its returned data (if any) as the value.

In case of errors, the errors structures must still return the type DataError[]. Inside a DataError, the JSON pointer must always point to the data/{ecu-name}/... element (including the ECU name), or, in case of communication/timeout errors, just to the ECU entry /data/{ecu-name}. A regular GenericError response with a failing HTTP status code (4xx, 5xx) is only acceptable when no communication was performed and the request failed beforehand.

Note

The content-type application/octet-stream is only supported for requests.

' SPDX-FileCopyrightText: 2026 Copyright (c) Contributors to the Eclipse Foundation ' ' See the NOTICE file(s) distributed with this work for additional ' information regarding copyright ownership. ' ' This program and the accompanying materials are made available under the ' terms of the Apache License Version 2.0 which is available at ' https://www.apache.org/licenses/LICENSE-2.0 ' ' SPDX-License-Identifier: Apache-2.0 @startuml title Functional Communication -- Data Read participant Client participant "HTTP Server\n(Axum)" as HTTP participant "Security\nMiddleware" as SEC participant "Functional\nComm Handler" as HANDLER participant "Diagnostic\nKernel" as DIAG participant "UDS / DoIP" as COMM participant "ECUs\n(functional)" as ECUS Client -> HTTP : GET /functions/functionalgroups/{group}/data/{id} activate HTTP HTTP -> SEC : authenticate & authorize activate SEC SEC -> HTTP : OK deactivate SEC HTTP -> HANDLER : route to functional comm handler activate HANDLER HANDLER -> DIAG : read data (functional, service name) activate DIAG DIAG -> DIAG : resolve service from MDD\n(short name -> SID 22 + DID) DIAG -> COMM : send functional UDS request activate COMM COMM -> ECUS : DoIP (functional) -> UDS\nReadDataByIdentifier (22 {DID}) activate ECUS ECUS -> COMM : responses from ECUs\n(62 {DID} {data}) deactivate ECUS COMM -> DIAG : responses from all ECUs deactivate COMM DIAG -> DIAG : decode each ECU response\ninto named parameters DIAG -> HANDLER : decoded parameters per ECU deactivate DIAG HANDLER -> HANDLER : map to SOVD JSON response\nwith ECU name as key in "data" HANDLER -> HTTP : JSON body deactivate HANDLER HTTP -> Client : HTTP 200 OK\n{ "id": "...", "data": {\n "ecu1": { ... },\n "ecu2": { ... }\n}, "errors": [ ... ] } deactivate HTTP @enduml

Software Architecture: Functional Communication - Operations arch~sovd-api-functional-communication-operations
status: draft
links incoming: arch~sovd-api-functional-communication-api

Same principle as with data, except that the top-level element name is parameters. Asynchronous Start responses return HTTP status 202 ACCEPTED with ECU-keyed parameters and any per-ECU conversion failures in errors. Error paths point to /parameters/{ecu-name}/{field}, or /parameters/{ecu-name} if the complete response from an ECU cannot be decoded.

Note

The content-type application/octet-stream is only supported for requests.

' SPDX-FileCopyrightText: 2026 Copyright (c) Contributors to the Eclipse Foundation ' ' See the NOTICE file(s) distributed with this work for additional ' information regarding copyright ownership. ' ' This program and the accompanying materials are made available under the ' terms of the Apache License Version 2.0 which is available at ' https://www.apache.org/licenses/LICENSE-2.0 ' ' SPDX-License-Identifier: Apache-2.0 @startuml title Functional Communication -- Operations participant Client participant "HTTP Server\n(Axum)" as HTTP participant "Security\nMiddleware" as SEC participant "Functional\nComm Handler" as HANDLER participant "Diagnostic\nKernel" as DIAG participant "UDS / DoIP" as COMM participant "ECUs\n(functional)" as ECUS Client -> HTTP : POST /functions/functionalgroups/{group}/operations/{id}/executions\n{ "parameters": { ... } } activate HTTP HTTP -> SEC : authenticate & authorize activate SEC SEC -> HTTP : OK deactivate SEC HTTP -> HANDLER : route to functional comm handler activate HANDLER HANDLER -> DIAG : execute operation (functional, service name, parameters) activate DIAG DIAG -> DIAG : resolve service from MDD\n(short name -> SID 31 + routine ID) DIAG -> DIAG : encode parameters into\nUDS request payload DIAG -> COMM : send functional UDS request activate COMM COMM -> ECUS : DoIP (functional) -> UDS\nRoutineControl (31 01 {RID} {params}) activate ECUS ECUS -> COMM : responses from ECUs\n(71 01 {RID} {data}) deactivate ECUS COMM -> DIAG : responses from all ECUs deactivate COMM DIAG -> DIAG : decode each ECU response\ninto named parameters DIAG -> HANDLER : decoded parameters per ECU deactivate DIAG HANDLER -> HANDLER : map to SOVD JSON response\nwith ECU name as key in "parameters" HANDLER -> HTTP : JSON body deactivate HANDLER HTTP -> Client : HTTP 200 OK\n{ "parameters": {\n "ecu1": { ... },\n "ecu2": { ... }\n}, "errors": [ ... ] } deactivate HTTP @enduml

Software Architecture: Functional Communication - Modes arch~sovd-api-functional-communication-modes
status: draft
links incoming: arch~sovd-api-functional-communication-api

The following modes must be supported for functional groups when the underlying diagnostic description contains them:

  1. session

  2. dtcsetting

  3. commctrl

' SPDX-FileCopyrightText: 2026 Copyright (c) Contributors to the Eclipse Foundation ' ' See the NOTICE file(s) distributed with this work for additional ' information regarding copyright ownership. ' ' This program and the accompanying materials are made available under the ' terms of the Apache License Version 2.0 which is available at ' https://www.apache.org/licenses/LICENSE-2.0 ' ' SPDX-License-Identifier: Apache-2.0 @startuml title Functional Communication -- Modes participant Client participant "HTTP Server\n(Axum)" as HTTP participant "Security\nMiddleware" as SEC participant "Functional\nComm Handler" as HANDLER participant "Diagnostic\nKernel" as DIAG participant "UDS / DoIP" as COMM participant "ECUs\n(functional)" as ECUS == Example: Session switch == Client -> HTTP : PUT /functions/functionalgroups/{group}/modes/session\n{ "value": "<session name>" } activate HTTP HTTP -> SEC : authenticate & authorize activate SEC SEC -> HTTP : OK deactivate SEC HTTP -> HANDLER : route to functional comm handler activate HANDLER HANDLER -> DIAG : set mode (functional, session, value) activate DIAG DIAG -> DIAG : resolve service from MDD\n(session name -> SID 10 subfunction) DIAG -> COMM : send functional UDS request activate COMM COMM -> ECUS : DoIP (functional) -> UDS\nDiagnosticSessionControl (10 {subfunction}) activate ECUS ECUS -> COMM : positive responses\n(50 {subfunction}) deactivate ECUS COMM -> DIAG : raw UDS responses deactivate COMM DIAG -> HANDLER : mode switch confirmed deactivate DIAG HANDLER -> HTTP : JSON body deactivate HANDLER HTTP -> Client : HTTP 200 OK\n{ "id": "session", "value": "<session name>" } deactivate HTTP note over Client, ECUS Supported modes: session, dtcsetting, commctrl end note @enduml