Bluetooth Low Energy (BLE) Central plugin for Apache Cordova (aka PhoneGap)
Clone or download
Pull request Compare This branch is 3 commits ahead, 231 commits behind don:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
src
tests
www
.gitignore
CHANGES.txt
LICENSE.txt
README.md
plugin.xml

README.md

Bluetooth Low Energy (BLE) Central Plugin for Apache Cordova

This plugin enables communication between a phone and Bluetooth Low Energy (BLE) peripherals.

The plugin provides a simple JavaScript API for iOS and Android.

  • Scan for peripherals
  • Connect to a peripheral
  • Read the value of a characteristic
  • Write new value to a characteristic
  • Get notified when characteristic's value changes

Advertising information is returned when scanning for peripherals. Service, characteristic, and property info is returned when connecting to a peripheral. All access is via service and characteristic UUIDs. The plugin manages handles internally.

Simultaneous connections to multiple peripherals are supported.

See the examples for ideas on how this plugin can be used.

Supported Platforms

  • iOS
  • Android (4.3 or greater)

Installing

Install with Cordova CLI

$ cd /path/to/your/project
$ cordova plugin add com.emeth.cordova.ble

API

Methods

scan

Scan and discover BLE peripherals.

ble.scan(services, seconds, success, failure);

Description

Function scan scans for BLE devices. The success callback is called each time a peripheral is discovered. Scanning automatically stops after the specified number of seconds.

{
    "name": "TI SensorTag",
    "id": "BD922605-1B07-4D55-8D09-B66653E51BBA",
    "rssi": -79,
    "advertising": /* ArrayBuffer or map */
}

Advertising information format varies depending on your platform. See Advertising Data for more information.

Parameters

  • services: List of services to discover, or [] to find all devices
  • seconds: Number of seconds to run discovery
  • success: Success callback function that is invoked which each discovered device.
  • failure: Error callback function, invoked when error occurs. [optional]

Quick Example

ble.scan([], 5, function(device) {
    console.log(JSON.stringify(device));
}, failure);

startScan

Scan and discover BLE peripherals.

ble.startScan(services, success, failure);

Description

Function startScan scans for BLE devices. The success callback is called each time a peripheral is discovered. Scanning will continue until stopScan is called.

{
    "name": "TI SensorTag",
    "id": "BD922605-1B07-4D55-8D09-B66653E51BBA",
    "rssi": -79,
    "advertising": /* ArrayBuffer or map */
}

Advertising information format varies depending on your platform. See Advertising Data for more information.

Parameters

  • services: List of services to discover, or [] to find all devices
  • success: Success callback function that is invoked which each discovered device.
  • failure: Error callback function, invoked when error occurs. [optional]

Quick Example

ble.startScan([], function(device) {
    console.log(JSON.stringify(device));
}, failure);

setTimeout(ble.stopScan,
    5000,
    function() { console.log("Scan complete"); },
    function() { console.log("stopScan failed"); }
);

stopScan

Stop scanning for BLE peripherals.

ble.stopScan(success, failure);

Description

Function stopScan stops scanning for BLE devices.

Parameters

  • success: Success callback function, invoked when scanning is stopped. [optional]
  • failure: Error callback function, invoked when error occurs. [optional]

Quick Example

ble.startScan([], function(device) {
    console.log(JSON.stringify(device));
}, failure);

setTimeout(ble.stopScan,
    5000,
    function() { console.log("Scan complete"); },
    function() { console.log("stopScan failed"); }
);

/* Alternate syntax
setTimeout(function() {
    ble.stopScan(
        function() { console.log("Scan complete"); },
        function() { console.log("stopScan failed"); }
    );
}, 5000);
*/

connect

Connect to a peripheral.

ble.connect(device_id, connectSuccess, connectFailure);

Description

Function connect connects to a BLE peripheral. The callback is long running. Success will be called when the connection is successful. Service and characteristic info will be passed to the success callback in the peripheral object. Failure is called if the connection fails, or later if the connection disconnects. An error message is passed to the failure callback.

Parameters

  • device_id: UUID or MAC address of the peripheral
  • connectSuccess: Success callback function that is invoked when the connection is successful.
  • connectFailure: Error callback function, invoked when error occurs or the connection disconnects.

disconnect

Disconnect.

ble.disconnect(device_id, [success], [failure]);

Description

Function disconnect disconnects the selected device.

Parameters

  • device_id: UUID or MAC address of the peripheral
  • success: Success callback function that is invoked when the connection is successful. [optional]
  • failure: Error callback function, invoked when error occurs. [optional]

read

Reads the value of a characteristic.

ble.read(device_id, service_uuid, characteristic_uuid, success, failure);

