3.3.11.3. Communication Parameters (ComParams)¶

Software Architecture: Communication Parameters API arch~sovd-api-comparams

status: draft

links outgoing: arch~sovd-api-comparams-without-lock

Note

Communication parameter handling is exposed through a comparam endpoint in operations.

Motivation

When using the CDA to communicate with classic ECUs, a client needs the ability to modify the communication parameters like timeouts and retries on-the-fly. This API provides a way to do this.

Retrieving & Modifying with a lock

ComParam operations¶
Method	Path	Description
POST	/operations/comparam/executions	Creates an id, can also directly contain parameters to be modified
GET	/operations/comparam/executions/{id}	Returns the current communication parameters
PUT	/operations/comparam/executions/{id}	Modifies the communication parameters
DELETE	/operations/comparam/executions/{id}	Resets the communication parameters to their original state

These operations require a lock on the entity. Only one execution of communication parameters per entity is allowed.

$' 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 Communication Parameters -- Operations with Lock participant Client participant "HTTP Server\n(Axum)" as HTTP participant "Security\nMiddleware" as SEC participant "ComParam\nHandler" as HANDLER participant "ComParam\nManager" as CPMGR == Create execution (POST) == Client -> HTTP : POST /components/{ecu}/operations/comparam/executions\n{ "parameters": { ... } } activate HTTP HTTP -> SEC : authenticate & authorize activate SEC SEC -> HTTP : OK deactivate SEC HTTP -> HANDLER : route to comparam handler activate HANDLER HANDLER -> HANDLER : verify lock on entity HANDLER -> CPMGR : create execution\n(optionally apply parameters) activate CPMGR CPMGR -> CPMGR : store original parameters\nfor rollback CPMGR -> CPMGR : apply new parameters\n(if provided) CPMGR -> HANDLER : execution id deactivate CPMGR HANDLER -> HTTP : JSON body deactivate HANDLER HTTP -> Client : HTTP 202 Accepted\n{ "id": "<execution-id>", ... } deactivate HTTP == Retrieve parameters (GET) == Client -> HTTP : GET /components/{ecu}/operations/comparam/executions/{id} activate HTTP HTTP -> HANDLER : route to comparam handler activate HANDLER HANDLER -> CPMGR : get current parameters activate CPMGR CPMGR -> HANDLER : current parameters deactivate CPMGR HANDLER -> HTTP : JSON body deactivate HANDLER HTTP -> Client : HTTP 200 OK\n{ "parameters": { ... } } deactivate HTTP == Modify parameters (PUT) == Client -> HTTP : PUT /components/{ecu}/operations/comparam/executions/{id}\n{ "parameters": { ... } } activate HTTP HTTP -> HANDLER : route to comparam handler activate HANDLER HANDLER -> CPMGR : update parameters activate CPMGR CPMGR -> CPMGR : apply new parameter values CPMGR -> HANDLER : confirmed deactivate CPMGR HANDLER -> HTTP : success deactivate HANDLER HTTP -> Client : HTTP 200 OK deactivate HTTP == Reset parameters (DELETE) == Client -> HTTP : DELETE /components/{ecu}/operations/comparam/executions/{id} activate HTTP HTTP -> HANDLER : route to comparam handler activate HANDLER HANDLER -> CPMGR : delete execution activate CPMGR CPMGR -> CPMGR : restore original parameters CPMGR -> HANDLER : reset confirmed deactivate CPMGR HANDLER -> HTTP : success deactivate HANDLER HTTP -> Client : HTTP 204 No Content deactivate HTTP @enduml$

Software Architecture: Retrieve Communication Parameters without Lock arch~sovd-api-comparams-without-lock

status: draft

links incoming: arch~sovd-api-comparams

Note

This is a small extension to the ISO standard

To allow retrieving the communication parameters without a lock, a GET on /operations/comparam?todo must also return the current parameters.

Rationale

Clients without a lock might want to log the current communication parameters for informational purposes, so they should be able to retrieve them.

Handling this with the POST/GET semantic with only a single execution would make the handling extremely complicated for parallel clients with & without locks.

Example for directly retrieving communication parameters:

{
  "item": {
    "id": "comparam",
    "name": "Communication parameters",
    "asynchronous_execution": true,
    "proximity_proof_required": false
  },
  "parameters": {
    "CP_P6Max": {
      "value": "4500000",
      "unit": {
        "factor_to_si_unit": 1e-06
      }
    },
    "CP_RC78Handling": {
      "value": "Continue until RC78 timeout"
    },
    "...": {
      "...": "..."
    }
  }
}