README.md

Eclipse Hara™ - hara-ddiclient

Hara-ddiclient is a Kotlin library that facilitates and speeds up the development of DDI API clients for devices connecting to hawkBit servers. It can be used from any JVM compatible language (Java, Kotlin, etc). Hara-ddiclient is part of the Eclipse Hara™ project

Project structure

The hara-ddiclient project provides several software modules:

1. ddi-consumer: implementation of a REST client for hawkBit DDI API
2. hara-ddiclient: implementation of communication logic using actors (uses ddi-consumer)
3. virtual-device: a simple application using the hara-ddiclient library (uses hara-ddiclient). Its purpose is to provide a configurable "virtual device" and a reference example on how to use the library. Some features, like the Updater, are not implemented in the virtual device and are just mocked.

Install

Here an example on how to import hara-ddiclient in a gradle project.

Add the JitPack repository to your build.gradle file at the end of repositories section:

allprojects {
	repositories {
		...
		maven { url 'https://jitpack.io' }
	}
}

Add the dependency

dependencies {
        implementation 'com.github.eclipse:hara-ddiclient:Tag'
}

For additional information refer to jitpack.

Build from source

To build this project from source:

./gradlew assemble

to build this project and run the tests (docker compose v2 required):

./gradlew build

to build the hara-virtual-device docker image:

./gradlew buildImage

to connect the virtual devices to the hawkBit sandbox:

docker run -e HAWKBIT_GATEWAY_TOKEN=<gatewaytokenvalue> -e HAWKBIT_CONTROLLER_ID=<mycontrollerid> hara-virtual-device:<virtual-device-version>

for example:

docker run -e HAWKBIT_GATEWAY_TOKEN=50f600c6e7e517b98b008311b0a325eb -e HAWKBIT_CONTROLLER_ID=mydevice hara-virtual-device:2.0.0

Make sure the authentication method provided in the parameters is enabled in the "System Config" page. Available virtual device parameters can be found in the Configuration class.

API usage

To learn how to use the hara-ddiclient library:

1. read the APIs documentation
2. follow the API usage example instructions
3. poke around the virtual-device source code

API usage example

Create a class that implements the DirectoryForArtifactsProvider interface:

class DirectoryForArtifactsProviderImpl(): DirectoryForArtifactsProvider {
    override fun directoryForArtifacts(): File {
        ...
    }
}

Create a class that implements the ConfigDataProvider interface:

class ConfigDataProviderImpl(): ConfigDataProvider {
    override fun configData(): Map<String, String> {
        ...
    }
}

Create a class that implements the DeploymentPermitProvider interface:

class DeploymentPermitProviderImpl: DeploymentPermitProvider {
    override fun downloadAllowed(): Deferred<Boolean> {
        ...
    }
    override fun updateAllowed(): Deferred<Boolean> {
        ...
    }
}

Create a class that implements the MessageListener interface:

class MessageListenerImpl(): MessageListener {
        override fun onMessage(message: MessageListener.Message) {
        ...
    }
}

Create a class that implements the Updater interface:

class UpdaterImpl(): Updater {
    override fun apply(modules: Set<Updater.SwModuleWithPath>,messenger: Updater.Messenger){
        ...
    }
}

Create a class that implements the DownloadBehavior interface:

class DownloadBehaviorImpl(): DownloadBehavior {
    override fun onAttempt(attempt: Int, artifactId:String, previousError: Throwable?): DownloadBehavior.Try {
        ...
    }
}

Create the Client, add the provider and return the client:

val client = HaraClientDefaultImpl()
client.init(
    clientData,
    DirectoryForArtifactsProviderImpl(),
    ConfigDataProviderImpl(),
    DeploymentPermitProviderImpl(),
    listOf(MessageListenerImpl()),
    listOf(UpdaterImpl())
)
return client

Contributing

To contribute to this project please open a GitHub pull request.

Contact us

• Having questions about hara-ddiclient? Subscribe to the hara-dev mailing list and post a question!
• Having issues with hara-ddiclient? Please open a GitHub issue.

Third-Party Libraries

For information on the libraries used by this project see NOTICE.

Authors

• Daniele Sergio - Initial work - danielesergio.
• Andrea Zoleo
• Diego Rondini
• Alberto Battiston
• Saeed Rezaee

See also the list of contributors who participated in this project.

License

Copyright © 2017-2024, Kynetics, Inc.

Released under the EPLv2 License.