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:
connectToDevicerather than the low-level function
- Functions now accept a device object in place of a low-level handle. Handles can still be used for backwards compatibility.
- On Android the pairing dialog is sometimes not shown when calling
bond, and state
'unbonded'is returned. Try calling
bondagain if this happens.
- On iOS pairing dialog may mot be shown on connect, resulting in that protected characteristics can not be read/written. Call
closeon the device and call
connectToDeviceagain if this happens.
- On Android connect may fail with error 133 (or other errors). Try to wait a little (500ms) and call
connectToDeviceagain 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
- File README.md contains an overview of the updated API.
- For reference documentation see file ble.js until generated documentation has been published on the Evothings web site.
- Example apps that demo the updated API are found here: https://github.com/evothings/cordova-ble/blob/master/examples/core-api/
- BLE API Guide: http://evothings.com/doc/tutorials/evothings-ble-api-guide.html
"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,
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,
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