Unit Controller
Unit Controller
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()
Unit Controller Status
The general status of the Unit Controller can be observed from the getStatus() method.
Possible values and their expected values are:
- SdkNotReady: Check the SDK status. The unit controller can only operate when the SDK is ready
- Ready: The SDK is ready and can be used to control units. A call to
.open(iotUnit) when the controller is not on this state will result in a IllegalStateException
- NoLocationPermission: It’s necessary to have location permission for the controller to scan for nearby IotUnits
- LocationIsOff: It’s necessary for the location to be on in the device settings for the controller to scan for nearby IotUnits
- BluetoothIsOff: It’s necessary for bluetooth to be turned on for the controller to scan for nearby IotUnits
- BluetoothError: There was an error reported by the Bluetooth radio. The error code is inside available inside this object
- Busy: The controller is busy opening a unit after it was requested.
Get Units
There’s only 1 method to get the IotUnits with parameters to filter the types.
unitController.getUnits(Availability, Proximity, IotUnit.Type?): LiveData<SimpleResponse<List<IotUnit>>>
Availability
- All: every unit the user can have access to, regardless of specific times or bookings
- AvailableNow: only the units the user can access at the moment. Takes in consideration opening times and if the unit is booked now. The LiveData will be updated when availability changes. For example: “Door A” availability starts at 8:00 AM and
getUnits() is queried at 7:59 AM. When the minute change the data will change to reflect the newly available door.
Proximity
- All: every unit, regardless of the distance to the user
- Nearby: this will trigger the SDK to actively execute NFC scans and respond only units in range
IotUnit.Type
null: no filtering, return every type of unit- Type.DOOR: returns only doors
- Type.LOCKER_BOX: returns only locker boxes
Refreshing
Calling the SDK method to refresh (sdk.refresh()) will execute API calls to the backend to refresh the LiveData. The Response status will change to executing (with the old values still available in .data field) and it will get updated once the API calls succeeded.
Open an IotUnit
To open an IotUnit simply call the .open() method:
val opening : Opening = unitController.open(openable)
Java
Opening opening = unitController.open(openable);
Openable
The Openable interface marks classes that can be opened by the SDK. Currently that includes:
- IotUnit: any unit returned by the
.getUnits() method can be called to open.
- OnTap: this object is received when the SDK detects a “tap” action on the Sensorberg gateway. See Tap handling
Opening
The Opening object returned by the .open() method is a LiveData<Response<IotUnit, Opening.Progress>> that also implements the Cancelable interface.
One way to observe just the progress, using the extensions utilities is shown below:
opening.onProgress().observe(this, Observer {
when (it) {
Opening.Progress.SearchingNearby -> // sdk is trying to find the closest available unit to open
Opening.Progress.SearchingUnit -> // sdk is searching for one specific unit to open
Opening.Progress.Connecting -> // sdk is connecting/communicating with the unit
}
})
Java
ResponseExtensionsKt.onProgress(opening).observe(this, new Observer<Opening.Progress>() {
@Override public void onChanged(@Nullable Opening.Progress progress) {
if (progress == null) return;
switch (progress) {
case SearchingNearby: // sdk is trying to find the closest available unit to open
break;
case SearchingUnit: // sdk is searching for one specific unit to open
break;
case Connecting: // sdk is connecting/communicating with the unit
break;
}
}
});
To observe progress directly on the Opening object
Kotlin
opening.observe(this, Observer {
it?.progress?.let { progress ->
when (progress) {
Opening.Progress.SearchingNearby ->
Opening.Progress.SearchingUnit ->
Opening.Progress.Connecting ->
}
}
})
Java
opening.observe(this, new Observer<Response<IotUnit, Opening.Progress>>() {
@Override public void onChanged(@Nullable Response<IotUnit, Opening.Progress> response) {
if (response != null &&
response.getStatus() == Response.Status.EXECUTING &&
response.getProgress() != null) {
switch (response.getProgress()) {
case SearchingNearby:
break;
case SearchingUnit:
break;
case Connecting:
break;
}
}
}
});
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.
Canceling
To cancel an opening simply call its method .cancel() method, with an optional exception.
opening.cancel() // default is CanceledException
opening.cancel(MyException("message")) // using a custom exception
Java
opening.cancel(CanceledException()) // or any custom exception
It’s important to remember thou, that canceling is a “best attempt” and the opening might still be SUCCESS.
Whenever canceling succeeds, status will be changed to FAIL and the exception can be found on opening.exception. The default on Kotlin is CanceledException