Via the Unit Controller the app can access available and nearby units, filter by type and command them to open.
To acquire the single instance of the Unit Controller call sdk.getUnitController()
The general status of the Unit Controller can be observed from the getStatus() method.
Possible values and their expected values are:
.open(iotUnit) when the controller is not on this state will throw IllegalStateExceptionThere’s only 1 method to get the IotUnits with parameters to filter the types.
unitController.getUnits(Availability, Sorting, IotUnit.Type?): LiveData<SimpleResponse<List<IotUnit>>>
getUnits() is queried at 7:59 AM. When the minute change the data will change to reflect the newly available door.iotUnit.isNearby() method to see if the unit is in reach.null: no filtering, return every type of unitTo open an IotUnit simply call the .open().
This method can only be called when the UnitController.Status is Ready.
In case the status is not ready, the returned Response will be failed with an IllegalStateException.
The Response of the .open() call contains two parameters:
- Response.data is the IotUnit this openable was resolved to
- Response.progress is an enum with the progress of the operation.
val cancelOpen = CancellationSignal()
fun onOpenButtonClicked() {
sdk.getUnitController()
.open(iotUnit, cancelOpen)
.observe(
lifecycleOwner,
Observer { response ->
// ... observe the progress, update UI
when (response.status) {
Response.Status.SUCCESS -> // ...
Response.Status.FAIL -> {
if(response.exception is UserCancelException) {
// the SDK successfully cancelled the operation as requested by the user
} else {
// check for other exception
}
}
Response.Status.EXECUTING -> // ...
}
}
)
}
fun onCancelButtonClicked() {
cancelOpen.cancel(UserCancelException("Canceling open of $iotUnit. User request"))
}
override fun onStop() {
// onStop cancel opening to avoid the UnitController to search (and be busy) forever
cancelOpen.cancel(Exception("Canceling open of $iotUnit. Activity stop"))
}
class UserCancelException(message:String): Exception(message:String)
The Openable interface marks classes that can be opened by the SDK. Currently that includes:
.getUnits() method can be called to open.The progress of the opening values are as follows:
opening.onProgress().observe(this, Observer {
when (it) {
OpeningProgress.SearchingNearby -> // sdk is trying to find the closest available unit to open
OpeningProgress.SearchingUnit -> // sdk is searching for one specific unit to open
OpeningProgress.Connecting -> // sdk is connecting/communicating with the unit
}
})
The opening.data will contain the IotUnit this opening is trying to open.
It’s important to remember thou, that whenever the progress of opening is SearchingNearby the IotUnit is not known and the data will be null.
The optional CancellationSignal object supplied to the open method can be managed however the client application wants.
A simple example is when there’s a dedicated opening screen and the app uses ViewModel, so the cancel would be called on exit that screen.
class OpeningViewModel : ViewModel() {
val cancellationSignal = CancellationSignal()
override onCleared() {
super.onCleared()
// cancel any `open` invoked by this view model
cancellationSignal.cancel(MyException()) // or just use the default CanceledException()
}
}
It’s important to understand and remember thou, that canceling is a “best attempt” and the opening might still be SUCCESS.
Whenever canceling happens, status will be changed to FAIL and the exception can be found on opening.exception. The default is CanceledException