From a3a809fac424573a79edb2760f324cafc34b202e Mon Sep 17 00:00:00 2001 From: Erik Jaegervall Date: Wed, 13 Nov 2024 15:56:02 +0100 Subject: [PATCH] Updating quickstart Based on current released version, so using v1 in all examples Signed-off-by: Erik Jaegervall --- content/quickstart.md | 86 ++++++++++++++++++++++++++----------------- 1 file changed, 52 insertions(+), 34 deletions(-) diff --git a/content/quickstart.md b/content/quickstart.md index a6b5463d..4fe2abfb 100644 --- a/content/quickstart.md +++ b/content/quickstart.md @@ -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! ``` @@ -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 { @@ -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 @@ -99,6 +105,7 @@ python ./speed_provider.py ``` ### Subscribing data: + Create a file `speed_subscriber.py` with the following content ```python @@ -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/). @@ -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= ghcr.io/eclipse/kuksa.val/databroker-cli:master +docker run -it --rm -e KUKSA_DATA_BROKER_PORT=55556 -e KUKSA_DATA_BROKER_ADDR= 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://:55556 +docker run -it --rm ghcr.io/eclipse-kuksa/kuksa-databroker-cli:latest --server http://: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 @@ -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 @@ -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).