From b3d3df75a46530962add1bf8069bade247087699 Mon Sep 17 00:00:00 2001 From: Andre Weber Date: Fri, 2 Feb 2024 13:12:02 +0100 Subject: [PATCH 1/4] docs: Add Quickstart Guide Closes: #18 Signed-off-by: Andre Weber --- README.md | 3 ++ docs/CONTRIBUTING.md | 3 ++ docs/QUICKSTART.md | 72 ++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 78 insertions(+) create mode 100644 docs/QUICKSTART.md diff --git a/README.md b/README.md index 0fbb882..ee6bcf6 100644 --- a/README.md +++ b/README.md @@ -31,5 +31,8 @@ Find out more about KUKSA: - KUKSA Android SDK: https://github.com/eclipse-kuksa/kuksa-android-sdk/ - KUKSA Companion App: https://github.com/eclipse-kuksa/kuksa-android-companion/ +Read our [quickstart guide](docs/QUICKSTART.md) to find out how to use the KUKSA Companion App +and setup it's infrastructure. + Includes digital car model by BMW AG licensed under CC-BY-4.0 (https://github.com/bmwcarit/digital-car-3d). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index c561a5e..796dacd 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,5 +1,8 @@ ## Getting started +Read our [quickstart guide](docs/QUICKSTART.md) to find out how to use the KUKSA Companion App +and setup it's infrastructure. + ### Make Changes ### Commit Messages diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md new file mode 100644 index 0000000..05b320d --- /dev/null +++ b/docs/QUICKSTART.md @@ -0,0 +1,72 @@ +## Introduction + +This guide explains on how to setup the infrastructure to use and test the KUKSA Companion App. + +## Requirements + +- Android Device with API Level >= 27 (Android 8.1) +- a running DataBroker +- a running MockService (Optional) + +## Setup Databroker + +To use the Companion App a connection to a Databroker is required. This Databroker might run inside +a car or on your local system for testing purposes. The steps to set up a local Databroker can be +found in +the [KUKSA.val Quickstart Guide](https://github.com/eclipse/kuksa.val/blob/master/doc/quickstart.md) + +## Setup Mock Service (Optional) + +This step is only required when connecting to a local running Databroker, which is not integrated +into an actual vehicle. + +To use the Companion App the Databroker needs to be connected to the Mock Service. +The Mock Service simulates the interaction with the car e.g. interactions with the different +interactors of a car. The steps to set up a local Databroker can be found in the +[KUKSA.val Quickstart Guide](https://github.com/eclipse/kuksa.val/blob/master/doc/quickstart.md) + +The Mock Service needs to be run with the +following [mock.py](https://github.com/eclipse-kuksa/kuksa-android-companion/blob/main/mock/mock.py) + +## Configure Companion App + +When you have access to a Databroker, the next step is to setup the Companion App so it can connect +to the Databroker. +For this enter the "Settings" screen from inside the NavigationBar of the app. + +Here you have to enter the following connection information: + +- Host: The host on which the Databroker is running. +- Port: The port on which the Databroker is running. + Make sure you used the same port, when starting the Databroker. The Apps default value is 55556. +- Enable TLS: This switch needs to be enabled, when you started your Databroker in secure mode. + Make sure you used the same mode, when starting the Databroker. +- Certificate: If TLS is enabled, it is mandatory to set a Certificate, which is used to establish + the secure connection. + +You can press the small "refresh" button in the Connection Status Bar, to start a new connection +cycle. + +## Questions + +### Can't connect to Databroker from Android Emulator + +When the App is run from an Android Emulator and the host device is running the Databroker. The host +to be used is `10.0.2.2`. This is the internal loopback address of the host device. See for further +details: https://developer.android.com/studio/run/emulator-networking + +### I can't connect to the Databroker from my mobile device. I am using a Proxy. + +The Proxy might prevent communication between the mobile device and the host device. Therefore even +though the host device is running the Databroker just fine, it is not possible for the mobile device +to connect to it. + +This can be solved by +a) using an Android Emulator +b) setting up a reverse port forwarding using adb +`adb reverse tcp:55556 tcp:55556` +This forwards all data from the host device port 55556 to the mobile device port 55556. +The host to be used is `localhost:55556` in this case. + +Reverse port forwarding requires host device and mobile device to be connected using usb, +usb debugging to be enabled on the mobile device and adb to be accessible on the host device. From 72b83bcb6e930ba8d63df57de5c22a5ea14f6a63 Mon Sep 17 00:00:00 2001 From: Andre Weber Date: Mon, 5 Feb 2024 07:52:58 +0100 Subject: [PATCH 2/4] docs: Adapt Documentation as per Review Findings --- docs/QUICKSTART.md | 117 +++++++++++++++++++++++++++++++++------------ 1 file changed, 86 insertions(+), 31 deletions(-) diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 05b320d..3f70b63 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -5,61 +5,69 @@ This guide explains on how to setup the infrastructure to use and test the KUKSA ## Requirements - Android Device with API Level >= 27 (Android 8.1) -- a running DataBroker -- a running MockService (Optional) +- a running [KUKSA.val DataBroker](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) +- a running [Vehicle Mock Service](https://github.com/eclipse/kuksa.val.services/tree/main/mock_service) (Optional) -## Setup Databroker +## Setup KUKSA.val Databroker -To use the Companion App a connection to a Databroker is required. This Databroker might run inside -a car or on your local system for testing purposes. The steps to set up a local Databroker can be -found in +To use the Companion App a connection to a KUKSA.val Databroker is required. The +KUKSA.val Databroker might run inside a car or on your local system for testing purposes. The steps +to set up a local KUKSA.val Databroker can be found in the [KUKSA.val Quickstart Guide](https://github.com/eclipse/kuksa.val/blob/master/doc/quickstart.md) -## Setup Mock Service (Optional) +## Setup Vehicle Mock Service (Optional) -This step is only required when connecting to a local running Databroker, which is not integrated -into an actual vehicle. +This step is only required when connecting to a local running KUKSA.val Databroker, which is not +integrated into an actual vehicle. -To use the Companion App the Databroker needs to be connected to the Mock Service. -The Mock Service simulates the interaction with the car e.g. interactions with the different -interactors of a car. The steps to set up a local Databroker can be found in the -[KUKSA.val Quickstart Guide](https://github.com/eclipse/kuksa.val/blob/master/doc/quickstart.md) +To use the Companion App the KUKSA.val Databroker needs to be connected to the Mock Service. +The Mock Service simulates the interaction with the car e.g. sensors and actuators of a car. +The steps to set up a local instance of the Vehicle Mock Service can be found here: +[Running mockservice](https://github.com/eclipse/kuksa.val.services/tree/main/mock_service#running-mockservice) The Mock Service needs to be run with the -following [mock.py](https://github.com/eclipse-kuksa/kuksa-android-companion/blob/main/mock/mock.py) +following [mock.py](https://github.com/eclipse-kuksa/kuksa-android-companion/blob/main/mock/mock.py). +Simply replace the mock.py inside the Vehicle Mock Service repository with the one provided by this +project to use it. ## Configure Companion App -When you have access to a Databroker, the next step is to setup the Companion App so it can connect -to the Databroker. -For this enter the "Settings" screen from inside the NavigationBar of the app. +When you have access to a KUKSA.val Databroker, the next step is to setup the Companion App so it +can connect to the it. +For this enter the "Settings" screen. The Settings screen can be found when clicking on the gear +icon in the Navigation Bar. Depending on your orientation the Navigation Bar can be found on top +(portrait) or to the left (landscape) of the screen. Here you have to enter the following connection information: -- Host: The host on which the Databroker is running. -- Port: The port on which the Databroker is running. - Make sure you used the same port, when starting the Databroker. The Apps default value is 55556. -- Enable TLS: This switch needs to be enabled, when you started your Databroker in secure mode. - Make sure you used the same mode, when starting the Databroker. +- Host: The host on which the KUKSA.val Databroker is running. +- Port: The port on which the KUKSA.val Databroker is running. + Make sure you used the same port, when starting the KUKSA.val Databroker. The default value + expected by the App is 55556 while the KUKSA.val Databroker by default starts at port 55555. +- Enable TLS: This switch needs to be enabled, when you started your KUKSA.val Databroker in + secure mode. Make sure you used the same mode, when starting the KUKSA.val Databroker. - Certificate: If TLS is enabled, it is mandatory to set a Certificate, which is used to establish the secure connection. -You can press the small "refresh" button in the Connection Status Bar, to start a new connection -cycle. +You can press the "refresh"-button, to start a new connection cycle. The "refresh"-button is the +self-referencing arrow in the Connection Status Bar. Depending on your connection status the +Connection Status Bar is colored red if no connection could be established or green if you are +successfully connected to the KUKSA.val Databroker. ## Questions -### Can't connect to Databroker from Android Emulator +### Can't connect to KUKSA.val Databroker from Android Emulator -When the App is run from an Android Emulator and the host device is running the Databroker. The host -to be used is `10.0.2.2`. This is the internal loopback address of the host device. See for further -details: https://developer.android.com/studio/run/emulator-networking +When the App is run from an Android Emulator and the host device is running the +KUKSA.val Databroker. The host to be used is `10.0.2.2`. This is the internal loopback address of +the host device. See the [android documentation](https://developer.android.com/studio/run/emulator-networking) +for further details -### I can't connect to the Databroker from my mobile device. I am using a Proxy. +### I can't connect to the KUKSA.val Databroker from my mobile device. I am using a Proxy. The Proxy might prevent communication between the mobile device and the host device. Therefore even -though the host device is running the Databroker just fine, it is not possible for the mobile device -to connect to it. +though the host device is running the KUKSA.val Databroker just fine, it is not possible for the +mobile device to connect to it. This can be solved by a) using an Android Emulator @@ -70,3 +78,50 @@ The host to be used is `localhost:55556` in this case. Reverse port forwarding requires host device and mobile device to be connected using usb, usb debugging to be enabled on the mobile device and adb to be accessible on the host device. + +## Which Signals are used inside the Companion App + +The KUKSA Companion App is based on version 4.0 of the Vehicle Signal Specification. + +It uses only a small portion of the Signals specified by the Vehicle Signal Specification for +it's show case. + +Here is a list of signals which are used inside the app: + +Door Control: +- Vehicle.Cabin.Door.Row1.DriverSide.IsLocked +- Vehicle.Cabin.Door.Row1.PassengerSide.IsLocked +- Vehicle.Cabin.Door.Row2.DriverSide.IsLocked +- Vehicle.Cabin.Door.Row2.PassengerSide.IsLocked +- Vehicle.Body.Trunk.Rear.IsLocked +- Vehicle.Cabin.Door.Row1.DriverSide.IsOpen +- Vehicle.Cabin.Door.Row1.PassengerSide.IsOpen +- Vehicle.Cabin.Door.Row2.DriverSide.IsOpen +- Vehicle.Cabin.Door.Row2.PassengerSide.IsOpen +- Vehicle.Body.Trunk.Rear.IsOpen + +Temperature Control: +- Vehicle.Cabin.HVAC.Station.Row1.Driver.Temperature +- Vehicle.Cabin.HVAC.Station.Row1.Passenger.Temperature +- Vehicle.Cabin.HVAC.Station.Row2.Driver.Temperature +- Vehicle.Cabin.HVAC.Station.Row2.Passenger.Temperature + +Light Control: +- Vehicle.Body.Lights.Beam.High.IsOn +- Vehicle.Body.Lights.Beam.Low.IsOn +- Vehicle.Body.Lights.DirectionIndicator.Left.IsSignaling +- Vehicle.Body.Lights.DirectionIndicator.Right.IsSignaling +- Vehicle.Body.Lights.Fog.Front.IsOn +- Vehicle.Body.Lights.Fog.Rear.IsOn +- Vehicle.Body.Lights.Hazard.IsSignaling +- Vehicle.Body.Lights.Parking.IsOn +- Vehicle.Body.Lights.Running.IsOn + +Tire Pressure: +- Vehicle.Chassis.Axle.Row1.Wheel.Left.Tire.Pressure +- Vehicle.Chassis.Axle.Row1.Wheel.Right.Tire.Pressure +- Vehicle.Chassis.Axle.Row2.Wheel.Left.Tire.Pressure +- Vehicle.Chassis.Axle.Row2.Wheel.Right.Tire.Pressure + +You can find more information about the signals used inside the app or other existing signals +[here](https://covesa.github.io/vehicle_signal_specification/). From a014e947ff6e271e3921f6b6dc6a279d2524ad9a Mon Sep 17 00:00:00 2001 From: Andre Weber Date: Mon, 5 Feb 2024 08:12:22 +0100 Subject: [PATCH 3/4] chore: Drop ".val" suffix --- docs/QUICKSTART.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 3f70b63..0cf6fc0 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -5,22 +5,22 @@ This guide explains on how to setup the infrastructure to use and test the KUKSA ## Requirements - Android Device with API Level >= 27 (Android 8.1) -- a running [KUKSA.val DataBroker](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) +- a running [KUKSA DataBroker](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) - a running [Vehicle Mock Service](https://github.com/eclipse/kuksa.val.services/tree/main/mock_service) (Optional) -## Setup KUKSA.val Databroker +## Setup KUKSA Databroker -To use the Companion App a connection to a KUKSA.val Databroker is required. The -KUKSA.val Databroker might run inside a car or on your local system for testing purposes. The steps -to set up a local KUKSA.val Databroker can be found in -the [KUKSA.val Quickstart Guide](https://github.com/eclipse/kuksa.val/blob/master/doc/quickstart.md) +To use the Companion App a connection to a KUKSA Databroker is required. The +KUKSA Databroker might run inside a car or on your local system for testing purposes. The steps +to set up a local KUKSA Databroker can be found in +the [KUKSA Quickstart Guide](https://github.com/eclipse/kuksa.val/blob/master/doc/quickstart.md) ## Setup Vehicle Mock Service (Optional) -This step is only required when connecting to a local running KUKSA.val Databroker, which is not +This step is only required when connecting to a local running KUKSA Databroker, which is not integrated into an actual vehicle. -To use the Companion App the KUKSA.val Databroker needs to be connected to the Mock Service. +To use the Companion App the KUKSA Databroker needs to be connected to the Mock Service. The Mock Service simulates the interaction with the car e.g. sensors and actuators of a car. The steps to set up a local instance of the Vehicle Mock Service can be found here: [Running mockservice](https://github.com/eclipse/kuksa.val.services/tree/main/mock_service#running-mockservice) @@ -32,7 +32,7 @@ project to use it. ## Configure Companion App -When you have access to a KUKSA.val Databroker, the next step is to setup the Companion App so it +When you have access to a KUKSA Databroker, the next step is to setup the Companion App so it can connect to the it. For this enter the "Settings" screen. The Settings screen can be found when clicking on the gear icon in the Navigation Bar. Depending on your orientation the Navigation Bar can be found on top @@ -40,33 +40,33 @@ icon in the Navigation Bar. Depending on your orientation the Navigation Bar can Here you have to enter the following connection information: -- Host: The host on which the KUKSA.val Databroker is running. -- Port: The port on which the KUKSA.val Databroker is running. - Make sure you used the same port, when starting the KUKSA.val Databroker. The default value - expected by the App is 55556 while the KUKSA.val Databroker by default starts at port 55555. -- Enable TLS: This switch needs to be enabled, when you started your KUKSA.val Databroker in - secure mode. Make sure you used the same mode, when starting the KUKSA.val Databroker. +- Host: The host on which the KUKSA Databroker is running. +- Port: The port on which the KUKSA Databroker is running. + Make sure you used the same port, when starting the KUKSA Databroker. The default value + expected by the App is 55556 while the KUKSA Databroker by default starts at port 55555. +- Enable TLS: This switch needs to be enabled, when you started your KUKSA Databroker in + secure mode. Make sure you used the same mode, when starting the KUKSA Databroker. - Certificate: If TLS is enabled, it is mandatory to set a Certificate, which is used to establish the secure connection. You can press the "refresh"-button, to start a new connection cycle. The "refresh"-button is the self-referencing arrow in the Connection Status Bar. Depending on your connection status the Connection Status Bar is colored red if no connection could be established or green if you are -successfully connected to the KUKSA.val Databroker. +successfully connected to the KUKSA Databroker. ## Questions -### Can't connect to KUKSA.val Databroker from Android Emulator +### Can't connect to KUKSA Databroker from Android Emulator When the App is run from an Android Emulator and the host device is running the -KUKSA.val Databroker. The host to be used is `10.0.2.2`. This is the internal loopback address of +KUKSA Databroker. The host to be used is `10.0.2.2`. This is the internal loopback address of the host device. See the [android documentation](https://developer.android.com/studio/run/emulator-networking) for further details -### I can't connect to the KUKSA.val Databroker from my mobile device. I am using a Proxy. +### I can't connect to the KUKSA Databroker from my mobile device. I am using a Proxy. The Proxy might prevent communication between the mobile device and the host device. Therefore even -though the host device is running the KUKSA.val Databroker just fine, it is not possible for the +though the host device is running the KUKSA Databroker just fine, it is not possible for the mobile device to connect to it. This can be solved by From e8f0a45632407ec5914da26a539e2f51266c06ef Mon Sep 17 00:00:00 2001 From: Andre Weber Date: Mon, 5 Feb 2024 08:35:24 +0100 Subject: [PATCH 4/4] chore: Add Info about KUKSA CLI and Python Library --- docs/QUICKSTART.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 0cf6fc0..b3771d0 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -54,7 +54,7 @@ self-referencing arrow in the Connection Status Bar. Depending on your connectio Connection Status Bar is colored red if no connection could be established or green if you are successfully connected to the KUKSA Databroker. -## Questions +## FAQ ### Can't connect to KUKSA Databroker from Android Emulator @@ -79,7 +79,7 @@ The host to be used is `localhost:55556` in this case. Reverse port forwarding requires host device and mobile device to be connected using usb, usb debugging to be enabled on the mobile device and adb to be accessible on the host device. -## Which Signals are used inside the Companion App +## Which Signals are used inside the Companion App? The KUKSA Companion App is based on version 4.0 of the Vehicle Signal Specification. @@ -125,3 +125,9 @@ Tire Pressure: You can find more information about the signals used inside the app or other existing signals [here](https://covesa.github.io/vehicle_signal_specification/). + +## Are there alternate ways to change the data of a VSS path? + +You can change the data of an underlying VSS path manually by using the +- [KUKSA CLI](https://github.com/eclipse/kuksa.val/blob/master/doc/quickstart.md#reading-and-writing-vss-data-via-cli) +- [KUKSA Python Library](https://github.com/eclipse/kuksa.val/blob/master/doc/quickstart.md#reading-and-writing-vss-data-with-code)