diff --git a/.versionrc b/.versionrc index d45da71..cf03f5d 100644 --- a/.versionrc +++ b/.versionrc @@ -17,7 +17,7 @@ {"type": "style", "hidden": true} ], "preMajor": true, - "commitUrlFormat": "https://github.com/eclipse-kuksa/kuksa-android-sdk/commit/{{hash}}", - "compareUrlFormat": "https://github.com/eclipse-kuksa/kuksa-android-sdk/compare/release/{{previousTag}}...{{currentTag}}", - "issueUrlFormat": "https://github.com/eclipse-kuksa/kuksa-android-sdk/issues/{{id}}" + "commitUrlFormat": "https://github.com/eclipse-kuksa/kuksa-java-sdk/commit/{{hash}}", + "compareUrlFormat": "https://github.com/eclipse-kuksa/kuksa-java-sdk/compare/release/{{previousTag}}...{{currentTag}}", + "issueUrlFormat": "https://github.com/eclipse-kuksa/kuksa-java-sdk/issues/{{id}}" } diff --git a/README.md b/README.md index c64aa09..f2d131b 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,87 @@ # kuksa-java-sdk -The Java SDK for Eclipse KUKSA + +[![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) + +[![SDK:main <-> Databroker:master](https://github.com/eclipse-kuksa/kuksa-java-sdk/actions/workflows/daily_integration_main-master.yaml/badge.svg)](https://github.com/eclipse-kuksa/kuksa-java-sdk/actions/workflows/daily_integration_main-master.yaml?query=branch%3Amain) + +This is a Java SDK for the [KUKSA Vehicle Abstraction Layer](https://github.com/eclipse-kuksa/kuksa-databroker). + +## Overview + +The KUKSA Java SDK allows you to interact with [VSS data](https://covesa.github.io/vehicle_signal_specification/) +from the [KUKSA Databroker](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/) +within a Java Application. The main functionality consists of fetching, updating and subscribing to VSS data. + +## Integration + +*app/build.gradle.kts* +``` +implementation("org.eclipse.kuksa:kuksa-java-sdk:") +``` + +The latest release version can be seen [here](https://github.com/eclipse-kuksa/kuksa-java-sdk/releases). + + +See the [quickstart guide](https://github.com/eclipse-kuksa/kuksa-java-sdk/tree/main/docs/QUICKSTART.md) for +additional integration options. + +### Maven Central + +The KUKSA Java SDK is currently uploaded to [Maven Central](https://central.sonatype.com/search?q=org.eclipse.kuksa). +Snapshot builds are also available (but of course less stable): https://oss.sonatype.org/content/repositories/snapshots/ + +## Usage + +> [!NOTE] +> The following snippet expects an **unsecure** setup of the Databroker. See the [quickstart guide](https://github.com/eclipse-kuksa/kuksa-java-sdk/blob/main/docs/QUICKSTART.md) +> for instructions on how to establish a **secure** connection to the Databroker. + +```kotlin +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 + } +} +``` + +```kotlin +fun fetch() { + lifecycleScope.launch { + val request = FetchRequest("Vehicle.Speed", listOf(Field.FIELD_VALUE)) + val response = dataBrokerConnection?.fetch(request) ?: return@launch + val entry = entriesList.first() // Don't forget to handle empty responses + val value = entry.value + val speed = value.float + } +} +``` + +Refer to the [quickstart guide](https://github.com/eclipse-kuksa/kuksa-java-sdk/tree/main/docs/QUICKSTART.md) or +[class diagrams](https://github.com/eclipse-kuksa/kuksa-java-sdk/blob/main/docs/kuksa-sdk_class-diagram.puml) for +further insight into the KUKSA SDK API. + +## Requirements + +- A working setup requires at least a running [KUKSA Databroker](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main) +- Optional: The [KUKSA Databroker CLI](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/databroker-cli) can be used to manually feed data and test your app. + See [this chapter](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main?tab=readme-ov-file#reading-and-writing-vss-data-using-the-cli) on how to read and write data via the CLI. +- Optional: The [KUKSA Mock Provider](https://github.com/eclipse-kuksa/kuksa-mock-provider?tab=readme-ov-file#kuksa-mock-provider) can be used to simulate a "real" environment. + +## Contribution + +Please feel free to create [GitHub issues](https://github.com/eclipse-kuksa/kuksa-java-sdk/issues) and [contribute](https://github.com/eclipse-kuksa/kuksa-java-sdk/blob/main/docs/CONTRIBUTING.md). + +## License + +The KUKSA Java SDK is provided under the terms of the [Apache Software License 2.0](https://github.com/eclipse-kuksa/kuksa-java-sdk/blob/main/LICENSE). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 9af15d3..7758e19 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -79,7 +79,7 @@ Used for detecting static code style issues. ### Fail-Early-Builds -We have multiple Fail-Early-Builds which run different versions of the KUKSA Android SDK against the KUKSA Databroker. +We have multiple Fail-Early-Builds which run different versions of the KUKSA Java SDK against the KUKSA Databroker. Our goal is to have an early indication which allows us more easily to find breaking or behavioral changes when running our SDK on a specific version of the Databroker. When one of these builds fail a short validity check should be done: @@ -103,7 +103,7 @@ If this build fails it should be considered as a warning **SDK:main -> Databroker:master** -[![SDK:main <-> Databroker:master](https://github.com/eclipse-kuksa/kuksa-android-sdk/actions/workflows/daily_integration_main-master.yaml/badge.svg)](https://github.com/eclipse-kuksa/kuksa-android-sdk/actions/workflows/daily_integration_main-master.yaml?query=branch%3Amain) +[![SDK:main <-> Databroker:master](https://github.com/eclipse-kuksa/kuksa-java-sdk/actions/workflows/daily_integration_main-master.yaml/badge.svg)](https://github.com/eclipse-kuksa/kuksa-java-sdk/actions/workflows/daily_integration_main-master.yaml?query=branch%3Amain) This means both the SDK and Databroker are running in a kind of "bleeding edge" state in their currently developed version. diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 645cb40..30c2e19 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -1,19 +1,17 @@ ## 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 Java SDK with the following code snippets! ## Integration *app/build.gradle.kts* ``` -implementation("org.eclipse.kuksa:kuksa-sdk:") +implementation("org.eclipse.kuksa:kuksa-java-sdk:") ``` ## Connecting to the Databroker -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. +You can use the following snippet for a simple (unsecure) connection to the Databroker. *Kotlin* ```kotlin