Implementing onTouch

BlueID onTouch

The onTouch technology allows the user to open a lock or pass through a turnstile just by presenting the phone to a reader. There is no need to open an app and to press a button anymore which leads to a shorter waiting time, a higher throughput and more convenience for the user.

Adding onTouch support to an app is fairly easy: Just start it and implement a callback that handles feedback. If you want, you can add some options.

Talking about locks, only permanently-powered readers that support both Bluetooth Smart and NFC communication with smartphones support the BlueID onTouch technology! Please ask your BlueID sales representive for more information.

Supported platforms

BlueID onTouch is supported at the moment by locks who run on the nRF52 platform, since it's the only one where we are able to configure the BLE chip. Supported devices: - UZ Wallreaders - teoretically all UZ locks can be configured for onTouch, but the high battery consumption make it advisable against any battery powered lock.

Advertised services

A mobile device can distinguish a classic BlueID lock from an onTouch lock by the advertised service UUID. The default classic UUID is

00005301-0000-002a-426c-756549442a00

while when a lock is in onTouch mode, this is changed to

00005301-0010-002a-426c-756549442a00

If set up, automatic command execution will only work with the latter ones. But this doesn't mean that classical manual command executions don’t work anymore if the lock was in onTouch mode! So it’s up to the app developer to allow or prevent manual command execution for onTouch locks.

How do BLE connections work

After the BLE connection to a device was established, the lock also measures the RSSI value by itself. Only if the mobile device reaches a certain threshold within a certain amount of time, the communication process starts, otherwise the connection was dropped.

This connection verification process takes a few hundred milliseconds. During that time, the connection handle is not available for other mobile devices. So in case that the connection gets eventually dropped, the lock cann't be used for this time if only one connection handle is supported. But exactly this is the case for battery-powered locks to maximize the battery lifetime. The nRF52832 is configured to support up to 3 concurrent BLE links (NRF_SDH_BLE_PERIPHERAL_LINK_COUNT) which is supported by the U&Z wallreader. If power is no issue, the number of concurrent links is only limited by the RAM available, thus we can, for example, configure the nRF52840 to allow 7 concurrent links.

Implementing the callback

When you implement your app for iOS, the callback is simply BlueIDAccessOnTouchDelegate which you can nicely integrate in your controller or elsewhere and directly access, for example, visual elements.

On Android it's a bit different and a bit more complicated due to Android's runtime architecture. Unfortunately, you can't simply implement the methods of AccessOnTouchCallback, but you have to create a separate class for this and hand this over to the BlueID SDK. This means that you need a mechanism to communicate with your activity. In the demo application, this is done using intents.

Common callback methods

devicesDiscovered

Once started, BlueID onTouch scans continuously for BlueID devices in your vicinity that you have got permissions for. By default, the SDK informs the callback every 500 ms about new devices. You change that by using setDeviceReportDelay (Android) or setting reportDelayMilliseconds (iOS).

selectCommandForLock

If this method returns null (Android) or nil (iOS), the default command "tokn" is taken. Normally, you don't have to adjust this but it makes sense to set it, for example, if you want to implement some maintenance functionality in your app.

commandExecutionStarted

This method gets called when an onTouch command execution is started in the background.

commandExecutionResult

This method gets called when an onTouch command execution was finished. If it was successful, you receive an command execution response (like if you executed the command manually) or an error object.

Android specific callback

If your app runs on a device with an Android version prior to 8, it's required to show a permanent notification to the user in order to keep the app alive. Though it's not guaranteed that the operating system will not kill the app,

By implementing the getLegacyForegroundNotification callback, the BlueID SDK can take care of showing this notification to the user.

Triggering a command execution

On iOS-based smartphones, Bluetooth Smart is the way to go whereas on Android, as long as the mobile device supports NFC, NFC is the preferred and required interface due to some serious performance bugs in the Android Bluetooth implementation. Although on Android, you as a developer can override the choice of the SDK when starting onTouch.

To do a command execution with onTouch, you have to put your phone near to the reader. While it is quite clear what that means for NFC, we have to dig a bit deeper to understand this using Bluetooth and the configuration options we have.

When using wireless communication protocols, like Bluetooth, the RSSI values indicates the signal strength, which gives a very rough estimation of the distance between a sender and a receiver. As a general rule, the signal strength value gets higher the nearer the objects come to each other and the possible values range from 0 (nearest distance) to -100 (farthest distance).

BlueID onTouch comes preconfigured with reasonable default values and sets the threshold for a command execution attempt via Bluetooth to -60 by default. This means, the RSSI value the smartphone measures must be -60 or higher. It then connects to the reader which itself reads the RSSI value to make sure the smartphone is really close to it and continues the command execution. Otherwise, it will just drop the connection.

If the threshold is configured to be very low, like -80 or even lower, it means that the smartphone tries to connect very early, even if it might be rejected by the reader, but this may lead to a shorter command execution duration. On the other hand if the threshold is too high, e.g. -40 or higher, it means that in worst case, the command execution will never happen because the reader is in a metallic case or the NFC antenna of the phone is positioned badly. So choosing the right threshold is always a tradeoff between distance and command execution speed and dependent on the use case.

Configuration options

BlueID onTouch gives you freedom to completely configure every aspect of it in order to meet your requirements. This table gives you an overview:

Function	Android	iOS	Default value
set preferred communication channel for onTouch (BLE or NFC)	setChannel	not applicable	depends on phone
set required RSSI threshold if app is in foreground	setRSSIThresholdInForeground	rssiThresholdInForeground	-60
set required RSSI threshold if app is in background	setRSSIThresholdInBackground	rssiThresholdInBackground	-60
set required RSSI threshold	setRSSIThreshold	rssiThreshold	-60
enable/disable automatic onTouch command execution	setOnTouchExecutionEnabled	automaticOnTouchCommandExecution	true
enable/disable scan for BlueID onTouch devices	setScanForBlueIDonTouchDevicesEnabled	scanForOnTouchDevices	true
enable/disable scan for standard BlueID devices	setScanForBlueIDDevicesEnabled	scanForStandardDevices	true
set interval for devicesDiscovered	setDeviceReportDelay	reportDelayMilliseconds	500
minimum delay after an onTouch command execution for the next one on the same lock	setDelayAfterSuccess	delaySecondsAfterSuccess	2000
minimum delay after a failed onTouch command execution for the next one on the same lock	setDelayAfterFailure	delayAfterFailureMilliseconds	500
mitigation for Android bug: minimum delay after successful onTouch execution in background with Bluetooth	setDelayAfterSuccessBackground	not applicable	20000

App-specific configuration for onTouch

Android

The BlueID SDK for Android library comes with a Manifest.xml that already contains all required settings. But when onTouch is started, it might fail with a MissingOnTouchRequirementException. It is then up to you as the app developer to ask the user for the appropriate permissions. The BlueID Example App gives you a blueprint of what you have to do.

iOS

iOS requires that your app declares that it always requires Bluetooth and that it requires it also in the background. These settings have to be done in the "Custom iOS Target Properties". Only if this was declared and the user accepts it, onTouch works flawlessly.

The following settings have to be done:

Name	Key	Value
Privacy - Bluetooth Always Usage Description	NSBluetoothAlwaysUsageDescription	Required for BlueID to work
Required background modes	UIBackgroundModes	bluetooth-central