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 Summary

Modifier and Type	Method and Description
BleLock	getLock(byte[] physicalLockId) Returns the BLE lock representation of the lock with the specified lock ID.
BleLock	getLock(String physicalLockId) Returns the BLE lock representation of the lock with the specified lock ID.
Map<String,BleLock>	getLocks() Returns a list of nearby locks along with their Bluetooth address.
Observable<Map<String,BleLock>>	getLocksChangedObservable() Returns an Observable of a list of nearby locks along with their Bluetooth address.
boolean	isLockNearby(byte[] physicalLockId) Returns whether the Tapkey lock with the specified physical lock ID is nearby.
boolean	isLockNearby(byte[] physicalLockId, int rssiThreshold) Same as isLockNearby(byte[]), but with configurable RSSI threshold.
boolean	isLockNearby(String physicalLockId) Returns whether the Tapkey lock with the specified physical lock ID is nearby.
boolean	isLockNearby(String physicalLockId, int rssiThreshold) Same as isLockNearby(String), but with configurable RSSI threshold.
ObserverRegistration	startForegroundScan() Starts scanning for nearby Tapkey locks.

Method Detail

startForegroundScan

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.

Parameters:

physicalLockId - the lock's physical lock ID.

Returns:

the BleLock for the given physicalLockId or null, if the lock is not nearby.

getLock

BleLock getLock(byte[] physicalLockId)

Returns the BLE lock representation of the lock with the specified lock ID.

Parameters:

physicalLockId - the lock's physical lock ID.

Returns:

the BleLock for the given physicalLockId or null, if the lock is not nearby.

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

boolean isLockNearby(byte[] physicalLockId)

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

boolean isLockNearby(byte[] physicalLockId,
                     int rssiThreshold)

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.