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.
- iOS
- Android (4.3 or greater)
Install with Cordova CLI
$ cd /path/to/your/project
$ cordova plugin add com.megster.cordova.ble
- ble.scan
- ble.connect
- ble.disconnect
- ble.read
- ble.write
- ble.writeWithoutResponse
- ble.startNotification
- ble.stopNotification
- ble.indicate
- ble.isEnabled
- ble.isConnected
Scan and discover BLE peripherals.
ble.scan(services, seconds, success, failure);
Function scan scans for BLE devices. The success callback is called each time a peripheral is discovered.
{
"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.
- 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 with a list of bonded devices.
- failure: Error callback function, invoked when error occurs. [optional]
ble.scan([], 5, function(device) {
console.log(JSON.stringify(device));
}, failure);
Connect to a peripheral.
ble.connect(device_id, connectSuccess, connectFailure);
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.
- 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.
ble.disconnect(device_id, [success], [failure]);
Function disconnect disconnects the selected device.
- 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]
Reads the value of a characteristic.
ble.read(device_id, service_uuid, characteristic_uuid, success, failure) {;
Function read reads the value of the characteristic.
Raw data is passed from native code to the callback as an ArrayBuffer.
- 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]
Writes data to a characteristic.
ble.write(device_id, service_uuid, characteristic_uuid, value, success, failure);
Function write writes data to a characteristic.
- 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]
Writes data to a characteristic without confirmation from the peripheral.
ble.writeCommand(device_id, service_uuid, characteristic_uuid, value, success, failure);
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.
- 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]
Register to be notified when the value of a characteristic changes.
ble.startNotification(device_id, service_uuid, characteristic_uuid, success, failure) {;
Function startNotification registers a callback that is called when the value of the characteristic changes.
Raw data is passed from native code to the success callback as an ArrayBuffer.
- 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]
Stop being notified when the value of a characteristic changes.
ble.stopNotification(device_id, service_uuid, characteristic_uuid, success, failure) {;
Function stopNotification stops a previously registered notification callback.
- 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]
Register for an indication when the value of a characteristic changes.
ble.indicate(device_id, service_uuid, characteristic_uuid, success, failure) {;
Function indicate registers a callback that is called when the value of the characteristic changes. Indicate is similar to notify, except indicate sends a confirmation back to the peripheral when the value is read.
Raw data is passed from native code to the success callback as an ArrayBuffer.
- 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]
Reports the connection status.
ble.isConnected(device_id, success, failure);
Function isConnected calls the success callback when the peripheral is connected and the failure callback when not connected.
- 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]
ble.isConnected(
'FFCA0B09-CB1D-4DC0-A1EF-31AFD3EDFB53',
function() {
console.log("Peripheral is connected");
},
function() {
console.log("Peripheral is *not* connected");
}
);
Reports if bluetooth is enabled.
ble.isEnabled(success, failure);
Function isEnabled calls the success callback when Bluetooth is enabled and the failure callback when Bluetooth is not enabled.
- success: Success callback function that is invoked with a boolean for connected status.
- failure: Error callback function, invoked when error occurs. [optional]
ble.isEnabled(
function() {
console.log("Bluetooth is enabled");
},
function() {
console.log("Bluetooth is *not* enabled");
}
);
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"
}
]
}
]
}
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.
{
"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)
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
}
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.
Apache 2.0
Try the code. If you find an problem or missing feature, file an issue or create a pull request.
- BluetoothSerial - Connect to Arduino and other devices. Bluetooth Classic on Android, BLE on iOS.
- RFduino - RFduino specific plugin for iOS and Android.
- BluetoothLE - Rand Dusing's BLE plugin for Cordova
- PhoneGap Bluetooth Plugin - Bluetooth classic pairing and connecting for Android