Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Test/caching #1

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Test/caching #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4848d0b
Fix corrupted links, wrong branch references and incorrect commands w…
dennismeister93 May 7, 2024
a6642a9
testcache
SebastianSchildt May 9, 2024
eeb6041
testcache
SebastianSchildt May 9, 2024
552fb61
Fix caching on databroker build
SebastianSchildt May 9, 2024
9137157
testcache
SebastianSchildt May 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/kuksa_databroker_build.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ jobs:
~/.cargo/git/db/
~/.cargo/.crates.toml
~/.cargo/.crates2.json
target/
target-*/
key: databroker-release-${{ matrix.platform.name }}-${{ hashFiles('**/Cargo.lock') }}
- name: Install build prerequisites
working-directory: ${{github.workspace}}/
Expand Down
35 changes: 22 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
![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)

<!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 -->

<a name="readme-top"></a>

<!-- PROJECT LOGO -->
Expand Down Expand Up @@ -53,9 +55,10 @@
</details>

<!-- ABOUT THE PROJECT -->

## Intro

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

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.

Expand Down Expand Up @@ -88,6 +91,7 @@ Data is usually exchanged with ECUs by means of a CAN bus or Ethernet based prot
<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- GETTING STARTED -->

## Getting started

The quickest possible way to get Kuksa Databroker up and running.
Expand All @@ -96,26 +100,26 @@ The quickest possible way to get Kuksa Databroker up and running.

### Prerequisites

