kuksa-val-server

KUKSA.VAL

Notice of Deprecation

NOTE: KUKSA Server is deprecated and will reach End-of-Life 2024-12-31!

Due to limited interest the KUKSA Project intends to declare that KUKSA Server has reached End-of-Life 2024-12-31! This means KUKSA Server will not be updated after 2024-12-31 and Pull Requests will not be accepted. Users are encouraged to migrate to KUKSA Databroker.

If you have a strong interest in KUKSA Server and are willing be responsible for maintaining it please reach out to KUKSA project by commenting in Issue 737.

Overview

kuksa-val-server is a feature rich in-vehicle data server written in C++ providing authorized access to vehicle data.

Check System Architecture for an overview how KUKSA.val can be used and deployed in a modern Software Defined Vehicle.

kuksa-val-server serves signals described using the COVESA VSS data model. VSS data is provided to applications using a variant based on the W3C VISS Interface or GRPC. KUKSA.val supports VISS V1 https://www.w3.org/TR/vehicle-information-service/ and extensions as well as parts of the upcomming VISS2 standard (Gen2 Core, Gen2 Transport), that are applicable to in-vehicle VSS servers.

See Supported Protocol for a detailled overview of the supported VISS feature.

Features

• Websocket interface, TLS-secured or plain
• Fine-grained authorisation based on JSON Webtokens (RFC 7519)
• Built-in MQTT publisher
• Python Kuksa Python SDK Client to interactively explore and modify the VSS data points and data structure
• Multiple example apps in different programming languages to communicate with different frameworks
• Multiple feeders to provide vehicle data for the kuksa.val server
• Support most of data types, which is specified in COVESA VSS data model.

Quick start

Using Docker Image

If you prefer to build kuksa.val yourself skip to Building KUKSA.val.

Download a current KUKSA.val server docker image from one of our container registry:

• https://github.com/eclipse/kuksa.val/pkgs/container/kuksa.val%2Fkuksa-val

The container images should work with any OCI compliant container runtime, in this document we assume you are using docker

Pull the docker image

docker pull ghcr.io/eclipse/kuksa.val/kuksa-val:latest

Prepare an empty directory $HOME/kuksaval.config. Run the desired docker image using docker run:

docker run -it --rm --net=host -v $HOME/kuksaval.config:/config  -p 127.0.0.1:8090:8090 -e LOG_LEVEL=ALL ghcr.io/eclipse/kuksa.val/kuksa-val:master

More information on using the docker images can be found here.

To learn, how to build your own docker image see doc/build-docker.md.

If this is successful you can skip to using kuksa.val.

Building kuksa.val

First you need to fetch the source. Make sure you also get the needed submodules, e.g. by using the --recursive flag

git clone --recursive https://github.com/eclipse/kuksa.val.git

Manually install dependencies

First install the required packages. On Ubuntu 20.04 this can be achieved by

sudo apt install cmake build-essential libssl-dev libmosquitto-dev

Compiling

Create a build folder inside the kuksa-val-server folder and execute cmake

cd kuksa-val-server
mkdir build
cd build
cmake ..

If there are any missing dependencies, cmake will tell you. If everything works fine, execute make

make

(if you have more cores, you can speed up compilation with something like make -j8

Additional information about our cmake setup (in case you need advanced options or intend to extend it) can be found here.

Running kuksa.val

After you successfully built the kuksa.val server you can run it like this

#assuming you are inside kuksa-val-server/build directory
cd src
./kuksa-val-server  --vss ./vss_release_4.0.json --log-level ALL

Setting log level to ALL gives you some more information about what is going on.

You can also edit config.ini file to configure kuksa val server. This file will be copied to the build directory and used als default config, if no other config file is specified using the command line option -c/--config-file.

For more information check usage.

Using kuksa.val

The easiest way to try kuksa-val-server out, is to use the KUKSA Python SDK kuksa-client:

pip install kuksa-client
kuksa-client

The jwt tokens for testing can also be found under kuksa_certificates/jwt.

You can also use the provided python sdk to develop your own kuksa.val clients. More details about kuksa-client can be found here.

Additionally, you can use the example apps and feeders to handle vehicle data, interacting with kuksa-val-server.