KUKSA DDS Provider

The KUKSA DDS provider provides data from an DDS middleware/API. For further understanding of the DDS middleware/API see this. The DDS provider only works with the KUKSA Databroker. The KUKSA C++ Server is not supported.

How to build

local build

python3 -m venv env && source env/bin/activate
pip install -r requirements/requirements.txt
chmod u+x ddsproviderlib/idls/generate_py_dataclass.sh
./ddsproviderlib/idls/generate_py_dataclass.sh

build image (suggested)

docker build -f Dockerfile --progress=plain --build-arg TARGETPLATFORM=linux/amd64 -t ddsprovider:latest .

KML replay

This requires that you already have created the virtual environment as described in "local build" above

source env/bin/activate
pip install -r requirements/requirements-kml.txt
cd kml && python3 dds_kmlreplay.py directions.kml

How to run

Choose from local build or containerization via docker. These steps are necessary:

Run an instance of databroker aka: docker run -it --rm --net=host ghcr.io/eclipse/kuksa.val/databroker:master
Start the KML replay with an active local python virtual environment (see KML replay section)
Start the DDS provider with either: docker run --rm -it --net=host ddsprovider:latest or with an active local python virtual environment: python3 ddsprovider.py

Configure the DDS provider

Configuration for the DDS provider is solved through setting environment variables. Have a look at the table below.

Environment variable	default value	description
VDB_ADDRESS	127.0.0.1	Address where to look for KUKSA.val Databroker
VDB_PORT	55555	On which port the KUKSA.val Databroker is expected.
MAPPING_FILE	mapping/latest/mapping.yml	Place of mapping file from DDS to VSS
TOKEN	None	JWT token which will get used to authorize to databroker; You can set on linux through `export TOKEN=$(< PATH_TO_kuksa.val/jwt/provide-all.token)` or `export TOKEN=<content of a file>`
VDB_ROOT_CA_PATH	None	Path to root CA. If defined the client will attempt to use a secure connection and identify the server using this certificate.
VDB_TLS_SERVER_NAME	None	TLS server name, may be needed if addressing a server by IP-name
VEHICLEDATABROKER_DAPR_APP_ID	None	DAPR ID for Vehicle App to look for. For more information to Vehicle Apps visit Velocitas
DAPR_GRPC_PORT	None	If DAPR gets used port of DAPR Sidecar. Overwrites VDB_PORT variable. Deprecated - please use VDB_PORT instead

Overall sequence

sequenceDiagram
title DDS on SDV
box LightBlue Container-1
participant databroker
end

dddsprovider -->> databroker : grpc_connect
alt on connection
    ddsprovider -->> databroker : register_datapoints
    ddsprovider -->> DDS_network : subscribe to topics
    ddspublisher1 -->> DDS_network : publish dds message
    ddspublisher2 -->> DDS_network : publish dds message
end
box LightBlue Container-2
participant ddspublisher1
end
box LightBlue Container-3
participant ddspublisher2
end
alt on data reception
    ddsprovider -->> databroker : update_datapoint
end

How to run the tests

The steps below shows how to run the tests in a virtual python environment.

create virtual python environment (python3 -m venv testEnv && source testEnv/bin/activate && pip install -r requirements/requirements.txt -r requirements/requirements-test.txt -r requirements/requirements-kml.txt)
Enter virtual python environment: source testEnv/bin/activate
Generate data class: ./ddsproviderlib/idls/generate_py_dataclass.sh
Run tests: pytest --html=report.html --self-contained-html --cov=. tests/* --cov-report html --cov-report xml
Leave virtual python environment: deactivate

TLS

If connecting to a KUKSA.val Databroker that require a secure connection you must specify which root certificate to use to identify the Server by the VDB_ROOT_CA_PATH variable. If your (test) setup use the KUKSA.val example certificates you must give CA.pem as root CA. The server name must match the name in the certificate provided by KUKSA.val Databroker. Due to a limitation in the gRPC client, if connecting by IP-address you may need to give a name listed in the certificate by the VDB_TLS_SERVER_NAME variable. The example server certificate lists the names Server and localhost, so one of those names needs to be specified if connecting to 127.0.0.1. An example is shown below:

VDB_ROOT_CA_PATH=/home/user/kuksa.val/kuksa_certificates/CA.pem VDB_TLS_SERVER_NAME=Server python3 ddsprovider.py

Pre-commit set up

This repository is set up to use pre-commit hooks. Use pip install pre-commit to install pre-commit. After you clone the project, run pre-commit install to install pre-commit into your git hooks. Pre-commit will now run on every commit. Every time you clone a project using pre-commit running pre-commit install should always be the first thing you do.

erikbosch / kuksa-dds-provider