* [Docker Engine](https://docs.docker.com/engine/install/) or [Podman](https://podman.io/docs/installation)
* A custom Docker *bridge* network
- [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
```

### Starting Databroker

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

```sh
docker run -it --rm --name Server --network kuksa ghcr.io/eclipse-kuksa/kuksa-databroker:main --insecure
```

> :bulb: **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```.

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

```sh
# in a new terminal
Expand All @@ -138,6 +142,7 @@ The quickest possible way to get Kuksa Databroker up and running.
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.

1. Display help for supported commands
Expand All @@ -161,26 +166,30 @@ The quickest possible way to get Kuksa Databroker up and running.
```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`.

2. Set the vehicle's current speed
1. Set the vehicle's current speed

```sh
feed Vehicle.Speed 100.34
publish Vehicle.Speed 100.34
```

```console
[set] OK
```

3. Get the vehicle's current speed
1. Get the vehicle's current speed

```sh
get Vehicle.Speed
```

```console
[get] OK
Vehicle.Speed: 100.34
Expand All @@ -195,8 +204,8 @@ Run the cli with:

<p align="right">(<a href="#readme-top">back to top</a>)</p>


<!-- USAGE EXAMPLES -->

## Usage

Please refer to the [User Guide](./doc/user_guide.md) for details regarding how to run and interact with Kuksa Databroker.
Expand All @@ -207,8 +216,8 @@ Please refer to the [User Guide](./doc/user_guide.md) for details regarding how

Building Kuksa Databroker from source code requires

* a [Rust tool chain](https://www.rust-lang.org/tools/install)
* a local workspace containing the source code
- 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/kuksa-databroker.git
```
Expand Down
80 changes: 40 additions & 40 deletions doc/protocol/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,55 +2,54 @@

This file contains an overview what the KUKSA Server and databroker each supports. It focuses on gRPC and VISS support and also what feeders are supported.


| Protocol | KUKSA server | KUKSA databroker |
|---------------------------|:----------------:|:--------------------:|
| VISS V1 | - | - |
| VISS V2 | x/- | x/- |
| gRPC (kuksa) | x | - |
| gRPC (kuksa.val.v1) | - | x |
| gRPC (sdv.databroker.v1) | - | x |
| Protocol | KUKSA server | KUKSA databroker |
| ------------------------ | :----------: | :--------------: |
| VISS V1 | - | - |
| VISS V2 | x/- | x/- |
| gRPC (kuksa) | x | - |
| gRPC (kuksa.val.v1) | - | x |
| gRPC (sdv.databroker.v1) | - | x |

x = supported; x/- = partially supported; - = not supported


### VISSv2 support (websocket transport)

| Feature | KUKSA server | KUKSA databroker |
|-------------------------------|:-----------------:|:--------------------:|
| Read | | |
| - Authorized Read | x<sup>1,2</sup> | x |
| - Search Read | - | - |
| - History Read | - | - |
| - Static Metadata Read | - | x |
| - Dynamic Metadata Read | - | - |
| Update | | |
| - Authorized Update | x<sup>1,2</sup> | x |
| Subscribe | | |
| - Authorized Subscribe | x<sup>1,2</sup> | x |
| - Curve Logging Subscribe | - | - |
| - Range Subscribe | - | - |
| - Change Subscribe | - | - |
| Unsubscribe | x | x |
| Subscription | x | x |
| Error messages | x | x |
| Timestamps | x | x |
| Feature | KUKSA server | KUKSA databroker |
| ------------------------- | :-------------: | :--------------: |
| Read | | |
| - Authorized Read | x<sup>1,2</sup> | x |
| - Search Read | - | - |
| - History Read | - | - |
| - Static Metadata Read | - | x |
| - Dynamic Metadata Read | - | - |
| Update | | |
| - Authorized Update | x<sup>1,2</sup> | x |
| Subscribe | | |
| - Authorized Subscribe | x<sup>1,2</sup> | x |
| - Curve Logging Subscribe | - | - |
| - Range Subscribe | - | - |
| - Change Subscribe | - | - |
| Unsubscribe | x | x |
| Subscription | x | x |
| Error messages | x | x |
| Timestamps | x | x |

x = supported

x<sup>1</sup> Authorization is done using a non-standard standalone call which is incompatible with standards compliant clients.

x<sup>2</sup> Relies on the non-standard `attribute` values which doesn't work with standards compliant clients.

For a more detailed view of the supported JSON-schemas [click here](https://github.com/eclipse-kuksa/kuksa-databrokerblob/master/kuksa-val-server/include/VSSRequestJsonSchema.hpp)

For a more detailed view of the supported JSON-schemas [click here](https://github.com/eclipse/kuksa.val/blob/master/kuksa-val-server/include/VSSRequestJsonSchema.hpp)

### VISSv2 in KUKSA Databroker

KUKSA databroker aims to provide a standards compliant implementation of VISSv2 (using the websocket transport).

It supports authorization using the access token format specified in [authorization.md](../authorization.md).

VISSv2 support in databroker is included by building it with the `viss` feature flag.

```shell
$ cargo build --features viss
```
Expand All @@ -70,15 +69,16 @@ $ kuksa-client ws://127.0.0.1:8090
TLS is currently not supported.

### KUKSA databroker gRPC API

The VISS Standard is not applicable for gRPC protocols. Here is an overview what the gRPC API in KUKSA databroker is capable of:

* Read: Reading VSS datapoints
* Reading current or target value for actuators
* Reading some metadata information from VSS datapoints
* Write: Writing VSS datapoints
* Writing sensor values
* Writing current or target value for actuators
* Soon: Writing some metadata information from VSS datapoints
* Subscription: Subscribing VSS datapoints
* Subscribing sensor values
* Subscribing current or target value for actuators
- Read: Reading VSS datapoints
- Reading current or target value for actuators
- Reading some metadata information from VSS datapoints
- Write: Writing VSS datapoints
- Writing sensor values
- Writing current or target value for actuators
- Soon: Writing some metadata information from VSS datapoints
- Subscription: Subscribing VSS datapoints
- Subscribing sensor values
- Subscribing current or target value for actuators
32 changes: 18 additions & 14 deletions doc/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,24 @@

The quickest possible way to get KUKSA.val up and running

*Note: The examples in this document do not use TLS or access control.*
_Note: The examples in this document do not use TLS or access control._

## Starting broker

First we want to run KUKSA.val databroker

```
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-databrokerdatabroker:master --insecure
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-databroker:main --insecure
```


## Reading and Writing VSS data via CLI

You can interact with the VSS datapoints using the cli clients. The first option is databroker-cli.

This is, how you start it:

```
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-databrokerdatabroker-cli:master
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-databroker-cli:main
```

Here is how you can use it:
Expand All @@ -45,7 +46,6 @@ docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-python-sdk/kuksa-clie

Here is how you can use it:


```
Test Client> getValue Vehicle.Speed
{
Expand Down Expand Up @@ -74,6 +74,7 @@ gRPC channel disconnected.
To realize your ideas with KUKSA.val you need to write programs that interact with its API. The easiest way to achieve this is using our Python library.

### Generating data

Create a file `speed_provider.py` with the following content

```python
Expand All @@ -99,6 +100,7 @@ python ./speed_provider.py
```

### Subscribing data:

Create a file `speed_subscriber.py` with the following content

```python
Expand All @@ -120,19 +122,21 @@ python ./speed_subscriber.py
```

## FAQ & Notes

Frequently anticipated questions and tips.

### This is not working on OS X

Unfortunately OS X has a bug that does not allow you to use the Databroker default port 55555. To change when starting the server:

```
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-databrokerdatabroker:master --port 55556 --insecure
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-databroker:main --port 55556 --insecure
```

Using the databroker-cli

```
docker run -it --rm --net=host -e KUKSA_DATABROKER_PORT=55556 ghcr.io/eclipse-kuksa/kuksa-databrokerdatabroker-cli:master
docker run -it --rm --net=host -e KUKSA_DATABROKER_PORT=55556 ghcr.io/eclipse-kuksa/kuksa-databroker-cli:main
```

Using kuksa-client CLI
Expand All @@ -142,6 +146,7 @@ docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-python-sdk/kuksa-clie
```

### Docker desktop: Host networking not supported

The examples above all used docker's `--net=host` option. That is quite convenient for development, as basically your containers "share" your hosts networking and there is no need for any port publishing.

However when using Docker Desktop on Mac OS or Windows, [host networking is not supported](https://docs.docker.com/network/host/).
Expand All @@ -151,24 +156,23 @@ One alternative is using a Docker distribution, that does support it even on Mac
With Docker Desktop you can still forward ports, so this should work:

```
docker run -it --rm --publish 55556:55556 ghcr.io/eclipse-kuksa/kuksa-databrokerdatabroker:master --port 55556 --insecure
docker run -it --rm --publish 55556:55556 ghcr.io/eclipse-kuksa/kuksa-databroker:main --port 55556 --insecure
```

From your host computer you can now reach databroker at `127.0.0.1:55556`. To connect from another container, you need to use your computers IP address (**not** 127.0.0.1), i.e. to use the client

```
docker run -it --rm -e KUKSA_DATABROKER_PORT=55556 -e KUKSA_DATABROKER_ADDR=<YOUR_IP> ghcr.io/eclipse-kuksa/kuksa-databrokerdatabroker-cli:master
docker run -it --rm -e KUKSA_DATABROKER_PORT=55556 -e KUKSA_DATABROKER_ADDR=<YOUR_IP> ghcr.io/eclipse-kuksa/kuksa-databroker-cli:main
```

Recent versions of the databroker-cli also support command line arguments, so you can also write

```
docker run -it --rm ghcr.io/eclipse-kuksa/kuksa-databrokerdatabroker-cli:master --server http://<YOUR_IP>:55556
docker run -it --rm ghcr.io/eclipse-kuksa/kuksa-databroker-cli:main --server http://<YOUR_IP>:55556
```



### feed/set: Why is my data not updated?

Some VSS points are "sensors", e.g. Vehicle.Speed. You can read/get Vehicle speed, but we are not expecting to be able to influence it via VSS.
Historically components, that gather the actual vehicle speed from some sensors/busses in a vehicle and providing a VSS representation to kuksa.val have been called `feeders`. Hence, to update the current speed in the Rust-cli, you use

Expand Down Expand Up @@ -205,6 +209,6 @@ client.set_target_values({
})
```


### All I see is Python, shouldn't this be high-performance?
Our Python library makes it easy to interact with databroker. While this is often sufficient for many applications, you are not limited by it: Databroker's native interface is based on GRPC, a high-performance GRPC framework. GRPC enables you to generate bindings for _any_ language. Check the [GRPC website](https://grpc.io) and take a look at the [databroker interface definitions](https://github.com/eclipse-kuksa/kuksa-databrokertree/master/proto/kuksa/val/v1).

Our Python library makes it easy to interact with databroker. While this is often sufficient for many applications, you are not limited by it: Databroker's native interface is based on GRPC, a high-performance GRPC framework. GRPC enables you to generate bindings for _any_ language. Check the [GRPC website](https://grpc.io) and take a look at the [databroker interface definitions](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/proto/kuksa/val/v1).
Loading
Loading