Description

Function read reads the value of the characteristic.

Raw data is passed from native code to the callback as an ArrayBuffer.

Parameters

  • device_id: UUID or MAC address of the peripheral
  • service_uuid: UUID of the BLE service
  • characteristic_uuid: UUID of the BLE characteristic
  • success: Success callback function that is invoked when the connection is successful. [optional]
  • failure: Error callback function, invoked when error occurs. [optional]

write

Writes data to a characteristic.

ble.write(device_id, service_uuid, characteristic_uuid, value, success, failure);

Description

Function write writes data to a characteristic.

Parameters

  • device_id: UUID or MAC address of the peripheral
  • service_uuid: UUID of the BLE service
  • characteristic_uuid: UUID of the BLE characteristic
  • data: binary data, use an ArrayBuffer
  • success: Success callback function that is invoked when the connection is successful. [optional]
  • failure: Error callback function, invoked when error occurs. [optional]

writeWithoutResponse

Writes data to a characteristic without confirmation from the peripheral.

ble.writeCommand(device_id, service_uuid, characteristic_uuid, value, success, failure);

Description

Function writeWithoutResponse writes data to a characteristic without a response from the peripheral. You are not notified if the write fails in the BLE stack. The success callback is be called when the characteristic is written.

Parameters

  • device_id: UUID or MAC address of the peripheral
  • service_uuid: UUID of the BLE service
  • characteristic_uuid: UUID of the BLE characteristic
  • data: binary data, use an ArrayBuffer
  • success: Success callback function that is invoked when the connection is successful. [optional]
  • failure: Error callback function, invoked when error occurs. [optional]

startNotification

Register to be notified when the value of a characteristic changes.

ble.startNotification(device_id, service_uuid, characteristic_uuid, success, failure);

Description

Function startNotification registers a callback that is called when the value of a characteristic changes. This method handles both notifications and indications.

Raw data is passed from native code to the success callback as an ArrayBuffer.

Parameters

  • device_id: UUID or MAC address of the peripheral
  • service_uuid: UUID of the BLE service
  • characteristic_uuid: UUID of the BLE characteristic
  • success: Success callback function that is invoked when the connection is successful. [optional]
  • failure: Error callback function, invoked when error occurs. [optional]

stopNotification

Stop being notified when the value of a characteristic changes.

ble.stopNotification(device_id, service_uuid, characteristic_uuid, success, failure);

Description

Function stopNotification stops a previously registered notification callback.

Parameters

  • device_id: UUID or MAC address of the peripheral
  • service_uuid: UUID of the BLE service
  • characteristic_uuid: UUID of the BLE characteristic
  • success: Success callback function that is invoked when the notification is removed. [optional]
  • failure: Error callback function, invoked when error occurs. [optional]

isConnected

Reports the connection status.

ble.isConnected(device_id, success, failure);

Description

Function isConnected calls the success callback when the peripheral is connected and the failure callback when not connected.

Parameters

  • device_id: UUID or MAC address of the peripheral
  • success: Success callback function that is invoked with a boolean for connected status.
  • failure: Error callback function, invoked when error occurs. [optional]

Quick Example

ble.isConnected(
    'FFCA0B09-CB1D-4DC0-A1EF-31AFD3EDFB53',
    function() {
        console.log("Peripheral is connected");
    },
    function() {
        console.log("Peripheral is *not* connected");
    }
);

isEnabled

Reports if bluetooth is enabled.

ble.isEnabled(success, failure);

Description

Function isEnabled calls the success callback when Bluetooth is enabled and the failure callback when Bluetooth is not enabled.

Parameters

  • success: Success callback function that is invoked with a boolean for connected status.
  • failure: Error callback function, invoked when error occurs. [optional]

Quick Example

ble.isEnabled(
    function() {
        console.log("Bluetooth is enabled");
    },
    function() {
        console.log("Bluetooth is *not* enabled");
    }
);

showBluetoothSettings

Show the Bluetooth settings on the device.

ble.showBluetoothSettings(success, failure);

Description

Function showBluetoothSettings opens the Bluetooth settings for the operating systems.

iOS

showBluetoothSettings is not supported on iOS.

Parameters

  • success: Success callback function [optional]
  • failure: Error callback function, invoked when error occurs. [optional]

Quick Example

ble.showBluetoothSettings();

enable

Enable Bluetooth on the device.

ble.enable(success, failure);

Description

Function enable prompts the user to enable Bluetooth.

Android

enable is only supported on Android and does not work on iOS.

If enable is called when Bluetooth is already enabled, the user will not prompted and the success callback will be invoked.

