Package com.tapkey.mobile.ble

Interface BleLockScanner

  • public interface BleLockScanner
    The BLE (Bluetooth Low Energy) lock scanner provides means to scan for Tapkey locks via BLE. It can be used to scan for nearby locks and to determine whether a specific lock is nearby. Use TapkeyServiceFactory to retrieve an instance of BleLockScanner.

    • Method Detail

      • startForegroundScan

        @RequiresPermission(allOf={"android.permission.BLUETOOTH_SCAN","android.permission.BLUETOOTH_CONNECT"})
ObserverRegistration startForegroundScan()
        Starts scanning for nearby Tapkey locks. Results can be retrieved using getLocks() and getLocksChangedObservable().
        Returns:
        an observer registration that can be used to stop scanning.

      • getLocks

        Map<String,​BleLock> getLocks()
        Returns a list of nearby locks along with their Bluetooth address. The Bluetooth address is a 48-bit identifier represented as a String of 6 bytes in hexadecimal separated by colons. For example, "00:11:22:AA:BB:CC". The lock is returned as an object of BleLock.
        Returns:
        a Map with a String representing the Bluetooth address as key, and an object of BleLock as value.
        See Also:
        BleLock

      • getLock

        BleLock getLock​(String physicalLockId)
        Returns the BLE lock representation of the lock with the specified lock ID. If multiple Bluetooth devices advertise the same lock id then the one with the greatest RSSI value will be returned.
        Parameters:
        physicalLockId - the lock's physical lock ID.
        Returns:
        the BleLock for the given physicalLockId or null, if the lock is not nearby.

      • getLock

        @Deprecated
BleLock getLock​(byte[] physicalLockId)
        Deprecated.
        Use getLock(String) instead.
        Returns the BLE lock representation of the lock with the specified lock ID. If multiple Bluetooth devices advertise the same lock id then the one with the greatest RSSI value will be returned.
        Parameters:
        physicalLockId - the lock's physical lock ID.
        Returns:
        the BleLock for the given physicalLockId or null, if the lock is not nearby.

      • getLocks

        List<BleLock> getLocks​(String physicalLockId)
        Returns a list of BLE locks advertising the specified lock id. If multiple locks nearby advertise the specified lock id, then all of these locks will be returned and ordered by their RSSI value in descending order. I.e. the device with the greatest value representing the device with the strongest signal will come first.
        Parameters:
        physicalLockId - the lock's physical lock ID.
        Returns:
        the list of BleLock for the given physicalLockId. May contain zero, one or multiple entries.

      • getLocks

        @Deprecated
List<BleLock> getLocks​(byte[] physicalLockId)
        Deprecated.
        Use getLocks(String) instead.
        Returns a list of BLE locks advertising the specified lock id. If multiple locks nearby advertise the specified lock id, then all of these locks will be returned and ordered by their RSSI value in descending order. I.e. the device with the greatest value representing the device with the strongest signal will come first.
        Parameters:
        physicalLockId - the lock's physical lock ID.
        Returns:
        the list of BleLock for the given physicalLockId. May contain zero, one or multiple entries.

      • isLockNearby

        boolean isLockNearby​(String physicalLockId)
        Returns whether the Tapkey lock with the specified physical lock ID is nearby. The physicalLockID parameter takes a base64-encoded representation of the lock's physical lock ID.
        Parameters:
        physicalLockId - the lock's physical lock ID.
        Returns:
        true if the lock with the specified ID is nearby, false if not.

      • isLockNearby

        @Deprecated
boolean isLockNearby​(byte[] physicalLockId)
        Deprecated.
        Use isLockNearby(String) instead.
        Returns whether the Tapkey lock with the specified physical lock ID is nearby. The physicalLockID parameter takes the lock ID in byte[] representation.
        Parameters:
        physicalLockId - the lock's physical lock ID.
        Returns:
        true if the lock with the specified ID is nearby, false if not.

      • isLockNearby

        boolean isLockNearby​(String physicalLockId,
                     int rssiThreshold)
        Same as isLockNearby(String), but with configurable RSSI threshold. If the specified lock is discovered with an RSSI below rssiThreshold, it will not be reported as nearby. This method can be used to filter out locks with weak signal strength.
        Parameters:
        physicalLockId - the lock's physical lock ID.
        rssiThreshold - the RSSI threshold for discovered locks to be reported as nearby. The valid range is [-127, 126] but the actual RSSI range as reported by the OS depends on the respective hardware and Bluetooth stack.
        Returns:
        true if the lock with the specified ID is nearby, false if not.
        See Also:
        isLockNearby(String)

      • isLockNearby

        @Deprecated
boolean isLockNearby​(byte[] physicalLockId,
                     int rssiThreshold)
        Deprecated.
        Use isLockNearby(String, int) instead.
        Same as isLockNearby(byte[]), but with configurable RSSI threshold. If the specified lock is discovered with an RSSI below rssiThreshold, it will not be reported as nearby. This method can be used to filter out locks with weak signal strength.
        Parameters:
        physicalLockId - the lock's physical lock ID.
        rssiThreshold - the RSSI threshold for discovered locks to be reported as nearby. The valid range is [-127, 126] but the actual RSSI range as reported by the OS depends on the respective hardware and Bluetooth stack.
        Returns:
        true if the lock with the specified ID is nearby, false if not.
        See Also:
        isLockNearby(byte[])

      • getLocksChangedObservable

        Observable<Map<String,​BleLock>> getLocksChangedObservable()
        Returns an Observable of a list of nearby locks along with their Bluetooth address. The observable will fire every time a new lock is discovered or a lock disappeared.
        Returns:
        an observable that returns a Map of BleLocks with their Bluetooth addresses as keys.