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
Get help, options and version number with:
docker run --rm -it ghcr.io/eclipse-kuksa/kuksa-databroker:main -hUsage: databroker [OPTIONS]
Options:
--address <IP> Bind address [env: KUKSA_DATABROKER_ADDR=] [default: 127.0.0.1]
--port <PORT> Bind port [env: KUKSA_DATABROKER_PORT=] [default: 55555]
--vss <FILE> Populate data broker with VSS metadata from (comma-separated) list of files [env: KUKSA_DATABROKER_METADATA_FILE=]
--jwt-public-key <FILE> Public key used to verify JWT access tokens
--disable-authorization Disable authorization
--insecure Allow insecure connections
--tls-cert <FILE> TLS certificate file (.pem)
--tls-private-key <FILE> TLS private key file (.key)
-h, --help Print help
-V, --version Print versionBefore 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.
docker run --rm -it -p 55555:55555 ghcr.io/eclipse-kuksa/kuksa-databroker:main --insecure
⚠️ Warning: Default port not working on Mac OSOn 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:docker run --rm -it -p 55556:55555 ghcr.io/eclipse-kuksa/kuksa-databroker:main --insecurePlease refer to this support forum post for additional information.
Kuksa 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 repository contains example keys and JWTs in the 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:
git clone https://github.com/eclipse-kuksa/kuksa-databroker.gitThe Databroker can then be started with support for authorization from the repository root folder:
# in repository root
docker run --rm -it --name Server --network kuksa -v ./certificates:/opt/kuksa ghcr.io/eclipse-kuksa/kuksa-databroker:main --insecure --jwt-public-key /opt/kuksa/jwt/jwt.key.pubThe CLI can then be configured to use a corresponding token when connecting to the Databroker:
# in repository root
docker run --rm -it --network kuksa -v ./jwt:/opt/kuksa ghcr.io/eclipse-kuksa/kuksa-databroker-cli:main --server Server:55555 --token-file /opt/kuksa/read-vehicle-speed.tokenThe 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:
get Vehicle.Cabin.Light.IsDomeOn[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:
get Vehicle.Speed[get] OK
Vehicle.Speed: ( NotAvailable )Kuksa 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 repository:
# in repository root
docker run --rm -it --name Server --network kuksa -v ./certificates:/opt/kuksa ghcr.io/eclipse-kuksa/kuksa-databroker:main --tls-cert /opt/kuksa/Server.pem --tls-private-key /opt/kuksa/Server.keyIt is mandatory to correctly qualify the Databroker URL with https:// protocol when the Databroker has an active TLS configuration.
The databroker-cli uses http://127.0.0.1:55555 as a default value therefore it is required to specify the --server flag (e.g. --server https://127.0.0.1:55555) when connecting from databroker-cli to a Databroker with an active TLS configuration.
The CLI can then be configured to use a corresponding trusted CA certificate store when connecting to the Databroker:
# in repository root
docker run --rm -it --network kuksa -v ./certificates:/opt/kuksa ghcr.io/eclipse-kuksa/kuksa-databroker-cli:main --server https://Server:55555 --ca-cert /opt/kuksa/CA.pemClients can subscribe to updates of data entries of interest using an SQL-based query syntax.
You can try it out using the subscribe command in the client:
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 Databroker supports management of data entries and branches as defined by the 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 repository:
./vss-tools/vspec2json.py -I spec spec/VehicleSignalSpecification.vspec vss.jsonThe Databroker can be configured to load the resulting vss.json file at startup:
docker run --rm -it -p 55555:55555 ghcr.io/eclipse-kuksa/kuksa-databroker:main --insecure --vss vss.jsonInternally, databroker knows different change types for VSS signals. There are three change-types
- Continuous: This are usually sensor values that are continuous, such as vehicle speed. Whenever a continuous signal is updated by a provider, all subscribers are notified.
- OnChange: This are usually signals that indicate a state, for example whether a door is open or closed. Even if this data is updated regularly by a provider, subscribers are only notified if the the value actually changed.
- Static: This are signals that you would not expect to change during one ignition cycle, i.e. if an application reads it once, it could expect this signal to remain static during the runtime of the application. The VIN might be an example for a static signal. Currently, in the implementation subscribing
staticsignals behaves exactly the same asonchangesignals.
Currently the way signals are classified depends on databroker version.
Up until version 0.4.1 (including)
- All signals where registered as OnChange
Starting from version 0.4.2, if nothing else is specified
- All signals that are of VSS type
sensororactuatorare registered as change typecontinuous - All attributes are registered as change type
static
VSS itself has no concept of change types, but you can explicitly configure this behavior on vss level with the custom extended attribute x-kuksa-changetype, where valid values are continuous, onchange, static.
Check these .vspec snippets as example
VehicleIdentification.VIN:
datatype: string
type: attribute
x-kuksa-changetype: static
description: 17-character Vehicle Identification Number (VIN) as defined by ISO 3779.
Vehicle.Speed:
datatype: float
type: sensor
unit: km/h
x-kuksa-changetype: continuous
description: Vehicle speed.
Vehicle.Cabin.Door.Row1.Left.IsOpen:
datatype: boolean
type: actuator
x-kuksa-changetype: onchange
description: Is door open or closedThe change types currently apply on current values, when subscribing to a target value, as an actuation provider would do, any set on the target value is propagated just like in continuous mode, even if a datapoint (and thus its current value behavior) is set to onchange or static. The idea here is, that a "set" by an application is the intent to actuate something (maybe a retry even), and should thus always be forwarded to the provider.
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_DATABROKER_METADATA_FILE |
Populate data broker with metadata from file | |
--address |
KUKSA_DATABROKER_ADDR |
127.0.0.1 |
Listen for rpc calls |
--port |
KUKSA_DATABROKER_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) |
Kuksa Databroker provides gRPC 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 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 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 Databroker implements the following service interfaces:
This error might occur when a client tries to connect to a Databroker with an active TLS configuration while using an 'http://' URL. The URL needs to be changed to 'https://'
The databroker-cli will use http://127.0.0.1:55555 as a default value, therefore it is required to specify the --server flag (e.g. --server https://127.0.0.1:55555) when connecting from databroker-cli.
- 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)