Parameters

  • success: Success callback function, invoked if the user enabled Bluetooth.
  • failure: Error callback function, invoked if the user does not enabled Bluetooth.

Quick Example

ble.enable(
    function() {
        console.log("Bluetooth is enabled");
    },
    function() {
        console.log("The user did *not* enable Bluetooth");
    }
);

Peripheral Data

Peripheral Data is passed to the success callback when scanning and connecting. Limited data is passed when scanning.

{
    "name": "Battery Demo",
    "id": "20:FF:D0:FF:D1:C0",
    "advertising": [2,1,6,3,3,15,24,8,9,66,97,116,116,101,114,121],
    "rssi": -55
}

After connecting, the peripheral object also includes service, characteristic and descriptor information.

{
    "name": "Battery Demo",
    "id": "20:FF:D0:FF:D1:C0",
    "advertising": [2,1,6,3,3,15,24,8,9,66,97,116,116,101,114,121],
    "rssi": -55,
    "services": [
        "1800",
        "1801",
        "180f"
    ],
    "characteristics": [
        {
            "service": "1800",
            "characteristic": "2a00",
            "properties": [
                "Read"
            ]
        },
        {
            "service": "1800",
            "characteristic": "2a01",
            "properties": [
                "Read"
            ]
        },
        {
            "service": "1801",
            "characteristic": "2a05",
            "properties": [
                "Read"
            ]
        },
        {
            "service": "180f",
            "characteristic": "2a19",
            "properties": [
                "Read"
            ],
            "descriptors": [
                {
                    "uuid": "2901"
                },
                {
                    "uuid": "2904"
                }
            ]
        }
    ]
}

Advertising Data

Bluetooth advertising data is returned in when scanning for devices. The format format varies depending on your platform. On Android advertising data will be the raw advertising bytes. iOS does not allow access to raw advertising data, so a dictionary of data is returned.

The advertising information for both Android and iOS appears to be a combination of advertising data and scan response data.

Ideally a common format (map or array) would be returned for both platforms in future versions. If you have ideas, please contact me.

Android

{
    "name": "demo",
    "id": "00:1A:7D:DA:71:13",
    "advertising": ArrayBuffer,
    "rssi": -37
}

Convert the advertising info to a Uint8Array for processing. var adData = new Uint8Array(peripheral.advertising)

iOS

Note that iOS uses the string value of the constants for the Advertisement Data Retrieval Keys. This will likely change in the future.

{
    "name": "demo",
    "id": "D8479A4F-7517-BCD3-91B5-3302B2F81802",
    "advertising": {
        "kCBAdvDataChannel": 37,
        "kCBAdvDataServiceData": {
            "FED8": {
                "byteLength": 7 /* data not shown */
            }
        },
        "kCBAdvDataLocalName": "demo",
        "kCBAdvDataServiceUUIDs": ["FED8"],
        "kCBAdvDataManufacturerData": {
            "byteLength": 7  /* data not shown */
        },
        "kCBAdvDataTxPowerLevel": 32,
        "kCBAdvDataIsConnectable": true
    },
    "rssi": -53
}

Typed Arrays

This plugin uses typed Arrays or ArrayBuffers for sending and receiving data.

This means that you need convert your data to ArrayBuffers before sending and from ArrayBuffers when receiving.

// ASCII only
function stringToBytes(string) {
   var array = new Uint8Array(string.length);
   for (var i = 0, l = string.length; i < l; i++) {
       array[i] = string.charCodeAt(i);
    }
    return array.buffer;
}

// ASCII only
function bytesToString(buffer) {
    return String.fromCharCode.apply(null, new Uint8Array(buffer));
}

You can read more about typed arrays in these articles on MDN and HTML5 Rocks.

UUIDs

UUIDs are always strings and not numbers. Some 16-bit UUIDs, such as '2220' look like integers, but they're not. (The integer 2220 is 0x8AC in hex.) This isn't a problem with 128 bit UUIDs since they look like strings 82b9e6e1-593a-456f-be9b-9215160ebcac. All 16-bit UUIDs should also be passed to methods as strings.

Testing the Plugin

Tests require the Cordova Plugin Test Framework

Create a new project

git clone https://github.com/don/cordova-plugin-ble-central
cordova create ble-test com.example.ble.test BLETest
cd ble-test
cordova platform add android
cordova plugin add ../ble
cordova plugin add ../ble/tests
cordova plugin add cordova-plugin-test-framework

Change the start page in config.xml

<content src="cdvtests/index.html" />

Run the app on your phone

cordova run android --device

License

Apache 2.0

Feedback

Try the code. If you find an problem or missing feature, file an issue or create a pull request.

Other Bluetooth Plugins