From a089ec103ad63e4444f6629950bac16f99f8fc20 Mon Sep 17 00:00:00 2001 From: Kai Hudalla Date: Fri, 10 Nov 2023 14:52:55 +0100 Subject: [PATCH] Improve Databroker README The README file has been restructured based on best practices. Much of the usage information has been moved into a separate User Guide document, resulting in a condensed README which focuses on setting the context, outlining the projects features and benefits and getting users started quickly. --- kuksa_databroker/README.md | 486 ++++++++++++----------------- kuksa_databroker/doc/user_guide.md | 218 +++++++++++++ 2 files changed, 425 insertions(+), 279 deletions(-) create mode 100644 kuksa_databroker/doc/user_guide.md diff --git a/kuksa_databroker/README.md b/kuksa_databroker/README.md index 8f26a8f96..1a574bdf0 100644 --- a/kuksa_databroker/README.md +++ b/kuksa_databroker/README.md @@ -1,329 +1,257 @@ -# Kuksa Databroker - -## Table of contents - - - -- [Kuksa Databroker](#kuksa-databroker) - - [Intro](#intro) - - [Relation to the COVESA Vehicle Signal Specification (VSS)](#relation-to-the-covesa-vehicle-signal-specification-vss) - - [Building KUKSA.val Databroker](#building-kuksaval-databroker) - - [Running KUKSA.val Databroker](#running-kuksaval-databroker) - - [Test the Databroker using CLI](#test-the-databroker-using-cli) - - [KUKSA.val Databroker Configuration](#kuksaval-databroker-configuration) - - [Run Databroker test cases](#run-databroker-test-cases) - - [Build and run Databroker using Docker](#build-and-run-databroker-using-docker) - - [Limitations](#limitations) - - [GRPC overview](#grpc-overview) - - [GRPC Interfaces](#grpc-interfaces) - +![Rust](https://img.shields.io/badge/rust-000000.svg?style=for-the-badge&logo=rust&logoColor=white)![Docker](https://img.shields.io/badge/docker-1D63ED.svg?style=for-the-badge&logo=docker&logoColor=white) + + + + +
+
+ + Logo + + +

Eclipse Kuksa.val™ Databroker

+ +

+ Kuksa.val Databroker is a gRPC service acting as a broker of vehicle data / data points / signals. +
+ Explore the docs » +
+
+ Report Bug + · + Request Feature + · + Chat +

+
+ + +
+ Table of Contents +
    +
  1. + Intro + +
    2. +
  2. + Getting Started + +
    3. +
  3. Usage
    4. +
  4. Building
    5. +
  5. Roadmap
    6. +
  6. Contributing
    7. +
  7. License
    8. +
  8. Contact
    9. +
+
+ + ## Intro -Kuksa Databroker is a GRPC service acting as a broker of vehicle data / data points / signals. +The [COVESA Vehicle Signal Specification](https://covesa.github.io/vehicle_signal_specification/) (VSS) defines the names and semantics of a large set of *data entries* that represent the current and/or intended state of a vehicle's sensors and actuators organized in a tree-like structure. For example, the vehicle's current speed is represented by the `Vehicle.Speed` entry. -## Relation to the COVESA Vehicle Signal Specification (VSS) +However, VSS does not define how these signals are to be collected and managed within a vehicle, nor does it prescribe how other components in the vehicle can read or write signal values from and to the tree. -The data broker is designed to support data entries and branches as defined by [VSS](https://covesa.github.io/vehicle_signal_specification/). +**Kuksa.val Databroker** is a resource efficient implementation of the VSS signal tree and is intended to be run within a vehicle on a microprocessor based platform. It allows applications in the vehicle to interact with the vehicle's sensors and actuators using a uniform, high level gRPC API for querying signals, updating current and target values of sensors and actuators and getting notified about changes to signals of interest. -In order to generate metadata from a VSS specification that can be loaded by the data broker, it's possible to use the `vspec2json.py` tool -that's available in the [vss-tools](https://github.com/COVESA/vss-tools) repository. E.g. + -```shell -./vss-tools/vspec2json.py -I spec spec/VehicleSignalSpecification.vspec vss.json +```mermaid +flowchart LR + A[Application] --VSS--- DB + DB[Kuksa.val Databroker] --VSS--- P + P[Kuksa.val Provider] --CAN frames etc---E + E[ECU] --- Sensor + E --- Actuator + style DB fill:#999999,stroke:#444444,color:#ffffff ``` -The resulting vss.json can be loaded at startup by supplying the data broker with the command line argument: +At the right end, [Kuksa.val Providers](https://github.com/eclipse/kuksa.val.feeders) implement the link between the Databroker and a vehicle's Electronic Control Units (ECU) to which the hardware sensors and actuators are physically attached. -```shell ---metadata vss.json -``` +Data is usually exchanged with ECUs by means of a CAN bus or Ethernet based protocols like SOME/IP. Providers translate between the low level messages used by these protocols and the Databroker's high level gRPC API calls to update a sensor's current reading or to forward a set-point value to an actuator via its controlling ECU. -## Building KUKSA.val Databroker +

