Theme
iOS
The SDK is one framework, CleviboxSDK. It shows no screen and no dialog: your app asks for Bluetooth, and your app shows the progress.
Requirements
- An iPhone or iPad with iOS 15.0 or later.
- A real device for each test of an opening. The simulator has no Bluetooth.
- An app that builds for iOS. The SDK has no build for the Mac or for Vision Pro.
Add the SDK
The SDK is a Swift package.
- In Xcode, choose File > Add Package Dependencies.
- Enter the address
https://github.com/clevibox/clevibox-ios. - Add the product
CleviboxSDKto the target of your app.
Before the first release
The package is not public yet. Until then, Clevibox sends you the SDK files. Their README.md says how to add them to your project.
A new app from a current Xcode template can also build for the Mac and for Vision Pro. Such a build stops with the text "no library for this platform was found in CleviboxSDK.xcframework". Then remove those destinations from the target of your app.
Bluetooth permission
Add the key NSBluetoothAlwaysUsageDescription to your Info.plist, with a text that says why your app uses Bluetooth. Without it, iOS stops the app at its first use of Bluetooth.
xml
<key>NSBluetoothAlwaysUsageDescription</key>
<string>The app uses Bluetooth to open your locker.</string>iOS shows its Bluetooth dialog when an app creates its first Bluetooth manager. The SDK creates none before the member has allowed Bluetooth, so the SDK never causes that dialog. Your app picks the moment: create a manager when the member first comes to the screen of the locker.
swift
import CoreBluetooth
final class BluetoothPermission: NSObject, CBCentralManagerDelegate {
private var manager: CBCentralManager?
/// Shows the Bluetooth dialog of iOS, when the member has not answered it yet.
func askOnce() {
guard manager == nil, CBCentralManager.authorization == .notDetermined else { return }
manager = CBCentralManager(
delegate: self,
queue: nil,
options: [CBCentralManagerOptionShowPowerAlertKey: false]
)
}
func centralManagerDidUpdateState(_ central: CBCentralManager) {}
}Keep the object for the life of your app. It never scans and never connects.
Set up
Call configure once, at the start of your app. It starts no Bluetooth and no network activity.
swift
import CleviboxSDK
Clevibox.shared.configure()While you develop, the SDK can write progress lines to the console of Xcode:
swift
Clevibox.shared.configure(config: CleviboxConfig(logLevel: .debug, apiBaseUrl: nil))apiBaseUrl stays nil. It serves the tests of Clevibox.
Check before an opening
checkReadiness tells you if an opening can work now. It shows nothing, and it asks the member for nothing.
swift
let readiness = Clevibox.shared.checkReadiness()
if !readiness.ready {
// Bluetooth is off, or the member has not allowed it.
}| Field | Values |
|---|---|
ready | true when Bluetooth is on and the member has allowed it. |
bluetooth | .on, .off, .unauthorized, .unsupported or .unknown. |
missingPermissions | It holds .bluetooth until the member has allowed Bluetooth. |
- Before the member has answered the dialog,
bluetoothis.unknown. - After the member has blocked Bluetooth,
bluetoothis.unauthorized. iOS does not show the dialog a second time, so send the member to the settings of your app.
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.
swift
import CleviboxSDK
final class DoorEvents: DoorListener {
func onPhase(phase: DoorPhase) {
showProgress(phase)
}
func onFinished(result: DoorResult) {
if result is DoorResultOpened {
showOpened()
} else if result is DoorResultCancelled {
showIdle()
} else if let failed = result as? DoorResultFailed {
showFailure(failed.error)
}
}
}
let call = Clevibox.shared.open(grant: grant, listener: DoorEvents())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.
Each value has a name with its name in capitals, for example "CONNECTING". The same is true for an error code: error.code.name is "BLUETOOTH_OFF" for ErrorCode.bluetoothOff.
The result
| Result | Meaning |
|---|---|
DoorResultOpened | The lock opened. The member can pull the door open now. |
DoorResultCancelled | Your app cancelled the call. |
DoorResultFailed | 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. iOS pauses an app in the background, and a paused call ends only when the app is back. call.cancel()stops a running call. It ends withDoorResultCancelled.- The SDK needs no background mode.
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 DoorResultOpened 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.
swift
Clevibox.shared.readStatus(grant: grant) { result in
if let read = result as? StatusResultRead {
showLatch(read.status.latchOut)
} else if let failed = result as? StatusResultFailed {
showFailure(failed.error)
}
}latchOut is true when the latch is out. That is its usual state: a door that is shut is locked then.
