Skip to content

Android ​

The SDK is one library. It shows no screen and no dialog: your app asks for the permissions, and your app shows the progress.

Requirements ​

  • A phone with Android 7.0 or later, and with Bluetooth Low Energy.
  • compileSdk 31 or later in your app.
  • Kotlin 2.1 or later in your build.

Add the SDK ​

Add the library to the build file of your app module.

kotlin
dependencies {
    implementation("ro.clevibox:sdk-android:0.1.0")
}

Before the first release

The library is not on Maven Central yet. Until then, Clevibox sends you the SDK files. Their README.md says how to add them to your build.

Permissions ​

The SDK declares its permissions in its own manifest, so your manifest needs no new line.

PermissionVersionWhy
BLUETOOTH_SCAN, BLUETOOTH_CONNECTAndroid 12 and laterThe SDK finds the lock and connects to it. The scan never serves to find the location of the phone, and the manifest says so.
ACCESS_FINE_LOCATION, BLUETOOTH, BLUETOOTH_ADMINAndroid 11 and olderAndroid needs the location permission for a Bluetooth scan there. The other two need no question to the member.
INTERNETAll versionsThe SDK calls Clevibox before each opening.

Your app asks the member for the Bluetooth permissions at run time. Ask when the member first comes to the screen of the locker, and say why.

kotlin
private val permissionRequest =
    registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) {}

private fun askForBluetooth() {
    val permissions = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        arrayOf(Manifest.permission.BLUETOOTH_SCAN, Manifest.permission.BLUETOOTH_CONNECT)
    } else {
        arrayOf(Manifest.permission.ACCESS_FINE_LOCATION)
    }
    permissionRequest.launch(permissions)
}

Set up ​

Call configure once, for example in onCreate of your Application class. It starts no Bluetooth and no network activity.

kotlin
import ro.clevibox.sdk.Clevibox
import ro.clevibox.sdk.CleviboxConfig
import ro.clevibox.sdk.LogLevel

Clevibox.configure(CleviboxConfig(logLevel = LogLevel.DEBUG))

LogLevel.DEBUG writes progress lines to Logcat while you develop. Leave it out in your release build: the default is LogLevel.NONE.

Check before an opening ​

checkReadiness tells you if an opening can work now. It shows nothing, and it asks the member for nothing.

kotlin
val readiness = Clevibox.checkReadiness()
if (!readiness.ready) {
    // Bluetooth is off, or a permission is missing.
}
FieldValues
readytrue when Bluetooth is on and no permission is missing.
bluetoothON, OFF, UNSUPPORTED or UNKNOWN.
missingPermissionsA list of BLUETOOTH_SCAN, BLUETOOTH_CONNECT and LOCATION.

The SDK makes the same check at the start of each call. A call that fails this check does not use up its grant.

Open the door ​

Get a grant from your server, and hand it to open. See Your server. The functions with a name like showProgress are your own.

kotlin
import ro.clevibox.sdk.Cancellable
import ro.clevibox.sdk.DoorListener
import ro.clevibox.sdk.DoorPhase
import ro.clevibox.sdk.DoorResult

val call: Cancellable = Clevibox.open(grant, object : DoorListener {
    override fun onPhase(phase: DoorPhase) {
        showProgress(phase)
    }

    override fun onFinished(result: DoorResult) {
        when (result) {
            DoorResult.Opened -> showOpened()
            DoorResult.Cancelled -> showIdle()
            is DoorResult.Failed -> showFailure(result.error)
        }
    }
})

onFinished comes exactly once, as the last callback. Both callbacks arrive on the main thread.

The phases ​

PhaseWhat the SDK does
REDEEMINGIt checks the grant with Clevibox.
CONNECTINGIt looks for the lock, and it connects.
VERIFYINGIt makes sure that it reached the right lock.
OPENINGIt sends the command that opens the door.
DONEThe lock took the command.

CONNECTING can come a second time in one call. When the link to the lock fails before the open command goes out, the SDK connects once more by itself.

The result ​

ResultMeaning
DoorResult.OpenedThe lock opened. The member can pull the door open now.
DoorResult.CancelledYour app cancelled the call.
DoorResult.FailedThe call failed. error has a code, a message for a developer, and retryable. See Error codes.

Rules ​

  • One grant serves one call. For a new attempt or a second opening, get a new grant from your server.
  • One call runs at a time. A second call fails at once with OPERATION_IN_PROGRESS. So lock your Open button while a call runs.
  • Keep your screen up until onFinished.
  • call.cancel() stops a running call. It ends with DoorResult.Cancelled.

After the door opens ​

The latch comes back by itself after about 5 seconds. The member opens the door in that time, and pushes it shut later by hand. Then the door is locked again.

The lock cannot tell if its door is shut. So Opened says that the lock opened, and it says nothing about the door after that. Tell your members to push the door shut.

Read the latch ​

readStatus connects to the lock, reads the state of the latch once, and disconnects. Most apps do not need it. It needs a grant of its own.

kotlin
import ro.clevibox.sdk.StatusResult

Clevibox.readStatus(grant) { result ->
    when (result) {
        is StatusResult.Read -> showLatch(result.status.latchOut)
        is StatusResult.Failed -> showFailure(result.error)
    }
}

latchOut is true when the latch is out. That is its usual state: a door that is shut is locked then.