2.0.0 - Updated BLE API and support for pairing/bonding

@mikaelkindborg mikaelkindborg released this Oct 12, 2016 · 3 commits to master since this release

This is a major update of the BLE plugin for iOS and Android.

New in this release

  • Extended BLE plugin API that is easier to use. This reduces the need for external add-on libraries like EasyBLE.
  • Support for automatic service discovery.
  • Advertisement data available both on Android and iOS.
  • Support for pairing/bonding.
  • New functions: connectToDevice, getBondedDevices, getBondState, bond, unbond.
  • Use connectToDevice rather than the low-level function connect.
  • Functions now accept a device object in place of a low-level handle. Handles can still be used for backwards compatibility.

Known issues

  • On Android the pairing dialog is sometimes not shown when calling bond, and state 'unbonded' is returned. Try calling bond again if this happens.
  • On iOS pairing dialog may mot be shown on connect, resulting in that protected characteristics can not be read/written. Call close on the device and call connectToDevice again if this happens.
  • On Android connect may fail with error 133 (or other errors). Try to wait a little (500ms) and call connectToDevice again if this happens. Use setTimeout and the UI will still be responsive and you can show status info etc. See this demo app for an example: https://github.com/evothings/cordova-ble/blob/master/examples/core-api/hexiwear-bonding/app.js


About pairing/bonding

"Pairing" and "bonding" usually refer to the same thing, but one distinction that is made is that "pairing" is the authentication with the device, and "bonding" is storing the device in a list of known devices. In the BLE API the term "bond" is used.

On iOS bonding cannot be requested programmatically, iOS automatically shows the pairing dialog asynchronously when connectToDevice is called. The connect success callback is called while pairing is in progress, and the only way to tell if the device is bonded is by reading (or writing) a protected characteristic. Calling readCharacteristic on a protected characteristic will not return until pairing is complete or cancelled. When the device is bonded the success callback of readCharacteristic is called, if pairing fails or is cancelled the error callback is called. This method also works on Android.

On iOS, if the user has cancelled the pairing dialog, call close on the device and call connectToDevice again to show the pairing dialog to the user.

On iOS, when connected, getBondedDevices and getBondState wrongly report the device as bonded even though pairing is not complete (this is native iOS behaviour). But before connectToDevice is called, the bond state is correctly reported.

On iOS bonded device are not reported on BLE scan. Use getBondedDevices to determine if the device is bonded, and call connectToDevice to connect if it is, without doing a scan. Android reports bonded devices on scan, however.

On Android one can request bonding programmatically, using the bond function. This function will return state 'bonded' when successful. To make the same application code work on both Android and iOS, bond and unbond are also implemented on iOS, but there the call the success callback with state 'unknown'. The reason for this design is to avoid the need for explicit platform checks in the code.

For an example of using the above programming techniques, see this file: https://github.com/evothings/cordova-ble/blob/master/examples/core-api/hexiwear-bonding/app.js