|
1 | 1 | # kuksa-java-sdk |
2 | | -The Java SDK for Eclipse KUKSA |
| 2 | + |
| 3 | +[](https://opensource.org/licenses/Apache-2.0) |
| 4 | +[](https://gitter.im/kuksa-val/community) |
| 5 | + |
| 6 | +[](https://github.com/eclipse-kuksa/kuksa-java-sdk/actions/workflows/daily_integration_main-master.yaml?query=branch%3Amain) |
| 7 | + |
| 8 | +This is a Java SDK for the [KUKSA Vehicle Abstraction Layer](https://github.com/eclipse-kuksa/kuksa-databroker). |
| 9 | + |
| 10 | +## Overview |
| 11 | + |
| 12 | +The KUKSA Java SDK allows you to interact with [VSS data](https://covesa.github.io/vehicle_signal_specification/) |
| 13 | +from the [KUKSA Databroker](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main/) |
| 14 | +within a Java Application. The main functionality consists of fetching, updating and subscribing to VSS data. |
| 15 | + |
| 16 | +## Integration |
| 17 | + |
| 18 | +*app/build.gradle.kts* |
| 19 | +``` |
| 20 | +implementation("org.eclipse.kuksa:kuksa-java-sdk:<VERSION>") |
| 21 | +``` |
| 22 | + |
| 23 | +The latest release version can be seen [here](https://github.com/eclipse-kuksa/kuksa-java-sdk/releases). |
| 24 | + |
| 25 | + |
| 26 | +See the [quickstart guide](https://github.com/eclipse-kuksa/kuksa-java-sdk/tree/main/docs/QUICKSTART.md) for |
| 27 | +additional integration options. |
| 28 | + |
| 29 | +### Maven Central |
| 30 | + |
| 31 | +The KUKSA Java SDK is currently uploaded to [Maven Central](https://central.sonatype.com/search?q=org.eclipse.kuksa). |
| 32 | +Snapshot builds are also available (but of course less stable): https://oss.sonatype.org/content/repositories/snapshots/ |
| 33 | + |
| 34 | +## Usage |
| 35 | + |
| 36 | +> [!NOTE] |
| 37 | +> 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) |
| 38 | +> for instructions on how to establish a **secure** connection to the Databroker. |
| 39 | +
|
| 40 | +```kotlin |
| 41 | +private var dataBrokerConnection: DataBrokerConnection? = null |
| 42 | + |
| 43 | +fun connectInsecure(host: String, port: Int) { |
| 44 | + lifecycleScope.launch { |
| 45 | + val managedChannel = ManagedChannelBuilder.forAddress(host, port) |
| 46 | + .usePlaintext() |
| 47 | + .build() |
| 48 | + |
| 49 | + val connector = DataBrokerConnector(managedChannel) |
| 50 | + dataBrokerConnection = connector.connect() |
| 51 | + // Connection to the Databroker successfully established |
| 52 | + } catch (e: DataBrokerException) { |
| 53 | + // Connection to the Databroker failed |
| 54 | + } |
| 55 | +} |
| 56 | +``` |
| 57 | + |
| 58 | +```kotlin |
| 59 | +fun fetch() { |
| 60 | + lifecycleScope.launch { |
| 61 | + val request = FetchRequest("Vehicle.Speed", listOf(Field.FIELD_VALUE)) |
| 62 | + val response = dataBrokerConnection?.fetch(request) ?: return@launch |
| 63 | + val entry = entriesList.first() // Don't forget to handle empty responses |
| 64 | + val value = entry.value |
| 65 | + val speed = value.float |
| 66 | + } |
| 67 | +} |
| 68 | +``` |
| 69 | + |
| 70 | +Refer to the [quickstart guide](https://github.com/eclipse-kuksa/kuksa-java-sdk/tree/main/docs/QUICKSTART.md) or |
| 71 | +[class diagrams](https://github.com/eclipse-kuksa/kuksa-java-sdk/blob/main/docs/kuksa-sdk_class-diagram.puml) for |
| 72 | +further insight into the KUKSA SDK API. |
| 73 | + |
| 74 | +## Requirements |
| 75 | + |
| 76 | +- A working setup requires at least a running [KUKSA Databroker](https://github.com/eclipse-kuksa/kuksa-databroker/tree/main) |
| 77 | +- 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. |
| 78 | + 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. |
| 79 | +- 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. |
| 80 | + |
| 81 | +## Contribution |
| 82 | + |
| 83 | +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). |
| 84 | + |
| 85 | +## License |
| 86 | + |
| 87 | +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). |
0 commit comments