diff --git a/README.md b/README.md index b79ac9bf..4d07be52 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ This is an Android SDK for the [KUKSA Vehicle Abstraction Layer](https://github. ## Overview -The Kuksa Android SDK allows you to interact with [VSS data](https://covesa.github.io/vehicle_signal_specification/) +The KUKSA Android SDK allows you to interact with [VSS data](https://covesa.github.io/vehicle_signal_specification/) from the [KUKSA Databroker](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) within an Android App. The main functionality consists of fetching, updating and subscribing to VSS data. @@ -23,13 +23,14 @@ The latest release version can be seen [here](https://github.com/eclipse-kuksa/k Snapshot builds are also available (but of course less stable): [Package view](https://github.com/eclipse-kuksa/kuksa-android-sdk/packages/1986280/versions) -See the [Quickstart guide](https://github.com/eclipse-kuksa/kuksa-android-sdk/tree/main/docs/QUICKSTART.md) for +See the [quickstart guide](https://github.com/eclipse-kuksa/kuksa-android-sdk/tree/main/docs/QUICKSTART.md) for additional integration options. ### GitHub packages -The Kuksa SDK is currently uploaded to [GitHub packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry#authenticating-to-github-packages) -where an authentication is needed to download the dependency. +The KUKSA SDK is currently uploaded to [GitHub packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry) +where an [authentication](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry#authenticating-to-github-packages) +is needed to download the dependency. ``` maven { @@ -44,7 +45,8 @@ maven { ## Usage > [!NOTE] -> The following snippet expects an unsecure setup of the Databroker. Please see the [QUICKSTART](https://github.com/eclipse-kuksa/kuksa-android-sdk/blob/main/docs/QUICKSTART.md) guide. +> The following snippet expects an **unsecure** setup of the Databroker. See the [quickstart](https://github.com/eclipse-kuksa/kuksa-android-sdk/blob/main/docs/QUICKSTART.md) guide +> for instructions on how to establish a **secure** connection to the Databroker. ```kotlin private var dataBrokerConnection: DataBrokerConnection? = null @@ -57,9 +59,9 @@ fun connectInsecure(host: String, port: Int) { val connector = DataBrokerConnector(managedChannel) dataBrokerConnection = connector.connect() - // Connection to the DataBroker successfully established + // Connection to the Databroker successfully established } catch (e: DataBrokerException) { - // Connection to the DataBroker failed + // Connection to the Databroker failed } } ``` @@ -76,22 +78,21 @@ fun fetch() { } ``` -Refer to the [Quickstart guide](https://github.com/eclipse-kuksa/kuksa-android-sdk/tree/main/docs/QUICKSTART.md) or +Refer to the [quickstart guide](https://github.com/eclipse-kuksa/kuksa-android-sdk/tree/main/docs/QUICKSTART.md) or [class diagrams](https://github.com/eclipse-kuksa/kuksa-android-sdk/blob/main/docs/kuksa-sdk_class-diagram.puml) for -further insight into the Kuksa SDK API. You can also checkout the [sample](https://github.com/eclipse-kuksa/kuksa-android-sdk/tree/main/samples) implementation. +further insight into the KUKSA SDK API. You can also checkout the [sample](https://github.com/eclipse-kuksa/kuksa-android-sdk/tree/main/samples) implementation. ## Requirements -- A working setup requires at least a running Kuksa [Databroker](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) -- Optional: The [Kuksa Databroker CLI](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) can be used to manually feed data and test your app. +- A working setup requires at least a running KUKSA [Databroker](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) +- Optional: The [KUKSA Databroker CLI](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker) can be used to manually feed data and test your app. See [this chapter](https://github.com/eclipse/kuksa.val/tree/master/kuksa_databroker#reading-and-writing-vss-data-using-the-cli) on how to read and write data via the CLI. -- Optional: The [(Vehicle) Mock Service](https://github.com/eclipse/kuksa.val.services/tree/main/mock_service) can be used to simulate a "real" environment. +- Optional: The [Mock Service](https://github.com/eclipse/kuksa.val.services/tree/main/mock_service) can be used to simulate a "real" environment. ## Contribution -Please feel free to create [GitHub issues](https://github.com/eclipse-kuksa/kuksa-android-sdk/issues) and contribute -[(Guidelines)](https://github.com/eclipse-kuksa/kuksa-android-sdk/blob/main/docs/CONTRIBUTING.md). +Please feel free to create [GitHub issues](https://github.com/eclipse-kuksa/kuksa-android-sdk/issues) and [contribute](https://github.com/eclipse-kuksa/kuksa-android-sdk/blob/main/docs/CONTRIBUTING.md). ## License -The Kuksa Android SDK is provided under the terms of the [Apache Software License 2.0](https://github.com/eclipse-kuksa/kuksa-android-sdk/blob/main/LICENSE). +The KUKSA Android SDK is provided under the terms of the [Apache Software License 2.0](https://github.com/eclipse-kuksa/kuksa-android-sdk/blob/main/LICENSE). diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 6c99a8d1..ffbb0571 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -1,6 +1,6 @@ ## Introduction -Get instantly bootstrapped into the world of the Kuksa SDK with the following code snippets! +Get instantly bootstrapped into the world of the KUKSA SDK with the following code snippets! ## Integration @@ -9,9 +9,9 @@ Get instantly bootstrapped into the world of the Kuksa SDK with the following co implementation("org.eclipse.kuksa:kuksa-sdk:") ``` -## Connecting to the DataBroker +## Connecting to the Databroker -You can use the following snippet for a simple (unsecure) connection to the DataBroker. This highly depends on your +You can use the following snippet for a simple (unsecure) connection to the Databroker. This highly depends on your setup so see the [samples package](https://github.com/eclipse-kuksa/kuksa-android-sdk/blob/main/samples/src/main/kotlin/com/example/sample/KotlinActivity.kt) for a detailed implementation or how to connect in a secure way with a certificate. @@ -28,9 +28,9 @@ fun connectInsecure(host: String, port: Int) { val connector = DataBrokerConnector(managedChannel) try { dataBrokerConnection = connector.connect() - // Connection to the DataBroker successfully established + // Connection to the Databroker successfully established } catch (e: DataBrokerException) { - // Connection to the DataBroker failed + // Connection to the Databroker failed } } } @@ -51,13 +51,13 @@ void connectInsecure(String host, int port) { @Override public void onError(@NonNull Throwable error) { - // Connection to the DataBroker failed + // Connection to the Databroker failed } }); } ``` -## Interacting with the DataBroker +## Interacting with the Databroker *Kotlin* ```kotlin @@ -150,7 +150,7 @@ the `subscribe` example. You may choose to reuse the same listener for multiple of the `vssPath` after receiving an updated value to correctly cast it back. This is feasible for simple use cases but can get tedious when working with a lot of vehicle signals. For a more convenient usage you can opt in to auto generate Kotlin models via [Symbol Processing](https://kotlinlang.org/docs/ksp-quickstart.html) -of the same specification the DataBroker uses. For starters you can retrieve an extensive default specification from the +of the same specification the Databroker uses. For starters you can retrieve an extensive default specification from the release page of the [COVESA Vehicle Signal Specification GitHub repository](https://github.com/COVESA/vehicle_signal_specification/releases). *build.gradle* @@ -174,7 +174,7 @@ class KotlinActivity public class JavaActivity ``` > [!IMPORTANT] -> Keep in mind to always synchronize the specification file between the client and the DataBroker. +> Keep in mind to always synchronize the specification file between the client and the Databroker. *Example .yaml specification file*