Merge pull request #1 from randdusing/master

update from origin

Author: lei-xiaoming

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "editor.formatOnSave": false
+}

CHANGELOG.md

@@ -1,3 +1,80 @@
+## 6.5.0 - 2021-06-21
+- Operations are queued per device connection rather than globally on Android
+- Use service data if available on Android
+
+## 6.4.1 - 2021-06-08
+- Ensure Android subscriptions are returned in order [\#419](https://github.com/randdusing/cordova-plugin-bluetoothle/issues/419)
+
+## 6.4.0 - 2021-06-08
+- Fix issue with writeQ when peripheral disconnects [\#690](https://github.com/randdusing/cordova-plugin-bluetoothle/issues/690)
+- Add JavaScript helper methods for encoding and decoding Unicode strings
+
+## 6.3.1 - 2021-04-07
+- Fix #retrieveConnected() for Android, Dual Type devices are no longer filtered out. [\#559](https://github.com/randdusing/cordova-plugin-bluetoothle/issues/559)
+
+## 6.3.0 - 2021-02-19
+- Add #retrievePeripheralsByAddress() for iOS and OSX
+
+## 6.2.2 - 2021-02-19
+- Remove ACCESS_BACKGROUND_LOCATION permission. Revert changes from v6.1.1. This should be added manually if background permissions are actually needed
+
+## 6.2.1 - 2021-02-05
+- Update types for NotifyParams
+
+## 6.2.0 - 2020-12-23
+- Add #setPin() method for Android
+
+## 6.1.1 - 2020-12-04
+- Add ACCESS_BACKGROUND_LOCATION permission to fix issue with Android target SDK 29
+
+## 6.1.0 - 2020-11-07
+- Allow specifying transport mode for Android
+
+## 6.0.2 - 2020-10-10
+- Add name when advertising
+
+## 6.0.1 - 2020-09-19
+- Force re-discovery when clearCache => true. [\#634](https://github.com/randdusing/cordova-plugin-bluetoothle/issues/634)
+
+## 6.0.0 - 2020-08-19
+- Fix ordering issue with notifications
+- Potential breaking change - Verify #subscribe() behavior closely!
+
+## 5.0.2 - 2020-08-05
+- Update cordovaDependencies to allow install [\#632](https://github.com/randdusing/cordova-plugin-bluetoothle/issues/632)
+
+## 5.0.1 - 2020-07-31
+- Reset isAdvertising flag when Bluetooth resets [\#302](https://github.com/randdusing/cordova-plugin-bluetoothle/issues/302)
+
+## 5.0.0 - 2020-07-21
+- Improves writeQ performance [\#617](https://github.com/randdusing/cordova-plugin-bluetoothle/issues/617)
+- Potentially breaking change, thus the version bump:
+  - iOS 10 required
+  - writeQ returns a success callback even with iOS's noResponse type. Ignore callback to keep existing behavior
+  - Review writeQ section of [readme](https://github.com/randdusing/cordova-plugin-bluetoothle#writeq)
+
+## 4.5.14 - 2020-06-25
+- Fix NPE in Android [\#615](https://github.com/randdusing/cordova-plugin-bluetoothle/issues/615)
+
+## 4.5.13 - 2020-06-16
+- Use fine location permissions to fix scanning in Android 10 [\#579](https://github.com/randdusing/cordova-plugin-bluetoothle/issues/579)
+
+## 4.5.12 - 2020-06-03
+- Update types
+
+## 4.5.11 - 2020-05-20
+- Reinitialize gatt server when Bluetooth resets [\#302](https://github.com/randdusing/BluetoothLE/issues/302)
+
+## 4.5.10 - 2020-04-10
+- Remove unnecessary check when advertising
+
+## 4.5.9 - 2020-03-13
+- Add null check when disabling scan on newer Android versions
+- Update docs
+
+## 4.5.8 - 2020-03-08
+- Improve connection reliability on Android
+
 ## 4.5.7 - 2020-02-11
 - Stop scan when Bluetooth is disabled on Android v6+
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cordova-plugin-bluetoothle",
-  "version": "4.5.7",
+  "version": "6.5.0",
   "description": "Use the Bluetooth Low Energy plugin to connect your Cordova app to new Bluetooth devices like heart rate monitors, thermometers, etc...",
   "types": "./types/index.d.ts",
   "cordova": {
@@ -32,7 +32,7 @@
         "cordova": ">=5.0.0",
         "cordova-android": ">=5.0.0"
       },
-      "5.0.0": {
+      "7.0.0": {
         "cordova": ">=100"
       }
     }

plugin.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0" xmlns:android="http://schemas.android.com/apk/res/android" xmlns:m2="http://schemas.microsoft.com/appx/2013/manifest" id="cordova-plugin-bluetoothle" version="4.5.7">
+<plugin xmlns="http://apache.org/cordova/ns/plugins/1.0" xmlns:android="http://schemas.android.com/apk/res/android" xmlns:m2="http://schemas.microsoft.com/appx/2013/manifest" id="cordova-plugin-bluetoothle" version="6.5.0">
   <engines>
     <engine name="cordova-plugman" version=">=5.0.0" />
     <engine name="cordova-android" version=">=5.0.0" />
@@ -20,9 +20,11 @@
     </config-file>
     <source-file src="src/android/BluetoothLePlugin.java" target-dir="src/com/randdusing/bluetoothle" />
     <source-file src="src/android/Operation.java" target-dir="src/com/randdusing/bluetoothle" />
+    <source-file src="src/android/SequentialCallbackContext.java" target-dir="src/com/randdusing/bluetoothle" />
     <config-file target="AndroidManifest.xml" parent="/manifest">
       <uses-permission android:name="android.permission.BLUETOOTH"/>
       <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
+      <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
       <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
     </config-file>
   </platform>

readme.md

@@ -1,3 +1,4 @@
+
 # Cordova Bluetooth LE Plugin
 This plugin allows you to interact with Bluetooth LE devices on Android, iOS, and Windows.
 
@@ -62,6 +63,8 @@ This plugin allows you to interact with Bluetooth LE devices on Android, iOS, an
   - [requestPermission](#requestpermission)
   - [isLocationEnabled](#islocationenabled)
   - [requestLocation](#requestlocation)
+  - [setPin](#setPin)
+  - [retrievePeripheralsByAddress](#retrievePeripheralsByAddress)
 - [Peripheral Life Cycle](#peripheral-life-cycle)
   - [Initilization](#initilization)
   - [Notifications](#notifications)
@@ -79,6 +82,8 @@ This plugin allows you to interact with Bluetooth LE devices on Android, iOS, an
   - [bytesToEncodedString](#bytestoencodedstring)
   - [stringToBytes](#stringtobytes)
   - [bytesToString](#bytestostring)
+  - [encodeUnicode](#encodeunicode)
+  - [decodeUnicode](#decodeunicode)
 - [Example](#example)
 - [Data Parsing Example](#data-parsing-example)
 - [Sample: Discover and interact with Bluetooth LE devices](#sample-discover-and-interact-with-bluetooth-le-devices)
@@ -95,8 +100,8 @@ This plugin allows you to interact with Bluetooth LE devices on Android, iOS, an
 ## Requirements ##
 
 * Cordova 5.0.0 or higher
-* Android 4.3 or higher, Android Cordova library 5.0.0 or higher, target Android API 23 or higher
-* iOS 7 or higher
+* Android Cordova library 5.0.0 or higher, target Android API 23/Platform 6.0 or higher (support for older Android versions should use versions 2.4.0 or below)
+* iOS 10 or higher
 * Windows Phone 8.1 (Tested on Nokia Lumia 630)
 * Windows 10 UWP
 * Device hardware must be certified for Bluetooth LE. i.e. Nexus 7 (2012) doesn't support Bluetooth LE even after upgrading to 4.3 (or higher) without a modification
@@ -237,6 +242,7 @@ Neither Android nor iOS support Bluetooth on emulators, so you'll need to test o
 * [bluetoothle.requestPermission](#requestpermission) (Android 6+)
 * [bluetoothle.isLocationEnabled](#islocationenabled) (Android 6+)
 * [bluetoothle.requestLocation](#requestlocation) (Android 6+)
+* [bluetoothle.retrievePeripheralsByAddress](#retrievePeripheralsByAddress) (iOS)
 * [bluetoothle.initializePeripheral](#initializeperipheral)
 * [bluetoothle.addService](#addservice)
 * [bluetoothle.removeService](#removeservice)
@@ -245,10 +251,13 @@ Neither Android nor iOS support Bluetooth on emulators, so you'll need to test o
 * [bluetoothle.stopAdvertising](#stopadvertising)
 * [bluetoothle.respond](#respond)
 * [bluetoothle.notify](#notify)
+* [bluetoothle.setPin](#setPin) (Android)
 * [bluetoothle.encodedStringToBytes](#encodedstringtobytes)
 * [bluetoothle.bytesToEncodedString](#bytestoencodedstring)
 * [bluetoothle.stringToBytes](#stringtobytes)
 * [bluetoothle.bytesToString](#bytestostring)
+* [bluetoothle.encodeUnicode](#encodeunicode)
+* [bluetoothle.decodeUnicode](#decodeunicode)
 
 
 
@@ -286,6 +295,8 @@ Whenever the error callback is executed, the return object will contain the erro
 * isNotConnected - Device isn't connected (Don't call discover or any read/write operations)
 * isDisconnected - Device is disconnected (Don't call disconnect)
 * isBonded - Operation is unsupported. (Is the device Android?)
+* setPin - Operation is unsupported. (Is the device Android?)
+* retrievePeripheralsByAddress - Operation is unsupported (Is the device iOS?)
 
 For example:
 ```javascript
@@ -614,7 +625,7 @@ bluetoothle.connect(connectSuccess, connectError, params);
 ##### Params #####
 * address = The address/identifier provided by the scan's return object
 * autoConnect = Automatically connect as soon as the remote device becomes available (Android)
-
+* transport = Mode of transport - Auto = 0, Prefer BR/EDR = 1, Prefer LE = 2, (Android API 23+)
 ```javascript
 {
   "address": "ECC037FD-72AE-AFC5-9213-CA785B3B5C63"
@@ -1264,6 +1275,8 @@ To write without response, set type to "noResponse". Any other value will defaul
 var string = "Write Hello World";
 var bytes = bluetoothle.stringToBytes(string);
 var encodedString = bluetoothle.bytesToEncodedString(bytes);
+// if your code includes special characters you should use the encodeUnicode helper function
+var encodedUnicodeString = bluetoothle.encodeUnicode(string);
 
 //Note, this example doesn't actually work since it's read only characteristic
 {"value":"V3JpdGUgSGVsbG8gV29ybGQ=","service":"180F","characteristic":"2A19","type":"noResponse","address":"ABC123"}
@@ -1276,24 +1289,33 @@ Value is a base64 encoded string of written bytes. Use bluetoothle.encodedString
 var returnObj = {"status":"written","service":"180F","characteristic":"2A19","value":"V3JpdGUgSGVsbG8gV29ybGQ=","address":"ABC123"}
 var bytes = bluetoothle.encodedStringToBytes(returnObj.value);
 var string = bluetoothle.bytesToString(bytes); //This should equal Write Hello World
+
+// if your code includes special characters you should use the decodeUnicode helper function
+var string = bluetoothle.decodeUnicode(returnObj.value);
 ```
 
 
 
 ### writeQ ###
-Write Quick / Queue, use this method to quickly execute write without response commands when writing more than 20 bytes at a time. The data will automatically be split up into 20 bytes packets. On iOS, these packets are written immediately since iOS uses queues. You probably won't see much of a performance increase using writeQ. On Android, a queue isn't used internally. Instead another call shouldn't be made until onCharacteristicWrite is called. This could be done at the Javascript layer, but the Javascript to plugin "bridge" must be crossed twice, which leads to some significant slow downs when milliseconds make a difference. For even better write throughput, use requestConnectionPriority('high') as well. Note, no callback will occur on write without response on iOS.
+Write Quick / Queue, use this method to quickly execute write without response commands when writing more than 20 bytes at a time. The data will automatically be split up into 20 bytes packets by default or you can increase that by setting `chunkSize`. On iOS, these packets are written immediately since iOS uses queues. You probably won't see much of a performance increase using writeQ unless you use `type="noResponse"` and set `chunkSize` higher than 20. On Android, a queue isn't used internally. Instead another call shouldn't be made until onCharacteristicWrite is called. This could be done at the Javascript layer, but the Javascript to plugin "bridge" must be crossed twice, which leads to some significant slow downs when milliseconds make a difference. For even better write throughput, use requestConnectionPriority('high') and mtu(SAME_VALUE_AS_CHUNK_SIZE_PARAM) as well.
 
 Warnings
 * This is experimental. Test heavily before using in any production code.
-* iOS won't see much performance gain, but Android should.
+* To see a performance gain you should use this in combination with requestConnectionPriority('high') and mtu(`MTU_VALUE`) and then calling this method with `type="noResponse"` and set `chunkSize` to `MTU_VALUE`.
+* Only supported on iOS11+.
 * Only supports one call at a time. Don't execute back to back, use on multiple devices, or multiple characteristics.
 
 ```javascript
 bluetoothle.writeQ(writeSuccess, writeError, params);
 ```
 
 ##### Params #####
-See write() above.
+* address = The address/identifier provided by the scan's return object
+* service = The service's UUID
+* characteristic = The characteristic's UUID
+* value = Base64 encoded string
+* type = Set to "noResponse" to enable write without response, all other values will write normally.
+* chunkSize = Define the size of packets. This should be according to MTU value
 
 ##### Success #####
 See write() above.
@@ -1553,7 +1575,32 @@ bluetoothle.isBonded(isBondedSuccess, isBondedError, params);
 }
 ```
 
+### setPin ###
+Set PIN if required by the pairing process. Android support only.
+
+```javascript
+bluetoothle.setPin(success, error, params);
+```
 
+#### Params ####
+* address = The address/identifier provided by the scan's return object
+* pin = Pairing PIN code
+
+```javascript
+{
+  "address": "5A:94:4B:38:B3:FD",
+  "pin": "1234"
+}
+```
+
+##### Success #####
+* status => string
+
+```javascript
+{
+  "status": "pinSet",
+}
+```
 
 ### wasConnected ###
 Determine whether the device was connected, or error if not initialized.
@@ -1714,6 +1761,38 @@ bluetoothle.requestLocation(requestLocationSuccess, requestLocationError);
 
 
 
+### retrievePeripheralsByAddress ###
+Retrieve paired Bluetooth LE devices based on their address. Wraps the iOS method [CBCentralManager.retrievePeripheralsWithIdentifiers](https://developer.apple.com/documentation/corebluetooth/cbcentralmanager/1519127-retrieveperipheralswithidentifie?language=objc). iOS support only. Will return an error if used on Android.
+
+```javascript
+bluetoothle.retrievePeripheralsByAddress(success, error, params);
+```
+
+##### Params #####
+* addresses = An arrays of addresses/identifiers to lookup devices by. If no addresses are specified, no devices will be returned
+
+```javascript
+{
+  "addresses": ["ECC037FD-72AE-AFC5-9213-CA785B3B5C63"]
+}
+```
+
+##### Success #####
+Returns an array of device objects:
+* name = the device's display name
+* address = the device's address / identifier for connecting to the object
+
+```javascript
+[
+  {
+    "name": "Polar H7 3B321015",
+    "address": "ECC037FD-72AE-AFC5-9213-CA785B3B5C63"
+  }
+]
+```
+
+
+
 ## Peripheral Life Cycle ##
 
 1. initializePeripheral
@@ -2006,7 +2085,7 @@ bluetoothle.isAdvertising(success, error);
 
 
 ### respond ###
-Respond to a read or write request
+Respond to a read or write request. On Android, a device address is required
 
 ```javascript
 bluetoothle.respond(success, error, params);
@@ -2038,7 +2117,7 @@ var params = {
 
 
 ### notify ###
-Update a value for a subscription. Currently all subscribed devices will receive update. Device specific updates will be added in the future. If ```sent``` equals false in the return value, you must wait for the ```peripheralManagerIsReadyToUpdateSubscribers``` event before sending more updates.
+Update a value for a subscription. Currently all subscribed devices will receive updates on iOS. Device specific updates will be added in the future. On Android, a device address is required. If ```sent``` equals false in the return value, you must wait for the ```peripheralManagerIsReadyToUpdateSubscribers``` event before sending more updates.
 
 ```javascript
 bluetoothle.notify(success, error, params);
@@ -2050,6 +2129,7 @@ var params = {
   "service":"1234",
   "characteristic":"ABCD",
   "value":"U3Vic2NyaWJlIEhlbGxvIFdvcmxk" //Subscribe Hello World
+  // "address": "5163F1E0-5341-AF9B-9F67-613E15EC83F7" // only on android
 };
 ```
 
@@ -2172,6 +2252,20 @@ if (obj.status == "subscribedResult")
 }
 ```
 
+### encodeUnicode ###
+Helper function to convert unicode string to base64 encoded string. This function can be used to encode special characters such as emojis.
+
+```javascript
+bluetoothle.encodeUnicode(string);
+```
+
+### decodeUnicode ###
+Helper function to convert a base64 encoded string to unicode string. This function also decodes special characters such as emojis.
+
+```javascript
+bluetoothle.decodeUnicode(string);
+```
+
 ## Sample: Discover and interact with Bluetooth LE devices ##
 
 We'll build an app that lets you discover Bluetooth Low Energy (LE) devices that are around you, connect to a one, and then look at all of the information that you can obtain from that device such as signal strength, supported services, battery level and more.