Skip to content

Commit

Permalink
Updating quickstart
Browse files Browse the repository at this point in the history 
Based on current released version, so using v1 in all examples

Signed-off-by: Erik Jaegervall <[email protected]>
  • Loading branch information
@erikbosch @SebastianSchildt
erikbosch authored and SebastianSchildt committed Dec 10, 2024
1 parent 5bb85f9 commit 194a1f5
Showing 1 changed file with 52 additions and 34 deletions.
86 changes: 52 additions & 34 deletions content/quickstart.md
View file
Original file line number Diff line number Diff line change
@@ -1,36 +1,40 @@
# KUKSA.val Quickstart
# Kuksa Quickstart

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

*Note: The examples in this document do not use TLS or access control.*
*They use the latest released version and use default settings as far as possible.*
*More details on how you can configure the components is available in the [GitHub Repositories](https://github.com/eclipse-kuksa)!*


## Starting broker
First we want to run KUKSA.val databroker
First we want to run latest released version of Kuksa Databroker

```
docker run -it --rm --net=host ghcr.io/eclipse/kuksa.val/databroker:master --insecure
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-databroker:latest --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.val/databroker-cli:master
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-databroker-cli:latest
```

Here is how you can use it:

```
client> get Vehicle.Speed
-> Vehicle.Speed: ( NotAvailable )
client> feed Vehicle.Speed 200
-> Ok
client> get Vehicle.Speed
-> Vehicle.Speed: 200.00
client> quit
kuksa.val.v1 > get Vehicle.Speed
[get] OK
Vehicle.Speed: NotAvailable
kuksa.val.v1 > publish Vehicle.Speed 200
[publish] OK
kuksa.val.v1 > get Vehicle.Speed
[get] OK
Vehicle.Speed: 200.00 km/h
kuksa.val.v1 > quit
Bye bye!
```
Expand All @@ -40,12 +44,11 @@ An alternative is the kuksa-client CLI (based on our Python client library).
Here is how you start it:

```
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-python-sdk/kuksa-client:main
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-python-sdk/kuksa-client:latest
```

Here is how you can use it:


```
Test Client> getValue Vehicle.Speed
{
Expand All @@ -55,25 +58,28 @@ Test Client> getValue Vehicle.Speed
Test Client> setValue Vehicle.Speed 200
OK
Test Client> getValue Vehicle.Speed
Test Client> getValue Vehicle.Speed
{
"path": "Vehicle.Speed",
"value": {
"value": 200.0,
"timestamp": "2023-01-16T12:43:57.305350+00:00"
"timestamp": "2024-11-13T14:29:37.156154+00:00"
}
}
Test Client> quit
gRPC channel disconnected.
2024-11-13 14:29:50,087 INFO kuksa_client.cli_backend.grpc: gRPC channel disconnected.
```

It is also possible to install the kuksa-client using [PyPI](https://pypi.org/project/kuksa-client/)

## Reading and Writing VSS data with code

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.
To realize your ideas with Kuksa 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 +105,7 @@ python ./speed_provider.py
```

### Subscribing data:

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

```python
Expand All @@ -119,29 +126,43 @@ Do a `pip install kuksa-client` and start with
python ./speed_subscriber.py
```

If you now run `speed_provider.py` and `speed_subscriber.py` in parallel you should get updated speed values in the subscriber.

```
Received updated speed: 0.0
Received updated speed: 1.0
Received updated speed: 2.0
Received updated speed: 3.0
Received updated speed: 4.0
Received updated speed: 5.0
...
```

## 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.val/databroker:master --port 55556 --insecure
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-databroker:latest --port 55556 --insecure
```

Using the databroker-cli

```
docker run -it --rm --net=host -e KUKSA_DATA_BROKER_PORT=55556 ghcr.io/eclipse/kuksa.val/databroker-cli:master
docker run -it --rm --net=host -e KUKSA_DATA_BROKER_PORT=55556 ghcr.io/eclipse-kuksa/kuksa-databroker-cli:latest
```

Using kuksa-client CLI

```
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-python-sdk/kuksa-client:main grpc://127.0.0.1:55556
docker run -it --rm --net=host ghcr.io/eclipse-kuksa/kuksa-python-sdk/kuksa-client:latest grpc://127.0.0.1:55556
```

### 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,29 +172,27 @@ 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.val/databroker:master --port 55556 --insecure
docker run -it --rm --publish 55556:55556 ghcr.io/eclipse-kuksa/kuksa-databroker:latest --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_DATA_BROKER_PORT=55556 -e KUKSA_DATA_BROKER_ADDR=<YOUR_IP> ghcr.io/eclipse/kuksa.val/databroker-cli:master
docker run -it --rm -e KUKSA_DATA_BROKER_PORT=55556 -e KUKSA_DATA_BROKER_ADDR=<YOUR_IP> ghcr.io/eclipse-kuksa/kuksa-databroker-cli:latest
```

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

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



### feed/set: Why is my data not updated?
### publish/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
Historically components, that gather the actual vehicle speed from some sensors/busses in a vehicle and providing a VSS representation to Kuksa have been called `feeders`. Hence, to update the current speed in the Rust-cli, you use

```
feed Vehicle.Speed 200
publish Vehicle.Speed 200
```

while in the Python-cli you use
Expand All @@ -188,13 +207,13 @@ The second-most important thing is: For VSS actuatorss, it is expected that you
You express this in the databroker-cli as

```
set Vehicle.Body.Trunk.Rear.IsOpen true
actuate Vehicle.Body.Trunk.Rear.IsOpen true
```

In kuksa-client cli you do

```
Test Client> setValue -a targetValue Vehicle.Body.Trunk.Rear.IsOpen True
Test Client> setTargetValue Vehicle.Body.Trunk.Rear.IsOpen True
```

In the code examples above you would do
Expand All @@ -205,6 +224,5 @@ 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.val/tree/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).

0 comments on commit 194a1f5

Please sign in to comment.