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

• Android 5.0 Lollipop (API 21) is the minimum required version for deployment

• The framework has been built primarily with Kotlin in mind

• The framework has been built with Gradle version 7.4.2 and Android gradle version 7.1.1

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.

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:

• initializeLock takes arguments as key and passkey to make sure the lock properly utilizes these resources to invoke desired action. Make sure to get it from the relevant TOMP endpoint.

• unlock invokes the unlock action of the specified lock.

• lock invokes the lock action of the specified lock.

• prepareEndRental invokes checking of the lock state including the extraLockCheck - necessary operation before ending rental to make sure the vehicle is safe from any misuse. In the case of lock being unlocked, this function will try to lock it as well. Note however that this does not end the rental. Remember to call the required endpoint on TOMP.

• finalizeLock makes sure any saved resources are cleaned from the cache and the bluetooth lock device gets disconnected. Make sure all of the lock handling is done at this point because without a new eKey it might not be possible to handle the lock again.

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

• Finish migration from realm to sqldelight — this version no longer depends on realm, which should decrease app size. To be able to keep eKeys for users which will update app during rentals it's advised to update to 1.2.0 first, and after grace period update to 1.3.0.

v1.2.0
2022-07-26

• Introduce UnlockCommandError and LockCommandError for unexpected errors during locking/unlocking instead of calling LockTimeout

• Fix wrong MTU size for sending commands to AXA lock v2 on some devices

• Introduce BluetoothUnauthorized error for cases when Bluetooth permissions are missing (Android 12+)

• Start migration from realm to sqldelight — this version still contains dependency to realm but migrates all ekeys to sqldelight and saves all new data there. To complete migration Lock Kit 1.3.0 version will be released soon.

v1.1.2
2021-12-02

• added support for the latest Android 12

v1.1.1
2021-12-01

• fixed potential issues of having duplicates while using the Donkey Lock Kit with other libraries

• fixed issue with ExtraLockCheck not emitting result when bluetooth got disabled

v1.1.0
2021-10-19

• now LockKit will use deviceName instead of bdAddress for all the bluetooth functions to enable easier input + aligns with iOS

v1.0.0
2021-09-09

• first stable release of the SDK