(back to top)

-Prerequsites: -- [Rust](https://www.rust-lang.org/tools/install) -- Linux +### Features + +- 100% Open Source (Apache 2.0 license) +- Written in Rust with an easy-to-use language agnostic gRPC interface +- Lightweight (<4 MB statically compiled), allowing it to run on even small vehicle computers + +

(back to top)

+ + +## Getting started + +The quickest possible way to get Kuksa.val Databroker up and running. -### Build all +> :memo: **Note:** The examples in this section do not use TLS nor access control. Please refer to the [User Guide](./doc/user_guide.md) for more sophisticated usage examples. -`cargo build --examples --bins` +### Prerequisites -### Build all release +* [Docker Engine](https://docs.docker.com/engine/install/) or [Podman](https://podman.io/docs/installation) +* A custom Docker *bridge* network + ```sh + docker network create kuksa + ``` -`cargo build --examples --bins --release` +### Starting Databroker -## Running KUKSA.val Databroker +1. Start Databroker in a container attached to the *kuksa* bridge network using hostname *Server*: -Get help, options and version number with: + ```sh + docker run -it --rm --name Server --network kuksa ghcr.io/eclipse/kuksa.val/databroker:master --insecure + ``` + > :bulb: **Tip:** You can stop the container using `ctrl-c`. -`cargo run --bin databroker -- -h` +### Reading and writing VSS data using the CLI -```shell -Kuksa Data Broker - -USAGE: - databroker [OPTIONS] - -OPTIONS: - --address Bind address [env: KUKSA_DATA_BROKER_ADDR=] [default: 127.0.0.1] - --port Bind port [env: KUKSA_DATA_BROKER_PORT=] [default: 55555] - --vss ... Populate data broker with VSS metadata from (comma-separated) - list of files [env: KUKSA_DATA_BROKER_METADATA_FILE=] - --jwt-public-key Public key used to verify JWT access tokens - --tls-cert TLS certificate file (.pem) - --tls-private-key TLS private key file (.key) - --insecure Allow insecure connections - --dummy-metadata Populate data broker with dummy metadata - -h, --help Print help information - -V, --version Print version information -``` +1. Start the CLI in a container attached to the *kuksa* bridge network and connect to the Databroker container: -Before starting KUKSA.val Databroker you must decide if you want to use TLS for incoming connections or not. -It is recommended to use TLS which is enabled by providing a private key with `--tls-private-key` -and a server certificate with `--tls-cert`. If you do not give those arguments KUKSA.val Databroker will only accept -insecure connections. The default behavior may change in the future, so if you want insecure connections it is -recommended to use the `--insecure` argument. + ```sh + # in a new terminal + docker run -it --rm --network kuksa ghcr.io/eclipse/kuksa.val/databroker-cli:master --server Server:55555 + ``` -*Note: Unless stated otherwise, the examples below show KUKSA.val Databroker running in insecure mode!* + The CLI provides an interactive prompt which can be used to send commands to the Databroker. -Run the Databroker in insecure mode with: + ```console + ⠀⠀⠀⢀⣤⣶⣾⣿⢸⣿⣿⣷⣶⣤⡀ + ⠀⠀⣴⣿⡿⠋⣿⣿⠀⠀⠀⠈⠙⢿⣿⣦ + ⠀⣾⣿⠋⠀⠀⣿⣿⠀⠀⣶⣿⠀⠀⠙⣿⣷ + ⣸⣿⠇⠀⠀⠀⣿⣿⠠⣾⡿⠃⠀⠀⠀⠸⣿⣇⠀⠀⣶⠀⣠⡶⠂⠀⣶⠀⠀⢰⡆⠀⢰⡆⢀⣴⠖⠀⢠⡶⠶⠶⡦⠀⠀⠀⣰⣶⡀ + ⣿⣿⠀⠀⠀⠀⠿⢿⣷⣦⡀⠀⠀⠀⠀⠀⣿⣿⠀⠀⣿⢾⣏⠀⠀⠀⣿⠀⠀⢸⡇⠀⢸⡷⣿⡁⠀⠀⠘⠷⠶⠶⣦⠀⠀⢠⡟⠘⣷ + ⢹⣿⡆⠀⠀⠀⣿⣶⠈⢻⣿⡆⠀⠀⠀⢰⣿⡏⠀⠀⠿⠀⠙⠷⠄⠀⠙⠷⠶⠟⠁⠀⠸⠇⠈⠻⠦⠀⠐⠷⠶⠶⠟⠀⠠⠿⠁⠀⠹⠧ + ⠀⢿⣿⣄⠀⠀⣿⣿⠀⠀⠿⣿⠀⠀⣠⣿⡿ + ⠀⠀⠻⣿⣷⡄⣿⣿⠀⠀⠀⢀⣠⣾⣿⠟ databroker-cli + ⠀⠀⠀⠈⠛⠇⢿⣿⣿⣿⣿⡿⠿⠛⠁ v0.4.1 -`cargo run --bin databroker -- --insecure` + Successfully connected to http://Server:55555/ + sdv.databroker.v1 > + ``` + > :bulb: **Tip:** The client retrieves metadata about the data entries that the Databroker knows about during startup. This allows for using `TAB`-completion of data entry names at the prompt. -To enable TLS, provide databroker with the path to the (public) certificate and it's corresponding private key. +1. Display help for supported commands + ```sh + help + ``` + ```console + connect [URI] Connect to server + get [[PATH] ...] Get signal value(s) + set Set actuator signal + subscribe Subscribe to signals with QUERY + feed Publish signal value + metadata [PATTERN] Fetch metadata. Provide PATTERN to list metadata of signals matching pattern. + token Use TOKEN as access token + token-file Use content of FILE as access token + help You're looking at it. + quit Quit + ``` +1. Get the vehicle's current speed -```shell -cargo run --bin databroker -- --tls-cert kuksa_certificates/Server.pem --tls-private-key kuksa_certificates/Server.key -``` + ```sh + get Vehicle.Speed + ``` + ```console + [get] OK + Vehicle.Speed: ( NotAvailable ) + ``` + > :memo: **Note** When Databroker starts up, all data entries are initialized to empty values. Thus, the vehicle speed is being reported as `NotAvailable`. -To enable authorization, provide a public key used to verify JWT access tokens (provided by connecting clients). +2. Set the vehicle's current speed -```shell -cargo run --bin databroker -- --jwt-public-key kuksa_certificates/jwt/jwt.key.pub --insecure -``` -### :warning: Default port not working on Mac OS -The databroker default port `55555` is not usable in many versions of Mac OS. You can not bind it, or if it seems bound you still can not receive messages. -Therefore, on Mac OS you need to start databroker on another port, e.g. + ```sh + feed Vehicle.Speed 100.34 + ``` + ```console + [set] OK + ``` -``` -cargo run --bin databroker -- --port 55556 -``` - -Please note, this also applies if you use a container environment like K3S or Docker on Mac OS. If you forward the port or exposing the host network -interfaces, the same problem occurs. - -For more information see also https://developer.apple.com/forums/thread/671197 - -Currently, to run databroker-cli (see below), you do need to change the port it connects to in databroker-cli code and recompile it. - -## Test the Databroker using CLI +3. Get the vehicle's current speed -Run the cli with: + ```sh + get Vehicle.Speed + ``` + ```console + [get] OK + Vehicle.Speed: 100.34 + ``` -`cargo run --bin databroker-cli` - -To get help and an overview to the offered commands, run the cli and type : - -```shell -sdv.databroker.v1 > help +4. Exit the client + ```sh + quit + ``` + +

(back to top)

+ + + +## Usage + +Please refer to the [User Guide](./doc/user_guide.md) for details regarding how to run and interact with Kuksa.val Databroker. + +

(back to top)

+ +## Building + +Building Kuksa.val Databroker from source code requires + +* a [Rust tool chain](https://www.rust-lang.org/tools/install) +* a local workspace containing the source code + ```shell + git clone https://github.com/eclipse/kuksa.val.git + ``` + +

(back to top)

+ +### Building Examples and Binaries + +```sh +# in ${WORKSPACE} +cargo build --examples --bins ``` +

(back to top)

-If server wasn't running at startup +### Building release Binaries -```shell -not connected> connect +```sh +# in ${WORKSPACE} +cargo build --bins --release ``` +

(back to top)

-The server holds the metadata for the available properties, which is fetched on client startup. -This will enable `TAB`-completion for the available properties in the client. Run "metadata" in order to update it. - +### Runing Databroker Test Cases -Get data points by running "get" ```shell -sdv.databroker.v1 > get Vehicle.ADAS.CruiseControl.IsEnabled -[get] OK -Vehicle.ADAS.CruiseControl.IsEnabled: ( NotAvailable ) +# in ${WORKSPACE} +cargo test --all-targets ``` -Set data points by running "set" -```shell -sdv.databroker.v1 > set Vehicle.ADAS.CruiseControl.IsEnabled false -[set] OK -``` - -### Authorization -```shell -databroker-cli --token-file jwt/read-vehicle-speed.token -``` - -or interactively - -```shell -sdv.databroker.v1 > token XXXXXXXXXX -``` - -or - -```shell -sdv.databroker.v1 > token-file jwt/read-vehicle-speed.token -``` +

(back to top)

-### Connect to databroker using TLS -```shell -databroker-cli --ca-cert kuksa_certificates/CA.pem -``` - -### Data Broker Query Syntax - -Detailed information about the databroker rule engine can be found in [QUERY.md](doc/QUERY.md) - - -You can try it out in the client using the subscribe command in the client: +## Contributing -```shell -sdv.databroker.v1 > subscribe -SELECT - Vehicle.ADAS.ABS.IsError -WHERE - Vehicle.ADAS.ABS.IsEngaged - -[subscribe] OK -Subscription is now running in the background. Received data is identified by [1]. -``` - -## KUKSA.val Databroker Configuration +Please refer to the [Kuksa.val Contributing Guide](../CONTRIBUTING.md). -| parameter | default value | cli parameter | environment variable | description | -|----------------|---------------|------------------|-----------------------------------|----------------------------------------------| -| vss | | --vss | KUKSA_DATA_BROKER_METADATA_FILE | Populate data broker with metadata from file | -| dummy_metadata | | --dummy-metadata | | Populate data broker with dummy metadata | -| listen_address | "127.0.0.1" | --address | KUKSA_DATA_BROKER_ADDR | Listen for rpc calls | -| listen_port | 55555 | --port | KUKSA_DATA_BROKER_PORT | Listen for rpc calls | -| jwt_public_key | | --jwt-public-key | | Public key used to verify JWT access tokens | -| tls_cert | | --tls-cert | | TLS certificate file (.pem) | -| tls_private_key | | --tls-private-key | | TLS private key file (.key) | -| insecure | | --insecure | | Allow insecure connections (default unless tls_cert and tls_private_key given)| +

(back to top)

-To change the default configuration use the arguments during startup see [run section](#running-kuksaval-databroker) or environment variables. +## License -## Run Databroker test cases +Kuksa.val Databroker is provided under the terms of the [Apache Software License 2.0](../LICENSE). -Use the following command to run Databroker test cases +

(back to top)

-```shell - cargo test --all-targets - ``` - -## Build and run Databroker using Docker +## Contact -To build the release version of databroker, run the following command: +Please feel free to create [GitHub Issues](https://github.com/eclipse/kuksa.val/issues) for reporting bugs and/or ask questions in our [Gitter chat room](https://matrix.to/#/#kuksa-val_community:gitter.im). -```shell -RUSTFLAGS='-C link-arg=-s' cargo build --release --bins --examples -``` - -Or use following commands for aarch64 -``` -cargo install cross - -RUSTFLAGS='-C link-arg=-s' cross build --release --bins --examples --target aarch64-unknown-linux-gnu -``` -Build tar file from generated binaries. - -```shell -# For amd64 -tar -czvf databroker_x86_64.tar.gz \ - target/release/databroker \ - target/release/databroker-cli \ - target/release/examples/perf_setter \ - target/release/examples/perf_subscriber -``` - -```shell -# For aarch64 -tar -czvf databroker_aarch64.tar.gz \ - target/aarch64-unknown-linux-gnu/release/databroker-cli \ - target/aarch64-unknown-linux-gnu/release/databroker \ - target/aarch64-unknown-linux-gnu/release/examples/perf_setter \ - target/aarch64-unknown-linux-gnu/release/examples/perf_subscriber -``` - -To build the image execute following commands from root directory as context. - -```shell -docker build -f kuksa_databroker/Dockerfile -t databroker: . -``` - -Use following command if buildplatform is required - -```shell -DOCKER_BUILDKIT=1 docker build -f kuksa_databroker/Dockerfile -t databroker: . -``` - -The image creation may take around 2 minutes. -After the image is created the databroker container can be ran from any directory of the project: - -```shell -#By default the container will execute the ./databroker command and load the latest VSS file. -# You must explicitly specify that you want insecure mode -docker run --rm -it -p 55555:55555/tcp databroker --insecure -``` - -To run any specific command, just append you command at the end. - -```shell -docker run --rm -it -p 55555:55555/tcp databroker -``` - -## Limitations - -- Arrays are not supported in conditions as part of queries (i.e. in the WHERE clause). -- Arrays are not supported by the cli (except for displaying them) - -## GRPC overview -Vehicle data broker uses GRPC for the communication between server & clients. - -A GRPC service uses `.proto` files to specify the services and the data exchanged between server and client. -From this `.proto`, code is generated for the target language (it's available for C#, C++, Dart, Go, Java, Kotlin, Node, Objective-C, PHP, Python, Ruby, Rust...) - -This implementation uses the default GRPC transport HTTP/2 and the default serialization format protobuf. The same `.proto` file can be used to generate server skeleton and client stubs for other transports and serialization formats as well. - -HTTP/2 is a binary replacement for HTTP/1.1 used for handling connections / multiplexing (channels) & and providing a standardized way to add authorization headers for authorization & TLS for encryption / authentication. It support two way streaming between client and server. - -## GRPC Interfaces - -Databroker implements a couple of GRPC interfaces. - -### `kuksa.val.v1.VAL` - -This GRPC interface is under development and is meant to be used by kuksa-databroker, kuksa-val-server and the feeders. - -### `sdv.databroker.v1.Broker` - -This interface is currently used by databroker clients. It is defined as follows (see [file](proto/sdv/databroker/v1/broker.proto) in the proto folder): - -```protobuf -service Broker { - rpc GetDatapoints(GetDatapointsRequest) returns (GetDatapointsReply); - rpc SetDatapoints(SetDatapointsRequest) returns (SetDatapointsReply); - - rpc Subscribe(SubscribeRequest) returns (stream Notification); - - rpc GetMetadata(GetMetadataRequest) returns (GetMetadataReply); -} -``` - -### `sdv.databroker.v1.Collector` -There is also a [Collector](proto/sdv/databroker/v1/collector.proto) interface which is used by providers to feed data into the broker. - -```protobuf -service Collector { - rpc RegisterDatapoints(RegisterDatapointsRequest) returns (RegisterDatapointsReply); - - rpc UpdateDatapoints(UpdateDatapointsRequest) returns (UpdateDatapointsReply); - - rpc StreamDatapoints(stream StreamDatapointsRequest) returns (stream StreamDatapointsReply); -} -``` +

(back to top)

diff --git a/kuksa_databroker/doc/user_guide.md b/kuksa_databroker/doc/user_guide.md new file mode 100644 index 000000000..4cae44c32 --- /dev/null +++ b/kuksa_databroker/doc/user_guide.md @@ -0,0 +1,218 @@ + + +# Eclipse Kuksa.val™ Databroker User Guide + +The following sections provide information for running and configuring Databroker as well as information necessary for developing client applications invoking Databroker's external API. + + +
+ Table of Contents +
    +
  1. Getting Help
    2. +
  2. Running Databroker
    3. +
  3. Enabling Authorization
    4. +
  4. Enabling TLS
    5. +
  5. Query Syntax
    6. +
  6. Using Custom VSS Data Entries
    7. +
  7. Configuration Reference
    8. +
  8. API
    9. +
  9. Known Limitations
    10. +
+
+ +## Getting help + +Get help, options and version number with: + +```sh +docker run --rm -it ghcr.io/eclipse/kuksa.val/databroker:master -h +``` +```console +Usage: databroker [OPTIONS] + +Options: + --address Bind address [env: KUKSA_DATA_BROKER_ADDR=] [default: 127.0.0.1] + --port Bind port [env: KUKSA_DATA_BROKER_PORT=] [default: 55555] + --vss Populate data broker with VSS metadata from (comma-separated) list of files [env: KUKSA_DATA_BROKER_METADATA_FILE=] + --jwt-public-key Public key used to verify JWT access tokens + --disable-authorization Disable authorization + --insecure Allow insecure connections + --tls-cert TLS certificate file (.pem) + --tls-private-key TLS private key file (.key) + -h, --help Print help + -V, --version Print version +``` + +

(back to top)

+ +## Running Databroker + +Before starting Databroker you must decide if you want to use TLS for incoming connections or not. It is recommended to use TLS which is enabled by providing a private key with `--tls-private-key` and a server certificate with `--tls-cert`. If you do not provide those options, Databroker will only accept insecure connections. The default behavior may change in the future, so if you want insecure connections it is recommended to use the `--insecure` argument. + +```sh +docker run --rm -it -p 55555:55555 ghcr.io/eclipse/kuksa.val/databroker:master --insecure +``` + +> :warning: **Warning**: Default port not working on Mac OS +> +> On several versions of Mac OS applications cannot bind to port `55555`. Databroker needs to be configured to bind to a different (local) port in such cases: +> +> ```sh +> docker run --rm -it -p 55556:55555 ghcr.io/eclipse/kuksa.val/databroker:master --insecure +> ``` +> +> Please refer to [this support forum post](https://developer.apple.com/forums/thread/671197) for additional information. + +

(back to top)

+ +## Enabling Authorization + +Kuksa.val Databroker supports authorizing client requests based on JSON Web Tokens (JWT) provided by clients in request messages. This requires configuration of a PEM file containing the public key that should be used for verifying the tokens' signature. + +The Kuksa.val repository contains example keys and JWTs in the *kuksa_certificates* and *jwt* folders respectively which can be used for testing purposes. In order to run the commands below, the repository first needs to be cloned to the local file system: + +```shell +git clone https://github.com/eclipse/kuksa.val.git +``` + +The Databroker can then be started with support for authorization from the repository root folder: + +```shell +# in repository root +docker run --rm -it --name Server --network kuksa -v ./kuksa_certificates:/opt/kuksa ghcr.io/eclipse/kuksa.val/databroker:master --insecure --jwt-public-key /opt/kuksa/jwt/jwt.key.pub +``` + +The CLI can then be configured to use a corresponding token when connecting to the Databroker: + +```shell +# in repository root +docker run --rm -it --network kuksa -v ./jwt:/opt/kuksa ghcr.io/eclipse/kuksa.val/databroker-cli:master --server Server:55555 --token-file /opt/kuksa/read-vehicle-speed.token +``` + +The token contains a claim that authorizes the client to read the *Vehicle.Speed* signal only. +Consequently, checking if the vehicle cabin's dome light is switched on fails: + +```sh +get Vehicle.Cabin.Light.IsDomeOn +``` +```console +[get] OK +Vehicle.Cabin.Light.IsDomeOn: ( AccessDenied ) +``` + +Retrieving the vehicle's current speed succeeds but yields no value because no value has been set yet: + +```sh +get Vehicle.Speed +``` +```console +[get] OK +Vehicle.Speed: ( NotAvailable ) +``` +

(back to top)

+ +## Enabling TLS + +Kuksa.val Databroker also supports using TLS for encrypting the traffic with clients. This requires configuration of both a PEM file containing the server's private key as well as a PEM file containing the server's X.509 certificate. + +The command below starts the Databroker using the example key and certificate from the Kuksa.val repository: + +```sh +# in repository root +docker run --rm -it --name Server --network kuksa -v ./kuksa_certificates:/opt/kuksa ghcr.io/eclipse/kuksa.val/databroker:master --tls-cert /opt/kuksa/Server.pem --tls-private-key /opt/kuksa/Server.key +``` + +The CLI can then be configured to use a corresponding trusted CA certificate store when connecting to the Databroker: + +```shell +# in repository root +docker run --rm -it --network kuksa -v ./kuksa_certificates:/opt/kuksa ghcr.io/eclipse/kuksa.val/databroker-cli:master --server Server:55555 --ca-cert /opt/kuksa/CA.pem +``` +

(back to top)

+ +## Query Syntax + +Clients can subscribe to updates of data entries of interest using an SQL-based [query syntax](./QUERY.md). + +You can try it out using the `subscribe` command in the client: + +```shell +subscribe +SELECT + Vehicle.ADAS.ABS.IsError +WHERE + Vehicle.ADAS.ABS.IsEngaged +``` + +```console +[subscribe] OK +Subscription is now running in the background. Received data is identified by [1]. +``` +

(back to top)

+ +## Using Custom VSS Data Entries + +Kuksa.val Databroker supports management of data entries and branches as defined by the [Vehicle Signal Specification](https://covesa.github.io/vehicle_signal_specification/). + +In order to generate metadata from a VSS specification that can be loaded by the data broker, it's possible to use the `vspec2json.py` tool +that's available in the [vss-tools](https://github.com/COVESA/vss-tools) repository: + +```shell +./vss-tools/vspec2json.py -I spec spec/VehicleSignalSpecification.vspec vss.json +``` + +The Databroker can be configured to load the resulting `vss.json` file at startup: + +```shell +docker run --rm -it -p 55555:55555 ghcr.io/eclipse/kuksa.val/databroker:master --insecure --vss vss.json +``` +

(back to top)

+ + +## Configuration Reference + +The default configuration can be overridden by means of setting the corresponding environment variables and/or providing options on the command line as illustrated in the previous sections. + +| CLI option | Environment Variable | Default Value | Description | +|---------------------|-----------------------------------|---------------|-------------| +|`--vss`,
`--metadata`| `KUKSA_DATA_BROKER_METADATA_FILE` | | Populate data broker with metadata from file | +|`--address` | `KUKSA_DATA_BROKER_ADDR` | `127.0.0.1` | Listen for rpc calls | +|`--port` | `KUKSA_DATA_BROKER_PORT` | `55555` | Listen for rpc calls | +|`--jwt-public-key` | | | Public key used to verify JWT access tokens | +|`--tls-cert` | | | TLS certificate file (.pem) | +|`--tls-private-key` | | | TLS private key file (.key) | +|`--insecure` | | | Allow insecure connections (default unless `--tls-cert` and `--tls-private-key` options are provided) | + +

(back to top)

+ +## API + +Kuksa.val Databroker provides [gRPC](https://grpc.io/) based API endpoints which can be used by +clients to interact with the server. + +gRPC services are specified by means of `.proto` files which define the services and the data +exchanged between server and client. + +[Tooling](https://grpc.io/docs/languages/) is available for most popular programming languages to create +client stubs for invoking the services. + +The Databroker uses gRPC's default HTTP/2 transport and [protocol buffers](https://developers.google.com/protocol-buffers) for message serialization. +The same `.proto` file can be used to generate server skeleton and client stubs for other transports and serialization formats as well. + +HTTP/2 is a binary replacement for HTTP/1.1 used for handling connections, multiplexing (channels) and providing a standardized way to add headers for authorization and TLS for encryption/authentication. +It also supports bi-directional streaming between client and server. + +Kuksa.val Databroker implements the following service interfaces: + +* [kuksa.val.v1.VAL](../databroker-proto/proto/kuksa/val/v1/val.proto) +* [sdv.databroker.v1.Broker](../databroker-proto/proto/sdv/databroker/v1/broker.proto) +* [sdv.databroker.v1.Collector](../databroker-proto/proto/sdv/databroker/v1/collector.proto) + +

(back to top)

+ +## Known Limitations + +* Arrays are not supported in conditions as part of queries (i.e. in the WHERE clause). +* Arrays are not supported by the CLI (except for displaying them) + +

(back to top)