This plugin enables communication between a phone and Bluetooth Low Energy (BLE) peripherials. Simultaneous connections to multiple peripherals are supported
The goal of this plugin is to provide a simple JavaScript API for Bluetooth Central devices. The API should be common across all platforms.
- 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
I assume you know details about the services and characteristics that you want to use. All access is via service and characteristic UUIDs. The plugin will manage handles internally. This plugin probably won't be suitable for writing generic BLE clients.
See the examples for ideas on how this plugin can be used.
- iOS
- Android (4.3 or greater)
This is an early version of plugin, the API is likely to change.
- All services are discovered, this can be slow, especially on iOS
- Implementation doesn't stop you from scanning during a scan
- Indicate is not implemented
Install with Cordova CLI
$ cd /path/to/your/project
$ cordova plugin add https://github.com/don/cordova-plugin-ble-central#:/plugin
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": /* byte array 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. 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.
ble.writeCommand(device_id, service_uuid, characteristic_uuid, value, success, failure);
Function write writes data to a characteristic without a response. You are not notified if the write fails in the BLE stack.
- 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.notify(device_id, service_uuid, characteristic_uuid, success, failure) {;
Function notify 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]
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");
}
);
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.
Future versions should return ArrayBuffers for all binary data. Currently, Android returns an int array for binary 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": [10, 22, -40, -2, 0, 32, 0, 101, 102, 102, 7, 5, 9, 100, 101, 109,
111, 2, 10, 32, 3, 3, -40, -2, 8, -1, 0, 0, 104, 101, 108, 108, 111,
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
"rssi": -37
}
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
}
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 pluginc for iOS and Android.
- BluetoothLE - Rand Dusing's BLE plugin for Cordova
- PhoneGap Bluetooth Plugin - Bluetooth classic pairing and connecting for Android