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

Comparing version 1.6.2 to 1.6.3

CHANGES.txt

@@ -0,1 +1,4 @@
+= 1.6.3 =
+Android: Implement manual bond control on #605 #843
+
 = 1.6.2 =
@@ -2,0 +5,0 @@ Android: Don't leak refreshDeviceCache callback

package.json

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

README.md

@@ -95,2 +95,5 @@ # Bluetooth Low Energy (BLE) Central Plugin for Apache Cordova
 -   [ble.setPin](#setpin)
+-   [ble.bond](#bond)
+-   [ble.unbond](#unbond)
+-   [ble.readBondState](#readbondstate)
 -   [ble.connect](#connect)
@@ -316,2 +319,79 @@ -   [ble.autoConnect](#autoconnect)
 
+## bond
+
+Initiate a bond with a remote device
+
+    ble.bond(device_id, [success], [failure], [options]);
+    // Or using await with promises
+    await ble.withPromises.bond(device_id);
+    await ble.withPromises.bond(device_id, { usePairingDialog: true });
+
+### Description
+
+Function `bond` initialises a bond with a peripheral. The success callback will be called when the
+bonding is complete. The bonding process may prompt the user to confirm the pairing process.
+
+### Parameters
+
+-   **device_id**: UUID or MAC address of the peripheral
+-   **success**: Success callback function that is invoked when the bonding succeeds. [optional]
+-   **failure**: Error callback function, invoked when the bonding fails. [optional]
+-   **options**: an object specifying a set of name-value pairs. The currently acceptable options are:
+    -   _usePairingDialog_: _true_ (default) Show pairing request as a dialog rather than a notification [optional]
+
+### Supported Platforms
+
+-   Android
+
+## unbond
+
+Remove a bond for a remote device
+
+    ble.unbond(device_id, [success], [failure]);
+    // Or using await with promises
+    await ble.withPromises.unbond(device_id);
+
+### Description
+
+Function `unbond` removes an existing bond for a remote device. The success callback will be called when the
+bond has been removed.
+
+### Parameters
+
+-   **device_id**: UUID or MAC address of the peripheral
+-   **success**: Success callback function that is invoked when the bond is removed. [optional]
+-   **failure**: Error callback function, invoked when the bond removal fails. [optional]
+
+### Supported Platforms
+
+-   Android
+
+## readBondState
+
+Get the bond state of a device as a string
+
+    ble.readBondState(device_id, [success], [failure]);
+    // Or using await with promises
+    const bondState = await ble.withPromises.readBondState(device_id);
+
+### Description
+
+Function `readBondState` retrieves the current bond state of the device.
+
+**States**
+
+-   "none"
+-   "bonding"
+-   "bonded"
+
+### Parameters
+
+-   **device_id**: UUID or MAC address of the peripheral
+-   **success**: Success callback function that is invoked with the current bond state. [optional]
+-   **failure**: Error callback function, invoked when error occurs. [optional]
+
+### Supported Platforms
+
+-   Android
+
 ## connect
@@ -318,0 +398,0 @@

src/browser/BLECentralPlugin.js

@@ -203,3 +203,9 @@
         notSupported(failure);
-    }
+    },
+    bond: function (success, failure) {
+        notSupported(failure);
+    },
+    readBondState: function (success, failure) {
+        notSupported(failure);
+    },
 };

types.d.ts

 declare namespace BLECentralPlugin {
     type PeripheralState = 'disconnected' | 'disconnecting' | 'connecting' | 'connected';
+    type BondState = 'none' | 'bonding' | 'bonded';
 
@@ -54,2 +55,7 @@ interface PeripheralCharacteristic {
 
+    interface CreateBondOptions {
+        /* Show pairing request as a dialog rather than a notification */
+        usePairingDialog: boolean;
+    }
+
     interface L2CAP {
@@ -181,2 +187,17 @@ close(device_id: string, psm: number, success?: () => any, failure?: (error: string | BLEError) => any): void;
         restoredBluetoothState(): Promise<RestoredState | undefined>;
+
+        /* Start the bonding (pairing) process with the remote device. 
+            [iOS] bond is not supported on iOS.
+         */
+        bond(device_id: string, options?: CreateBondOptions): Promise<void>;
+
+        /* unbonds a remote device. Note: this uses an unlisted API on Android.
+            [iOS] bond is not supported on iOS.
+         */
+        unbond(device_id: string): Promise<void>;
+
+        /* Read the bond state of the remote device.
+            [iOS] readBondState is not supported on iOS.
+         */
+        readBondState(device_id: string): Promise<BondState>;
     }
@@ -353,2 +374,22 @@
         withPromises: BLECentralPluginPromises;
+
+        /* Start the bonding (pairing) process with the remote device. 
+            [iOS] bond is not supported on iOS.
+         */
+        bond(
+            device_id: string,
+            success: () => any,
+            failure?: (error: string) => any,
+            options?: CreateBondOptions
+        ): void;
+
+        /* unbonds a remote device. Note: this uses an unlisted API on Android.
+            [iOS] bond is not supported on iOS.
+         */
+        unbond(device_id: string, success: () => any, failure?: (error: string) => any): void;
+
+        /* Read the bond state of the remote device.
+            [iOS] readBondState is not supported on iOS.
+         */
+        readBondState(device_id: string, success: (state: BondState) => any, failure?: (error: string) => any): void;
     }
@@ -355,0 +396,0 @@ }

www/ble.js

@@ -273,2 +273,14 @@ // (c) 2014-2016 Don Coleman
     },
+
+    bond: function (device_id, success, failure, options) {
+        cordova.exec(success, failure, 'BLE', 'bond', [device_id, options || {}]);
+    },
+
+    unbond: function (device_id, success, failure) {
+        cordova.exec(success, failure, 'BLE', 'unbond', [device_id]);
+    },
+
+    readBondState: function (device_id, success, failure) {
+        cordova.exec(success, failure, 'BLE', 'readBondState', [device_id]);
+    },
 };
@@ -445,2 +457,20 @@
     },
+
+    bond: function (device_id, options) {
+        return new Promise(function (resolve, reject) {
+            module.exports.bond(device_id, resolve, reject, options);
+        });
+    },
+
+    unbond: function (device_id) {
+        return new Promise(function (resolve, reject) {
+            module.exports.unbond(device_id, resolve, reject);
+        });
+    },
+
+    readBondState: function (device_id) {
+        return new Promise(function (resolve, reject) {
+            module.exports.readBondState(device_id, resolve, reject);
+        });
+    },
 };
@@ -447,0 +477,0 @@

No alert changes

Improved metrics

Total package byte prevSize

444167

increased by3.73%

Lines of code

2846

increased by2.3%

Number of lines in readme file

1461

increased by5.79%

No dependency changes