cordova-plugin-ble-central - npm Package Compare versions

Comparing version 1.0.6 to 1.1.0

CHANGES.txt

@@ -0,1 +1,11 @@
+= 1.1.0 =
+Add documentation about receiving notifications in the background on iOS #169
+Add option to report duplicates during scan #172 Thanks Chris Armstrong
+Read RSSI value from an active BLE connection #171 Thanks Chris Armstrong
+Register for callbacks on Bluetooth state change #136 Thanks Ryan Harvey
+Fix example for write characteristic #195 Thanks Wynout van der Veer
+Fix documentation for write & writeWithoutResponse #193 Thanks Blake Parkinson
+Update CC2650 example #200 Thanks jplourenco
+Connect peripheral with missing ble-flag (Android SDK 23) #226 Thanks PeacePan
+
 = 1.0.6 =
@@ -2,0 +12,0 @@ Fix compile error with Cordova 5.x #219

examples/sensortag_cc2650/www/js/index.js

@@ -175,5 +175,5 @@ // (c) 2014 Don Coleman
                   "Mag <br/>"+
-                  "X: " + a[3] + "<br/>" +
-                  "Y: " + a[4] + "<br/>" +
-                  "Z: " + a[5] + "<br/>" ;
+                  "X: " + a[6] + "<br/>" +
+                  "Y: " + a[7] + "<br/>" +
+                  "Z: " + a[8] + "<br/>" ;
 
@@ -180,0 +180,0 @@ accelerometerData.innerHTML = message;

LICENSE.txt

@@ -1,2 +0,2 @@
-Copyright 2014 Don Coleman
+Copyright 2014-2016 Don Coleman
 
@@ -13,2 +13,2 @@ Licensed under the Apache License, Version 2.0 (the "License");
 See the License for the specific language governing permissions and
-limitations under the License.
+limitations under the License.

