Theme
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.
compileSdk31 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.
| Permission | Version | Why |
|---|---|---|
BLUETOOTH_SCAN, BLUETOOTH_CONNECT | Android 12 and later | The 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_ADMIN | Android 11 and older | Android needs the location permission for a Bluetooth scan there. The other two need no question to the member. |
INTERNET | All versions | The 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.
}| Field | Values |
|---|---|
ready | true when Bluetooth is on and no permission is missing. |
bluetooth | ON, OFF, UNSUPPORTED or UNKNOWN. |
missingPermissions | A 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
| Phase | What the SDK does |
|---|---|
REDEEMING | It checks the grant with Clevibox. |
CONNECTING | It looks for the lock, and it connects. |
VERIFYING | It makes sure that it reached the right lock. |
OPENING | It sends the command that opens the door. |
DONE | The 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
| Result | Meaning |
|---|---|
DoorResult.Opened | The lock opened. The member can pull the door open now. |
DoorResult.Cancelled | Your app cancelled the call. |
DoorResult.Failed | The 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 withDoorResult.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.
