Skip to content

Latest commit

 

History

History
 
 

kuksa_databroker

README.md

RustDocker


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. Getting Started
  3. Usage
  4. Building
  5. Roadmap
  6. Contributing
  7. License
  8. Contact

Intro

The COVESA 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.

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.

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.

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
Loading

At the right end, Kuksa.val Providers implement the link between the Databroker and a vehicle's Electronic Control Units (ECU) to which the hardware sensors and actuators are physically attached.

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.

(back to top)

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.

📝 Note: The examples in this section do not use TLS nor access control. Please refer to the User Guide for more sophisticated usage examples.

Prerequisites

Starting Databroker

  1. Start Databroker in a container attached to the kuksa bridge network using hostname Server:

    docker run -it --rm --name Server --network kuksa ghcr.io/eclipse/kuksa.val/databroker:master --insecure

    💡 Tip: You can stop the container using ctrl-c.

Reading and writing VSS data using the CLI

  1. Start the CLI in a container attached to the kuksa bridge network and connect to the Databroker container: The databroker supports both of sdv.databroker.v1 and kuksa.val.v1 as an API. Per default the databroker-cli uses the sdv.databroker.v1 interface. To change it use --protocol option when starting. Chosse eihter one of kuksa-val-v1 and sdv-databroker-v1.

    # in a new terminal
docker run -it --rm --network kuksa ghcr.io/eclipse/kuksa.val/databroker-cli:master --server Server:55555

    The CLI provides an interactive prompt which can be used to send commands to the Databroker.

      ⠀⠀⠀⢀⣤⣶⣾⣿⢸⣿⣿⣷⣶⣤⡀
  ⠀⠀⣴⣿⡿⠋⣿⣿⠀⠀⠀⠈⠙⢿⣿⣦
  ⠀⣾⣿⠋⠀⠀⣿⣿⠀⠀⣶⣿⠀⠀⠙⣿⣷
  ⣸⣿⠇⠀⠀⠀⣿⣿⠠⣾⡿⠃⠀⠀⠀⠸⣿⣇⠀⠀⣶⠀⣠⡶⠂⠀⣶⠀⠀⢰⡆⠀⢰⡆⢀⣴⠖⠀⢠⡶⠶⠶⡦⠀⠀⠀⣰⣶⡀
  ⣿⣿⠀⠀⠀⠀⠿⢿⣷⣦⡀⠀⠀⠀⠀⠀⣿⣿⠀⠀⣿⢾⣏⠀⠀⠀⣿⠀⠀⢸⡇⠀⢸⡷⣿⡁⠀⠀⠘⠷⠶⠶⣦⠀⠀⢠⡟⠘⣷
  ⢹⣿⡆⠀⠀⠀⣿⣶⠈⢻⣿⡆⠀⠀⠀⢰⣿⡏⠀⠀⠿⠀⠙⠷⠄⠀⠙⠷⠶⠟⠁⠀⠸⠇⠈⠻⠦⠀⠐⠷⠶⠶⠟⠀⠠⠿⠁⠀⠹⠧
  ⠀⢿⣿⣄⠀⠀⣿⣿⠀⠀⠿⣿⠀⠀⣠⣿⡿
  ⠀⠀⠻⣿⣷⡄⣿⣿⠀⠀⠀⢀⣠⣾⣿⠟    databroker-cli
  ⠀⠀⠀⠈⠛⠇⢿⣿⣿⣿⣿⡿⠿⠛⠁     v0.4.1

Successfully connected to http://Server:55555/
sdv.databroker.v1 >

    💡 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.

  2. Display help for supported commands

    help
    connect [URI]            Connect to server
get <PATH> [[PATH] ...]  Get signal value(s)
set <PATH> <VALUE>       Set actuator signal
subscribe <QUERY>        Subscribe to signals with QUERY
feed <PATH> <VALUE>      Publish signal value
metadata [PATTERN]       Fetch metadata. Provide PATTERN to list metadata of signals matching pattern.
token <TOKEN>            Use TOKEN as access token
token-file <FILE>        Use content of FILE as access token
help                     You're looking at it.
quit                     Quit

  3. Get the vehicle's current speed

    get Vehicle.Speed
    [get]  OK
Vehicle.Speed: ( NotAvailable )

    📝 Note When Databroker starts up, all data entries are initialized to empty values. Thus, the vehicle speed is being reported as NotAvailable.

  4. Set the vehicle's current speed

    feed Vehicle.Speed 100.34
    [set]  OK

  5. Get the vehicle's current speed

    get Vehicle.Speed
    [get]  OK
Vehicle.Speed: 100.34

Run the cli with:

  1. Exit the client 
    quit

(back to top)

Usage

Please refer to the User Guide 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
  • a local workspace containing the source code 
    git clone https://github.com/eclipse/kuksa.val.git

(back to top)

Building Examples and Binaries

# in ${WORKSPACE}
cargo build --examples --bins

(back to top)

Building release Binaries

# in ${WORKSPACE}
cargo build --bins --release

(back to top)

Runing Databroker Test Cases

# in ${WORKSPACE}
cargo test --all-targets

(back to top)

Contributing

Please refer to the Kuksa.val Contributing Guide.

(back to top)

License

Kuksa.val Databroker is provided under the terms of the Apache Software License 2.0.

(back to top)

Contact

Please feel free to create GitHub Issues for reporting bugs and/or ask questions in our Gitter chat room.

(back to top)