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>>>


  • 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.


  • 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


  • null: no filtering, return every type of unit
  • Type.DOOR: returns only doors
  • Type.LOCKER_BOX: returns only locker boxes


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)


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


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
To observe progress directly on the Opening object

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.


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

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