2.0.1 - Bugfix release

This release fixes a bug that made scanning for and reading only specific services not work as expected. Rather than reading only the specified services, all services where read.

2.0.0 - Updated BLE API and support for pairing/bonding

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

Documentation

• 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

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

1.4.4 - Android bugfix for device disconnect

This version fixes a bug on Android when a disconnecting from a BLE device.

1.4.3 - Support for writeCharacteristicWithoutResponse also on iOS

The iOS version of the plugin now supports the function writeCharacteristicWithoutResponse. This function is also available on Android (added in a previous release).

Testing has shown that on iOS using writeCharacteristicWithoutResponse fails with a characteristic that does not support write without response (expected behaviour). On Android however, writing a characteristic that does not support write without response is observed to work (this seems to be the behaviour of the Android BLE implementation).

1.4.2 - Bugfix for enableNotification on Android

This version of the plugin contains an update that fixes a bug in enableNotification. The options parameter did not work as expected.

It now works to set the last options parameter as follows; setting writeConfigDescriptor: false will turn off automatic writing of the config descriptor:

evothings.ble.enableNotification(
    deviceHandle,
    characteristic.handle,
    function(data)
    {
        console.log('BLE characteristic data: ' + evothings.ble.fromUtf8(data));
    },
    function(errorCode)
    {
        console.log('BLE enableNotification error: ' + errorCode);
    },
    { writeConfigDescriptor: false });

This also works for disableNotification:

evothings.ble.disableNotification(
    deviceHandle,
    characteristic.handle,
    function()
    {
        console.log('BLE characteristic notification disabled');
    },
    function(errorCode)
    {
        console.log('BLE disableNotification error: ' + errorCode);
    },
    { writeConfigDescriptor: false });

Disabling automatic writing of the notification/indication config descriptor can be useful if the application has special requirements.

Setting writeConfigDescriptor: true turns on automatic writing of the config descriptor. This is the default if you leave out the options parameter, like this:

evothings.ble.enableNotification(
    deviceHandle,
    characteristic.handle,
    function(data)
    {
        console.log('BLE characteristic data: ' + evothings.ble.fromUtf8(data));
    },
    function(errorCode)
    {
        console.log('BLE enableNotification error: ' + errorCode);
    });

This should work for most applications.

The high-level EasyBLE library also has support for specifying the options parameter in function enableServiceNotification(). This library is available here:

https://github.com/evothings/evothings-libraries/blob/master/libs/evothings/easyble/easyble.dist.js

1.4.1 - Bugfix release for Android

This release has an important fix for a bug that prevented automatic writing of the config descriptor when enabling notifications.

Now the config descriptor should be properly set when enabling notifications.

1.4.0 - Support for indications on Android

This version contains support for indications on Android and a bug fix for enabling Bluetooth on Android (fixes null-pointer runtime error).

The plugin now checks if a characteristic has the notify or the indicate property set, and writes the corresponding value to the config descriptor when enabling notifications.

There is a new config parameter for functions enableNotification and disableNotification that allows turning off automatic writing of the config descriptor. This is useful for applications that want to have full control of writing the config descriptor on Android.

Updated documentation comments in ble.js:

/** Request notification or indication on changes to a characteristic's value.
* This is more efficient than polling the value using readCharacteristic().
* This function automatically detects if the characteristic supports 
* notification or indication. 
*
* <p>Android only: To disable this functionality and write
* the configuration descriptor yourself, supply an options object as
* last parameter, see example below.</p>
*
* @param {number} deviceHandle - A handle from {@link connectCallback}.
* @param {number} characteristicHandle - A handle from {@link characteristicCallback}.
* @param {dataCallback} win - Called every time the value changes.
* @param {failCallback} fail - Error callback.
* @param {object} options - Android only: Optional object with options. 
Set field writeConfigDescriptor to false to disable automatic writing of 
notification or indication descriptor value. This is useful if full control 
of writing the config descriptor is needed.
*
* @example
// Example call:
evothings.ble.enableNotification(
    deviceHandle,
    characteristic.handle,
    function(data)
    {
        console.log('BLE characteristic data: ' + evothings.ble.fromUtf8(data));
    },
    function(errorCode)
    {
        console.log('BLE enableNotification error: ' + errorCode);
    });

// To disable automatic writing of the config descriptor 
// supply this as last parameter to enableNotification:
{ writeConfigDescriptor: false }
*/

/** Disable notification or indication of a characteristic's value.
*
* @param {number} deviceHandle - A handle from {@link connectCallback}.
* @param {number} characteristicHandle - A handle from {@link characteristicCallback}.
* @param {emptyCallback} win - Success callback.
* @param {failCallback} fail - Error callback.
* @param {object} options - Android only: Optional object with options. 
Set field writeConfigDescriptor  to false to disable automatic writing of 
notification or indication descriptor value. This is useful if full control 
of writing the config descriptor is needed.
*
* @example
// Example call:
evothings.ble.disableNotification(
    deviceHandle,
    characteristic.handle,
    function()
    {
        console.log('BLE characteristic notification disabled');
    },
    function(errorCode)
    {
        console.log('BLE disableNotification error: ' + errorCode);
    });

// To disable automatic writing of the config descriptor 
// supply this as last parameter to enableNotification:
{ writeConfigDescriptor: false }
*/

Here is how you would call enableNotification with the options object set to turn off automatic write of the config descriptor:

evothings.ble.enableNotification(
    deviceHandle,
    characteristic.handle,
    function(data)
    {
        console.log('BLE characteristic data: ' + evothings.ble.fromUtf8(data));
    },
    function(errorCode)
    {
        console.log('BLE enableNotification error: ' + errorCode);
    },
    { writeConfigDescriptor: false });

1.3.2 - Modernized the Android permission code

This version supports the new Android permissions scheme, used by Android 6.

1.3.1 - Plugin version for Evothings Viewer 1.4

This is the plugin version shipped with Evothings Viewer 1.4.

New in this version:

• Removed debug logging.

1.3.0 - Android: Updates for Android 6.0

This release is an update for update for Android 6.0 (API Level 23).

Plugin now asks user for permission when calling startScan.

Note that in addition, the user has to turn on Location in the Settings application.