package.json

 {
   "name": "cordova-plugin-ble-central",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Bluetooth Low Energy (BLE) Central Plugin",
@@ -5,0 +5,0 @@ "cordova": {

README.md

@@ -54,2 +54,3 @@ # Bluetooth Low Energy (BLE) Central Plugin for Apache Cordova
 - [ble.startScan](#startscan)
+- [ble.startScanWithOptions](#startscanwithoptions)
 - [ble.stopScan](#stopscan)
@@ -65,4 +66,7 @@ - [ble.connect](#connect)
 - [ble.isConnected](#isconnected)
+- [ble.startStateNotifications](#startstatenotifications)
+- [ble.stopStateNotifications](#stopstatenotifications)
 - [ble.showBluetoothSettings](#showbluetoothsettings)
 - [ble.enable](#enable)
+- [ble.readRSSI](#readrssi)
 
@@ -138,2 +142,45 @@ ## scan
 
+## startScanWithOptions
+
+Scan and discover BLE peripherals, specifying scan options.
+
+    ble.startScan(services, options, success, failure);
+
+### Description
+
+Function `startScanWithOptions` scans for BLE devices. It operates similarly to the `startScan` function, but allows you to specify extra options (like allowing duplicate device reports).  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](#advertising-data) for more information.
+
+### Parameters
+
+- __services__: List of services to discover, or [] to find all devices
+- __options__: an object specifying a set of name-value pairs. The currently acceptable options are:
+- _reportDuplicates_: true if duplicate devices should be reported, false (default) if devices should only be reported once. [optional]
+- __success__: Success callback function that is invoked which each discovered device.
+- __failure__: Error callback function, invoked when error occurs. [optional]
+
+### Quick Example
+
+    ble.startScan([],
+        { reportDuplicates: true }
+        function(device) {
+            console.log(JSON.stringify(device));
+        },
+        failure);
+
+    setTimeout(ble.stopScan,
+        5000,
+        function() { console.log("Scan complete"); },
+        function() { console.log("stopScan failed"); }
+    );
+
+
 ## stopScan
@@ -233,3 +280,3 @@
 
-    ble.write(device_id, service_uuid, characteristic_uuid, value, success, failure);
+    ble.write(device_id, service_uuid, characteristic_uuid, data, success, failure);
 
@@ -259,5 +306,5 @@ ### Description
     var data = new Uint8Array(3);
-    data[0] = 0xFF;  // red
-    data[0] = 0x00; // green
-    data[0] = 0xFF; // blue
+    data[0] = 0xFF; // red
+    data[1] = 0x00; // green
+    data[2] = 0xFF; // blue
     ble.write(device_id, "ccc0", "ccc1", data.buffer, success, failure);
@@ -274,3 +321,3 @@
 
-    ble.writeWithoutResponse(device_id, service_uuid, characteristic_uuid, value, success, failure);
+    ble.writeWithoutResponse(device_id, service_uuid, characteristic_uuid, data, success, failure);
 
@@ -301,2 +348,4 @@ ### Description
 
+See [Background Notifications on iOS](#background-notifications-on-ios)
+
 ### Parameters
@@ -309,3 +358,3 @@
 - __failure__: Error callback function, invoked when error occurs. [optional]
- 
+
 ### Quick Example
@@ -318,3 +367,3 @@
     }
-    
+
     ble.startNotification(device_id, "FFE0", "FFE1", onData, failure);
@@ -394,2 +443,46 @@
 
+## startStateNotifications
+
+Registers to be notified when Bluetooth state changes on the device.
+
+    ble.startStateNotifications(success, failure);
+
+### Description
+
+Function `startStateNotifications` calls the success callback when the Bluetooth is enabled or disabled on the device.
+
+__States__
+
+- "on"
+- "off"
+- "turningOn" (Android Only)
+- "turningOff" (Android Only)
+- "unknown" (iOS Only)
+- "resetting" (iOS Only)
+- "unsupported" (iOS Only)
+- "unauthorized" (iOS Only)
+
+### Parameters
+
+- __success__: Success callback function that is invoked with a string for the Bluetooth state.
+- __failure__: Error callback function, invoked when error occurs. [optional]
+
+### Quick Example
+
+    ble.startStateNotifications(
+        function(state) {
+            console.log("Bluetooth is " + state);
+        }
+    );
+
+## stopStateNotifications
+
+Stops state notifications.
+
+    ble.startStateNotifications(success, failure);
+
+### Description
+
+Function `stopStateNotifications` calls the success callback when Bluetooth state notifications have been stopped.
+
 ## showBluetoothSettings
@@ -450,2 +543,34 @@
 
+## readRSSI
+
+Read the RSSI value on the device connection.
+
+    ble.readRSSI(device_id, success, failure);
+
+### Description
+
+Samples the RSSI value (a measure of signal strength) on the connection to a bluetooth device. Requires that you have established a connection before invoking (otherwise an error will be raised).
+
+### Parameters
+
+- __device_id__: device identifier
+- __success__: Success callback function, invoked with the RSSI value (as an integer)
+- __failure__: Error callback function, invoked if there is no current connection or if there is an error reading the RSSI.
+
+### Quick Example
+    var rssiSample;
+    ble.connect(device_id,
+        function(device) {
+            rssiSample = setInterval(function() {
+                    ble.readRSSI(device_id, function(rssi) {
+                            console.log('read RSSI',rssi,'with device', device_id);
+                        }, function(err) {
+                            console.error('unable to read RSSI',err);
+                            clearInterval(rssiSample);
+                            })
+                }, 5000);
+        },
+        function(err) { console.error('error connecting to device')}
+        );
+
 # Peripheral Data
@@ -545,3 +670,3 @@
                 "FED8": {
-                    "byteLength": 7 /* data not shown */
+                    "byteLength": 7 // data not shown
                 }
@@ -552,3 +677,3 @@ },
             "kCBAdvDataManufacturerData": {
-                "byteLength": 7  /* data not shown */
+                "byteLength": 7  // data not shown
             },
@@ -587,2 +712,22 @@ "kCBAdvDataTxPowerLevel": 32,
 
+# Background Notifications on iOS
+
+Android applications will continue to receive notification while the application is in the background.
+
+iOS applications need additional configuration to allow Bluetooth to run in the background.
+
+Install the [cordova-custom-config](https://www.npmjs.com/package/cordova-custom-config) plugin.
+
+    cordova plugin add cordova-custom-config
+
+Add a new section to config.xml
+
+    <platform name="ios">
+        <config-file parent="UIBackgroundModes" target="*-Info.plist">
+            <array>
+                <string>bluetooth-central</string>
+            </array>
+        </config-file>
+    </platform>
+    
 # Testing the Plugin
@@ -589,0 +734,0 @@

src/browser/BLECentralPlugin.js

@@ -18,2 +18,6 @@ function notSupported() {
     },
+    startScanWithOptions: function(services, options, success, failure) {
+        notSupported();
+        if (failure) failure();
+    },
     connect: function(device_id, connectSuccess, connectFailure) {
@@ -31,2 +35,6 @@ notSupported();
     },
+    readRSSI: function(device_id, success, failure) {
+        notSupported();
+        if (failure) failure();
+    },
     write: function(device_id, service_uuid, characteristic_uuid, data, success, failure) {
@@ -63,3 +71,11 @@ notSupported();
         if (failure) failure();
+    },
+    startStateNotifications: function(success, failure) {
+      notSupported();
+      if (failure) failure();
+    },
+    stopStateNotifications: function(success, failure) {
+      notSupported();
+      if (failure) failure();
     }
 };

www/ble.js

@@ -1,2 +0,2 @@
-// (c) 2014 Don Coleman
+// (c) 2014-2016 Don Coleman
 //
@@ -72,2 +72,10 @@ // Licensed under the Apache License, Version 2.0 (the "License");
 
+    startScanWithOptions: function(services, options, success, failure) {
+        var successWrapper = function(peripheral) {
+            convertToNativeJS(peripheral);
+            success(peripheral);
+        };
+        options = options || {};
+        cordova.exec(successWrapper, failure, 'BLE', 'startScanWithOptions', [services, options]);
+    },
 
@@ -96,2 +104,7 @@ // this will probably be removed
 
+    // RSSI value comes back as an integer
+    readRSSI: function(device_id, success, failure) {
+        cordova.exec(success, failure, 'BLE', 'readRSSI', [device_id]);
+    },
+
     // value must be an ArrayBuffer
@@ -143,4 +156,12 @@ write: function (device_id, service_uuid, characteristic_uuid, value, success, failure) {
         cordova.exec(success, failure, "BLE", "showBluetoothSettings", []);
+    },
+
+    startStateNotifications: function (success, failure) {
+        cordova.exec(success, failure, "BLE", "startStateNotifications", []);
+    },
+
+    stopStateNotifications: function (success, failure) {
+        cordova.exec(success, failure, "BLE", "stopStateNotifications", []);
     }
 
 };

No alert changes

Improved metrics

Total package byte prevSize

256327

increased by8.2%

Lines of code

1919

increased by1.8%

Number of lines in readme file

755

increased by23.77%

No dependency changes