This wraps the Bluetooth Low Energy Phonegap Plugin by Rand Dusing in AngularJS code so it can be used more easily in AngularJS mobile applications.
Please only create issues that are directly related to ng-cordova-bluetoothle! If it's not an Angular/Javascript issue, create the issue in the cordova-plugin-bluetoothle repo!
- Install the Bluetooth LE Plugin:
cordova plugin add cordova-plugin-bluetoothle - Install the Angular Wrapper:
bower install git://github.com/randdusing/ng-cordova-bluetoothle.git#master
An example app has been created using the Ionic Framework to demonstrate the functionality. To install the example app, follow the steps below:
- Create a new Ionic Project: ionic start test tabs
- Install the Bluetooth LE plugin: cordova plugin add cordova-plugin-bluetoothle
- Install the Angular Wrapper:
bower install git://github.com/randdusing/ng-cordova-bluetoothle.git#master - Install crypto-js library if using examples:
bower install js-md5 - Add contents from /example to /www of the Cordova project, replacing if necessary
- Build and run the Cordova project
A few examples, but the example app is your best resource.
$cordovaBluetoothLE.initialize({request:true}).then(null,
function(obj) {
//Handle errors
},
function(obj) {
//Handle successes
}
);
Initialize uses the notify callback to keep track of changes in the Bluetooth state (on/off).
$cordovaBluetoothLE.startScan({services:[]}).then(null,
function(obj) {
//Handle errors
console.log(obj.message);
},
function(obj) {
if (obj.status == "scanResult")
{
//Device found
}
else if (obj.status == "scanStarted")
{
//Scan started
}
}
);
Scan uses the notify callback as well since multiple scanned devices may be returned.
$cordovaBluetoothLE.connect({address:"ABCDEFG"}).then(null,
function(obj) {
//Handle errors
console.log(obj.message);
},
function(obj) {
if (obj.status == "connected") {
//Device connected
} else {
//Device disconnected, handle this unexpected disconnect
}
}
);
Connect uses the notify callback as well since the connection state may change. See useResolve option below for resolve vs notify.
For details on each function, please visit https://github.com/randdusing/cordova-plugin-bluetoothle. A few methods require you wait for notify rather than resolve since the callback may be called multiple times: intialize, startScan, connect, reconnect, disconnect, subscribe. Enable and disable only wait for error since the "success" is returned to the initialize
- $cordovaBluetoothLE.initialize(params).then(null, error, success);
- $cordovaBluetoothLE.enable().then(null, error); Android
- $cordovaBluetoothLE.disable().then(null, error); Android
- $cordovaBluetoothLE.startScan(params).then(null, error, success);
- $cordovaBluetoothLE.stopScan().then(success, error);
- $cordovaBluetoothLE.retrieveConnected(params).then(success, error);
- $cordovaBluetoothLE.bond(params).then(null, error, success);
- $cordovaBluetoothLE.unbond(params).then(success, error);
- $cordovaBluetoothLE.connect(params).then(null, error, success);
- $cordovaBluetoothLE.reconnect(params).then(null, error, success);
- $cordovaBluetoothLE.disconnect(params).then(success, error);
- $cordovaBluetoothLE.close(params).then(success, error);
- $cordovaBluetoothLE.discover(params).then(success, error);
- $cordovaBluetoothLE.services(params).then(success, error); iOS
- $cordovaBluetoothLE.characteristics(params).then(success, error); iOS
- $cordovaBluetoothLE.descriptors(params).then(success, error); iOS
- $cordovaBluetoothLE.read(params).then(success, error);
- $cordovaBluetoothLE.subscribe(params).then(null, error, success);
- $cordovaBluetoothLE.unsubscribe(params).then(success, error);
- $cordovaBluetoothLE.write(params).then(success, error);
- $cordovaBluetoothLE.writeQ(params).then(success, error);
- $cordovaBluetoothLE.readDescriptor(params).then(success, error);
- $cordovaBluetoothLE.writeDescriptor(params).then(success, error);
- $cordovaBluetoothLE.rssi(params).then(success, error);
- $cordovaBluetoothLE.mtu(params).then(success, error); Android
- $cordovaBluetoothLE.requestConnectionPriority(params).then(success, error); Android
- $cordovaBluetoothLE.isInitialized(params).then(success);
- $cordovaBluetoothLE.isEnabled(params).then(success);
- $cordovaBluetoothLE.isScanning(params).then(success);
- $cordovaBluetoothLE.isBonded(params).then(success);
- $cordovaBluetoothLE.wasConnected(params).then(success, error);
- $cordovaBluetoothLE.isConnected(params).then(success, error);
- $cordovaBluetoothLE.isDiscovered(params).then(success, error);
- $cordovaBluetoothLE.hasPermission().then(success, error); Android 6.0+
- $cordovaBluetoothLE.requestPermission().then(success, error); Android 6.0+
- $cordovaBluetoothLE.isLocationEnabled().then(success, error); Android 6.0+
- $cordovaBluetoothLE.requestLocation().then(success, error); Android 6.0+
- $cordovaBluetoothLE.initializePeripheral(params).then(success, error);
- $cordovaBluetoothLE.addService(params).then(success, error);
- $cordovaBluetoothLE.removeService(params).then(success, error);
- $cordovaBluetoothLE.removeAllServices().then(success, error);
- $cordovaBluetoothLE.startAdvertising().then(success, error);
- $cordovaBluetoothLE.stopAdvertising().then(success, error);
- $cordovaBluetoothLE.isAdvertising().then(success, error);
- $cordovaBluetoothLE.respond(params).then(success, error);
- $cordovaBluetoothLE.notify(params).then(success, error);
- $cordovaBluetoothLE.encodedStringToBytes(encodedString);
- $cordovaBluetoothLE.bytesToEncodedString(bytes);
- $cordovaBluetoothLE.stringToBytes(string);
- $cordovaBluetoothLE.bytesToString(bytes);
- useResolve - If true, forces connect and reconnect to resolve the promise rather than using notify.
- timeout - If set, the operation will timeout with an error after X milliseconds. Available on connect, reconnect, discover, services, characteristics, descriptors, read, subscribe, unsubscribe, write, readDescriptor, writeDescriptor, rssi, mtu, requestConnectionPriority.
- scanTimeout - On a successful scan start, automatically stop the scan after X milliseconds.
- subscribeTimeout - On a successful subscribe, automatically unsubscribe after X milliseconds.
Some examples are provided to help demonstrate different common scenarios. Looking for more examples? Let me know!
- Throughput (Central) - Transfers a file to another device running Throughput (Peripheral). Make sure to start the Throughput (Peripheral) test first.
- Throughput (Peripheral) - Receives a file from another device running Throughput (Central).
- Read All - Scans for first available device, connects to it, discovers it, iterates through all characteristics and reads them, disconnects and finally closes. This provides a good example of promise chains.
Example of how you could queue up three read operations.
$cordovaBluetoothLE.read(params1).then(function() { //Read 1
return $cordovaBluetoothLE.read(params2); //Read 2
}).then(function() {
return $cordovaBluetoothLE.read(params3); //Read 3
}).catch(function(err) {
console.log(err); //Catch any errors
});AngularJS - http://www.angularjs.org
Apache Cordova - http://cordova.apache.org
The code that powers the 'build generation' is a carbon copy (with minimal changes) of Nic Raboy's ngCordovaBeacon project. As of the Fork, it was licensed under the MIT license; The Cordova Wrapper was written by myself, and my employer and I retain the copyright for that; but this project is also licensed under the MIT License.
If you want to follow more of Nic's work, his blog is located here. If you want to know more about me or Jewelbots, you can follow Jewelbots on twitter, our Ink, or me.
Rand Dusing - Primary author of the Cordova Bluetooth LE Plugin. You can contact me via: [email protected], Facebook, LinkedIn or Twitter.