search

DonkeyRepublic / lockkit-android

Donkey Lock Kit for Android
https://developer.donkey.bike/tomp/lockkit/docs/android/
3 stars 0 forks source link

readme

Donkey Lock Kit



Donkey Lock Kit is a Kotlin Android framework that enables interaction with BLE-enabled locks that Donkey Republic vehicles are equipped with. It is a supplement to Donkey Republic x TOMP to help aggregators fully integrate Donkey Republic services into their product. Purpose of the framework is to enable handling of bluetooth locks that TOMP cannot access online. Note that it also handles minimal server communication to Donkey for authentication and tracking purposes, however it does not communicate with TOMP and neither calls any major transactional requests. Make sure that all the required TOMP interactions are done according to the documentation.

Prerequisites

Donkey Lock Kit APIs are available after you authenticated with the SDK token received from Donkey Republic. It helps establish the secure usage of the framework and prevent wrong manipulation of the Donkey locks. Note that this SDK token is different from the SDK token that is used for server communication. Contact your representative at Donkey Republic to obtain the SDK token.

System requirements

Getting started

Donkey Lock Kit is available via MavenCentral repository. In order to apply the dependency, add the mavenCentral repository in the top-level gradle like this:


allProjects {
    repositories {
        mavenCentral() // for production ready releases
    }
}


Then add the Donkey Lock Kit dependency in the module-level gradle like this:


dependencies {
    implementation 'bike.donkey:lockkit:<version>'
}

Snapshots

For using beta releases of Donkey Lock Kit in your project, add the maven snapshot repository in the top-level gradle like this:


allProjects {
    repositories {
        maven { url 'https://s01.oss.sonatype.org/content/repositories/snapshots/' } // for beta versions (snapshots)
    }
}


Then add the Donkey Lock Kit dependency in the module-level gradle the same way as for the production release version. Note however that the beta release version number will always end with a suffix -SNAPSHOT. Make sure not to rely on beta releases too much since they can be removed and stop being available at any future time.

Bluetooth LE requirement

By default Donkey Lock Kit requires Bluetooth LE hardware. This can prevent some devices from installing the app in the Play Store. If Donkey Lock Kit is used for optional feature in your app, you can disable Bluetooth LE hardware requirement in AndroidManifest.xml:

    <uses-feature
        android:name="android.hardware.bluetooth_le"
        android:required="false"
        tools:replace="android:required" />

Usage

The framework exposes DonkeyLockKit Kotlin object that handles all the interaction with the Donkey Republic locks.

In order to interact with the vehicle locks, you must initialize the SDK with the SDK token provided to you by Donkey Republic:


DonkeyLockKit.initializeSdk(context = context, sdkToken = "MyDonkeyToken", onResult = { result ->
    // The result of the initialization will be available in the callback in case of debugging
    println(result)
})


Note that the initialization happens instantly and you are able to use the lock functions straight away. In the case error is thrown in the onResult callback - the SDK will be considered uninitialized and no further lock functions would be usable until the SDK is successfully authenticated again. If the SDK is uninitialized during the call of lock handling functions, UninitializedSdkError will be thrown.

Lock handling

For identifying the specific lock, lock device name is used and needs to be supplied for all lock functions as an argument. It is usually displayed in the following format AXA:C885D6B0F03113BCAC2F. Make sure to get it from the relevant TOMP endpoint.


In order for the lock device to execute actions - the framework uses eKeys that consist of key and passkey that are passed in initializeLock. This data is dynamic, cannot be reused and each device can have 1+ unique eKeys depending on number of uses and whether using one or more phone devices. Make sure to get eKey data from the relevant TOMP endpoint.


Each lock function of the framework has onResult callback to let you know asynchronously the outcome of the operation. Additionally, for unlock, lock and prepareEndRental there is also available onUpdate callback to let you know the ConnectionUpdate of the given operation.


These are the major functions regarding lock handling:


Following is the recommended sequence of lock handling:

  1. initializeLock - once per rental (if invoked more times, the sequence of the keys for the given lock might be out of order and might need refresh)
  2. unlocking and locking - up to 255 times together on one eKey (if more times is needed, after using all, please refresh eKeys and initializeLock again with a new eKey)
  3. prepareEndRental - just once before wanting to finish rental to make sure lock device is locked (it is okay to call it more than once)
  4. finish rental on TOMP - after successful prepareEndRental
  5. finalizeLock - after successful finish of the rental on TOMP

Configuration

In the need of supply additional configuration to the framework, DonkeyConfig is provided. Default configuration is set with Server Environment to LIVE and Log Level to DEBUG.

It is a val therefore it is not possible to update DonkeyConfig itself but only its internal variables:


    // example
    DonkeyLockKit.config.environment = DonkeyConfig.ServerEnvironment.TEST

    // example using apply
    DonkeyLockKit.config.apply {
        environment = DonkeyConfig.ServerEnvironment.TEST
        logLevel = DonkeyConfig.LogLevel.ERROR
    }


Note that it is only possible to update the DonkeyConfig values before calling of initializeSdk function.

Changelog

v1.3.0
2022-07-27

v1.2.0
2022-07-26

v1.1.2
2021-12-02

v1.1.1
2021-12-01

v1.1.0
2021-10-19

v1.0.0
2021-09-09