Add Quickstart guide

README.md

@@ -6,5 +6,86 @@ This is an Android SDK for the [KUKSA Vehicle Abstraction Layer](https://github.
 [![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Gitter](https://img.shields.io/gitter/room/kuksa-val/community)](https://gitter.im/kuksa-val/community)
 
+## Overview
 
-It allows you to access VSS data from KUKSA databroker using an Android System.
+The Kuksa Android SDK allows you to interact with [VSS data](https://github.com/COVESA/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. 
+
+## Integration
+
+*build.gradle*
+```
+implementation(org.eclipse.kuksa:kuksa-sdk:<VERSION>)
+```
+
+The latest release version can be seen [here](https://github.com/eclipse-kuksa/kuksa-android-sdk/releases).
+
+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 where an authentication is needed to download the dependency.
+It is recommended to not check these information into your version control.
+
+```
+maven {
+    url = uri("https://maven.pkg.github.com/eclipse-kuksa/kuksa-android-sdk")
+    credentials {
+        username = <USERNAME>
+        password = <GITHUB_TOKEN>
+    }
+}
+```
+
+## Usage
+
+```
+private var dataBrokerConnection: DataBrokerConnection? = null
+
+fun connectInsecure(host: String, port: Int) {
+    lifecycleScope.launch {
+        val managedChannel = ManagedChannelBuilder.forAddress(host, port)
+            .usePlaintext()
+            .build()
+
+        val connector = DataBrokerConnector(managedChannel)
+            dataBrokerConnection = connector.connect()
+            // Connection to the DataBroker successfully established
+        } catch (e: DataBrokerException) {
+            // Connection to the DataBroker failed
+        }
+    }
+}
+```
+
+```
+fun fetch() {
+    lifecycleScope.launch {
+        val property = Property("Vehicle.Speed")
+        val response = dataBrokerConnection?.fetch(property) ?: return@launch
+        val value = response.firstValue
+        val speed = value.float
+    }
+}
+```
+
+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.
+
+## 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.
+- Optional: The [Kuksa (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 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).
+
+## License
+
+The Kuksa Android SDK is provided under the terms of the [Apache Software License 2.0](https://github.com/eclipse/kuksa.val/blob/master/LICENSE).

docs/CONTRIBUTING.md

@@ -35,6 +35,7 @@ The following types are supported:
       {"type": "docs", "section": "Documentation"},
       {"type": "perf", "section": "Performance"},
       {"type": "refactor", "section": "Refactoring"},
+      {"type": "revert", "section": "Reverts"},
       {"type": "test", "section": "Tests"},
       {"type": "chore", "hidden": true},
       {"type": "style", "hidden": true},

docs/QUICKSTART.md

@@ -0,0 +1,157 @@
+## Introduction
+
+## Integration
+
+*build.gradle*
+```
+implementation(org.eclipse.kuksa:kuksa-sdk:<VERSION>)
+```
+
+## Connecting to the DataBroker
+
+You can use the following snippet for a simple (unsecure) connection to the DataBroker. See the samples package for
+a detailed implementation or how to connect in a secure way with a certificate.
+
+```
+private var dataBrokerConnection: DataBrokerConnection? = null
+
+fun connectInsecure(host: String, port: Int) {
+    lifecycleScope.launch {
+        val managedChannel = ManagedChannelBuilder.forAddress(host, port)
+            .usePlaintext()
+            .build()
+
+        val connector = DataBrokerConnector(managedChannel)
+        try {
+            dataBrokerConnection = connector.connect()
+            // Connection to the DataBroker successfully established
+        } catch (e: DataBrokerException) {
+            // Connection to the DataBroker failed
+        }
+    }
+}
+```
+
+## Interacting with the DataBroker
+
+```
+fun fetch() {
+    lifecycleScope.launch {
+        val property = Property("Vehicle.Speed")
+        val response = dataBrokerConnection?.fetch(property) ?: return@launch
+        val value = response.firstValue
+        val speed = value.float
+    }
+}
+
+fun update(property: Property, datapoint: Datapoint) {
+    lifecycleScope.launch {
+        val property = Property("Vehicle.Speed")
+        val datapoint = Datapoint.newBuilder().float = 50f
+        dataBrokerConnection?.update(property, datapoint)
+    }
+}
+
+ fun subscribe(property: Property) {
+        val propertyListener = object : PropertyListener {
+            override fun onPropertyChanged(vssPath: String, field: Types.Field, updatedValue: Types.DataEntry) {
+                 when (vssPath) {
+                    "Vehicle.Speed" -> {
+                        val speed = updatedValue.value.float
+                    }
+                }
+            }
+        }
+
+        dataBrokerConnection?.subscribe(property, propertyListener)
+    }
+```
+
+## Specifications Symbol Processing
+
+The generic nature of using the `Property` API will result into an information loss of the type which can be seen in 
+the `subscribe` example. It requires an additional check of the `vssPath` when 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 of the same specification the DataBroker uses.
+
+*build.gradle*
+```
+ksp(org.eclipse.kuksa:vss-processor:<VERSION>)
+```
+
+Use the new `VssDefinition` annotation and provide the path to the specification file (Inside the assets folder).
+This will generate a complete tree of Kotlin models which can be used in combination with the SDK API. This way you can
+work safe types which are also returned again when interacting with the Kuksa SDK. There is also a whole set of 
+convenience operators and methods to work with the tree data. See the `VssSpecification` class documentation for this.
+
+```
+@VssDefinition("vss_rel_4.0.yaml") 
+class MainActivity
+```
+
+*Example .yaml specification file*
+```
+Vehicle.Speed:
+  datatype: float
+  description: Vehicle speed.
+  type: sensor
+  unit: km/h
+  uuid: efe50798638d55fab18ab7d43cc490e9
+```
+
+*Example model*
+```
+public data class VssSpeed @JvmOverloads constructor(
+    override val `value`: Float = 0f,
+  ) : VssProperty<Float> {
+    override val comment: String
+      get() = ""
+
+    override val description: String
+      get() = "Vehicle speed."
+
+    override val type: String
+      get() = "sensor"
+
+    override val uuid: String
+      get() = "efe50798638d55fab18ab7d43cc490e9"
+
+    override val vssPath: String
+      get() = "Vehicle.Speed"
+
+    override val children: Set<VssSpecification>
+      get() = setOf()
+
+    override val parentClass: KClass<*>?
+      get() = VssVehicle::class
+  }
+}
+```
+
+*Specification API*
+```
+fun fetch() {
+    lifecycleScope.launch {
+        val vssSpeed = VssVehicle.VssSpeed()
+        val updatedSpeed = dataBrokerConnection?.fetch(vssSpeed)
+        val speed = updatedSpeed?.value
+    }
+}
+
+fun update() {
+    lifecycleScope.launch {
+        val vssSpeed = VssVehicle.VssSpeed(value = 100f)
+        val updatedSpeed = dataBrokerConnection?.update(vssSpeed)
+    }
+}
+
+fun subscribe() {
+    val vssSpeed = VssVehicle.VssSpeed(value = 100f)
+    dataBrokerConnection?.subscribe(vssSpeed, listener = object : VssSpecificationListener<VssVehicle.VssSpeed> {
+        override fun onSpecificationChanged(vssSpecification: VssVehicle.VssSpeed) {
+            val speed = vssSpeed.value
+        }
+    })
+}
+```

kuksa-sdk/src/main/kotlin/org/eclipse/kuksa/PropertyListener.kt

@@ -36,7 +36,7 @@ interface PropertyListener : Listener {
     /**
      * Will be triggered when an error happens during subscription and forwards the [throwable].
      */
-    fun onError(throwable: Throwable)
+    fun onError(throwable: Throwable) {}
 }
 
 /**
@@ -53,5 +53,5 @@ interface VssSpecificationListener<T : VssSpecification> {
     /**
      * Will be triggered when an error happens during subscription and forwards the [throwable].
      */
-    fun onError(throwable: Throwable)
+    fun onError(throwable: Throwable) {}
 }

samples/build.gradle.kts

@@ -1,3 +1,9 @@
+plugins {
+    id("com.android.application")
+    id("com.google.devtools.ksp")
+    kotlin("android")
+}
+
 android {
     namespace = "org.eclipse.kuksa.samples"
     compileSdk = 34
@@ -31,15 +37,10 @@ android {
 
 dependencies {
     implementation(project(":kuksa-sdk"))
+    ksp(project(":vss-processor"))
 
     // app dependencies
     implementation(libs.androidx.appcompat)
     implementation(libs.androidx.lifecycle.runtime.ktx)
     implementation(libs.androidx.activity.ktx)
 }
-
-plugins {
-    id("com.android.application")
-
-    kotlin("android")
-}