react-native-ble-manager 8.8.0 → 9.0.0

package/README.md

@@ -4,7 +4,13 @@
 [![npm downloads](https://img.shields.io/npm/dm/react-native-ble-manager.svg?style=flat)](https://www.npmjs.com/package/react-native-ble-manager)
 [![GitHub issues](https://img.shields.io/github/issues/innoveit/react-native-ble-manager.svg?style=flat)](https://github.com/innoveit/react-native-ble-manager/issues)
 
-This is a porting of https://github.com/don/cordova-plugin-ble-central project to React Native.
+A React Native Bluetooth Low Energy library.
+
+Originally inspired by https://github.com/don/cordova-plugin-ble-central.
+
+## Introduction
+
+The library is a simple connection with the OS APIs, the BLE stack should be standard but often has different behaviors based on the device used, the operating system and the BLE chip it connects to. Before opening an issue verify that the problem is really the library.
 
 ## Requirements
 
@@ -35,28 +41,41 @@ The library support the react native autolink feature.
     xmlns:tools="http://schemas.android.com/tools"
     package="YOUR_PACKAGE_NAME">
 
-    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
-    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
+    <!--
+      HACK: this permission should not be needed on android 12+ devices anymore,
+      but in fact some manufacturers still need it for BLE to properly work : 
+      https://stackoverflow.com/a/72370969
+    -->
+    <uses-permission android:name="android.permission.BLUETOOTH" tools:remove="android:maxSdkVersion" />
+    <!--
+      should normally only be needed on android < 12 if you want to:
+      - activate bluetooth programmatically
+      - discover local BLE devices
+      see: https://developer.android.com/guide/topics/connectivity/bluetooth/permissions#discover-local-devices.
+      Same as above, may still be wrongly needed by some manufacturers on android 12+.
+     -->
+    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" tools:remove="android:maxSdkVersion" />
 
     <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="28"/>
-    <uses-permission-sdk-23 android:name="android.permission.ACCESS_FINE_LOCATION" tools:targetApi="Q"/>
+    <uses-permission-sdk-23 android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30"/>
 
     <!-- Only when targeting Android 12 or higher -->
-    <!-- Please make sure you read the following documentation to have a
-         better understanding of the new permissions.
-         https://developer.android.com/guide/topics/connectivity/bluetooth/permissions#assert-never-for-location
-         -->
-
-    <!-- If your app doesn't use Bluetooth scan results to derive physical location information,
-         you can strongly assert that your app
-         doesn't derive physical location. -->
-    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" 
-                     android:usesPermissionFlags="neverForLocation"
-                     tools:targetApi="s" />
-
-    <!-- Needed only if your app looks for Bluetooth devices. -->
-    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
-    <!-- Needed only if your app makes the device discoverable to Bluetooth devices. -->
+    <!-- 
+      Please make sure you read the following documentation
+      to have a better understanding of the new permissions.
+      https://developer.android.com/guide/topics/connectivity/bluetooth/permissions#assert-never-for-location
+    -->
+
+    <!-- Needed if your app search for Bluetooth devices. -->
+     <!--
+      If your app doesn't use Bluetooth scan results to derive physical location information,
+      you can strongly assert that your app doesn't derive physical location.
+    -->
+    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
+                     android:usesPermissionFlags="neverForLocation" />
+    <!-- Needed if you want to interact with a BLE device. -->
+    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
+    <!-- Needed if your app makes the current device discoverable to other Bluetooth devices. -->
     <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
 ...
 ```
@@ -75,7 +94,7 @@ In iOS >= 13 you need to add the `NSBluetoothAlwaysUsageDescription` string key.
 - Android API >= 29 require the ACCESS_FINE_LOCATION permission to scan for peripherals.
    React-Native 0.63.X started targeting Android API 29.
 - Before write, read or start notification you need to call `retrieveServices` method
-- Because location and bluetooth permissions are runtime permissions, you **must** request these permissions at runtime along with declaring them    in your manifest.
+- Because location and bluetooth permissions are runtime permissions, you **must** request these permissions at runtime along with declaring them in your manifest.
 
 ## Example
 
@@ -86,11 +105,14 @@ The easiest way to test is simple make your AppRegistry point to our example com
 import React, { Component } from "react";
 import { AppRegistry } from "react-native";
 import App from "react-native-ble-manager/example/App"; //<-- simply point to the example js!
-
+/* 
+Note: The react-native-ble-manager/example directory is only included when cloning the repo, the above import will not work 
+if trying to import react-native-ble-manager/example from node_modules
+*/
 AppRegistry.registerComponent("MyAwesomeApp", () => App);
 ```
 
-Or, you can still look into the whole [example](https://github.com/innoveit/react-native-ble-manager/tree/master/example) folder for a standalone project.
+Or, [use the example directly](example)
 
 ## Methods
 
@@ -131,13 +153,14 @@ Returns a `Promise` object.
 - `seconds` - `Integer` - the amount of seconds to scan.
 - `allowDuplicates` - `Boolean` - [iOS only] allow duplicates in device scanning
 - `scanningOptions` - `JSON` - [Android only] after Android 5.0, user can control specific ble scan behaviors:
-  - `numberOfMatches` - `Number` - [Android only] corresponding to [`setNumOfMatches`](<https://developer.android.com/reference/android/bluetooth/le/ScanSettings.Builder.html#setNumOfMatches(int)>). Defaults to `ScanSettings.MATCH_NUM_MAX_ADVERTISEMENT`.
+  - `numberOfMatches` - `Number` - [Android only] corresponding to [`setNumOfMatches`](<https://developer.android.com/reference/android/bluetooth/le/ScanSettings.Builder.html#setNumOfMatches(int)>). Defaults to `ScanSettings.MATCH_NUM_MAX_ADVERTISEMENT`. /!\ anything other than default may only work when a `ScanFilter` is active /!\
   - `matchMode` - `Number` - [Android only] corresponding to [`setMatchMode`](<https://developer.android.com/reference/android/bluetooth/le/ScanSettings.Builder.html#setMatchMode(int)>). Defaults to `ScanSettings.MATCH_MODE_AGGRESSIVE`.
-  - `callbackType` - `Number` - [Android only] corresponding to [`setCallbackType`](<https://developer.android.com/reference/android/bluetooth/le/ScanSettings.Builder.html#setCallbackType(int)>). Defaults `ScanSettings.CALLBACK_TYPE_ALL_MATCHES`.
+  - `callbackType` - `Number` - [Android only] corresponding to [`setCallbackType`](<https://developer.android.com/reference/android/bluetooth/le/ScanSettings.Builder.html#setCallbackType(int)>). Defaults `ScanSettings.CALLBACK_TYPE_ALL_MATCHES`. /!\ anything other than default may only work when a `ScanFilter` is active /!\
   - `scanMode` - `Number` - [Android only] corresponding to [`setScanMode`](<https://developer.android.com/reference/android/bluetooth/le/ScanSettings.Builder.html#setScanMode(int)>). Defaults to `ScanSettings.SCAN_MODE_LOW_POWER`.
   - `reportDelay` - `Number` - [Android only] corresponding to [`setReportDelay`](<https://developer.android.com/reference/android/bluetooth/le/ScanSettings.Builder.html#setReportDelay(long)>). Defaults to `0ms`.
   - `phy` - `Number` - [Android only] corresponding to [`setPhy`](https://developer.android.com/reference/android/bluetooth/le/ScanSettings.Builder#setPhy(int))
   - `legacy` - `Boolean` - [Android only] corresponding to [`setLegacy`](https://developer.android.com/reference/android/bluetooth/le/ScanSettings.Builder#setLegacy(boolean))
+  - `exactAdvertisingName` - `string` - [Android only] corresponds to the `ScanFilter` [deviceName](https://developer.android.com/reference/android/bluetooth/le/ScanFilter.Builder#setDeviceName(java.lang.String))
 
 **Examples**
 
@@ -238,12 +261,13 @@ BleManager.enableBluetooth()
 
 ### checkState()
 
-Force the module to check the state of BLE and trigger a BleManagerDidUpdateState event.
+Force the module to check the state of the native BLE manager and trigger a BleManagerDidUpdateState event.
+Resolves to a promise containing the current BleState.
 
 **Examples**
 
 ```js
-BleManager.checkState();
+BleManager.checkState().then(state => console.log(`current BLE state = '${state}'.`));
 ```
 
 ### startNotification(peripheralId, serviceUUID, characteristicUUID)
@@ -320,7 +344,8 @@ Returns a `Promise` object.
 ### read(peripheralId, serviceUUID, characteristicUUID)
 
 Read the current value of the specified characteristic, you need to call `retrieveServices` method before.
-Returns a `Promise` object.
+Returns a `Promise` object that will resolves to an array of plain integers (`number[]`) representing a `ByteArray` structure.
+That array can then be converted to a JS `ArrayBuffer` for example using `Buffer.from()` [thanks to this buffer module](https://github.com/feross/buffer).
 
 **Arguments**
 
@@ -340,7 +365,9 @@ BleManager.read(
     // Success code
     console.log("Read: " + readData);
 
-    const buffer = Buffer.Buffer.from(readData); //https://github.com/feross/buffer#convert-arraybuffer-to-buffer
+    // https://github.com/feross/buffer
+    // https://nodejs.org/api/buffer.html#static-method-bufferfromarray
+    const buffer = Buffer.from(readData); 
     const sensorData = buffer.readUInt8(1, true);
   })
   .catch((error) => {
@@ -359,25 +386,31 @@ Returns a `Promise` object.
 - `peripheralId` - `String` - the id/mac address of the peripheral.
 - `serviceUUID` - `String` - the UUID of the service.
 - `characteristicUUID` - `String` - the UUID of the characteristic.
-- `data` - `Byte array` - the data to write.
+- `data` - `number[]` - the data to write as a plain integer array representing a `ByteArray` structure.
 - `maxByteSize` - `Integer` - specify the max byte size before splitting message, defaults to 20 bytes if not specified
 
 **Data preparation**
 
-If your data is not in byte array format you should convert it first. For strings you can use `convert-string` or other npm package in order to achieve that.
-Install the package first:
-
-```shell
-npm install convert-string
-```
+To convert your data to a `number[]`, you should probably be manipulating a `Buffer` or anything representing a JS `ArrayBuffer`.
+This will make sure you are converting from valid byte representations of your data first and not with [an integer outside the expected range](https://techtutorialsx.com/2019/10/27/node-js-converting-array-to-buffer/).
 
-Then use it in your application:
+You can create a buffer from files, numbers or strings easily (see examples bellow).
 
 ```js
-// Import/require in the beginning of the file
-import { stringToBytes } from "convert-string";
-// Convert data to byte array before write/writeWithoutResponse
-const data = stringToBytes(yourStringData);
+// https://github.com/feross/buffer
+import { Buffer } from 'buffer';
+
+ * // Creates a Buffer containing the bytes [0x01, 0x02, 0x03].
+ * const buffer = Buffer.from([1, 2, 3]);
+ *
+ * // Creates a Buffer containing the bytes [0x01, 0x01, 0x01, 0x01] – the entries
+ * // are all truncated using `(value & 255)` to fit into the range 0–255.
+ * const buffer = Buffer.from([257, 257.5, -255, '1']);
+ *
+ * // Creates a Buffer containing the UTF-8-encoded bytes for the string 'tést':
+ * // [0x74, 0xc3, 0xa9, 0x73, 0x74] (in hexadecimal notation)
+ * // [116, 195, 169, 115, 116] (in decimal notation)
+ * const buffer = Buffer.from('tést');
 ```
 
 Feel free to use other packages or google how to convert into byte array if your data has other format.
@@ -389,7 +422,9 @@ BleManager.write(
   "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
   "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
   "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
-  data
+  // encode & extract raw `number[]`.
+  // Each number should be in the 0-255 range as it is converted from a valid byte.
+  buffer.toJSON().data
 )
   .then(() => {
     // Success code
@@ -411,13 +446,13 @@ Returns a `Promise` object.
 - `peripheralId` - `String` - the id/mac address of the peripheral.
 - `serviceUUID` - `String` - the UUID of the service.
 - `characteristicUUID` - `String` - the UUID of the characteristic.
-- `data` - `Byte array` - the data to write.
+- `data` - `number[]` - the data to write as a plain integer array representing a `ByteArray` structure. (see `write()`).
 - `maxByteSize` - `Integer` - (Optional) specify the max byte size
 - `queueSleepTime` - `Integer` - (Optional) specify the wait time before each write if the data is greater than maxByteSize
 
 **Data preparation**
 
-If your data is not in byte array format check info for the write function above.
+If your data is not in `number[]` format check info fom the `write()` function example above.
 
 **Example**
 
@@ -576,7 +611,7 @@ BleManager.getConnectedPeripherals([]).then((peripheralsArray) => {
 ### createBond(peripheralId,peripheralPin) [Android only]
 
 Start the bonding (pairing) process with the remote device. If you pass peripheralPin(optional), bonding will be auto(without manual entering pin)
-Returns a `Promise` object. The promise is resolved when either `new bond successfully created` or `bond already existed`, otherwise it will be rejected.
+Returns a `Promise` object that will resolves if the bond is successfully created, otherwise it will be rejected with the appropriate error message.
 
 **Examples**
 
@@ -838,3 +873,17 @@ The peripheral received a request to start or stop providing notifications for a
 - `isNotifying` - `Boolean` - Is the characteristic notifying or not
 - `domain` - `String` - [iOS only] error domain
 - `code` - `Number` - [iOS only] error code
+
+## Library development
+
+- the library is written in typescript and needs to be built before being used for publication or local development, using the provided npm scripts in `package.json`.
+- the local `example` project is configured to work with the locally built version of the library. To be able to run it, you need to build at least once the library so that its outputs listed as entrypoint in `package.json` (in the `dist` folder) are properly generated for consumption by the example project:
+
+from the root folder:
+
+```shell
+npm install
+npm run build
+```
+
+> if you are modifying the typescript files of the library (in `src/`) on the fly, you can run `npm run watch` instead. If you are modifying files from the native counterparts, you'll need to rebuild the whole app for your target environnement (`npm run android/ios`).

package/android/.gradle/buildOutputCleanup/cache.properties

@@ -0,0 +1,2 @@
+#Wed Dec 14 11:37:11 CET 2022
+gradle.version=7.4

package/android/.idea/.name

@@ -0,0 +1 @@
+react-native-ble-manager

package/android/.idea/compiler.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="CompilerConfiguration">
+    <bytecodeTargetLevel target="1.8" />
+  </component>
+</project>

package/android/.idea/gradle.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="GradleMigrationSettings" migrationVersion="1" />
+  <component name="GradleSettings">
+    <option name="linkedExternalProjectsSettings">
+      <GradleProjectSettings>
+        <option name="testRunner" value="GRADLE" />
+        <option name="distributionType" value="DEFAULT_WRAPPED" />
+        <option name="externalProjectPath" value="$PROJECT_DIR$" />
+        <option name="modules">
+          <set>
+            <option value="$PROJECT_DIR$" />
+          </set>
+        </option>
+      </GradleProjectSettings>
+    </option>
+  </component>
+</project>

package/android/.idea/jarRepositories.xml

@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="RemoteRepositoriesConfiguration">
+    <remote-repository>
+      <option name="id" value="central" />
+      <option name="name" value="Maven Central repository" />
+      <option name="url" value="https://repo1.maven.org/maven2" />
+    </remote-repository>
+    <remote-repository>
+      <option name="id" value="jboss.community" />
+      <option name="name" value="JBoss Community repository" />
+      <option name="url" value="https://repository.jboss.org/nexus/content/repositories/public/" />
+    </remote-repository>
+    <remote-repository>
+      <option name="id" value="maven" />
+      <option name="name" value="maven" />
+      <option name="url" value="file:$PROJECT_DIR$/../node_modules/react-native/android" />
+    </remote-repository>
+    <remote-repository>
+      <option name="id" value="MavenRepo" />
+      <option name="name" value="MavenRepo" />
+      <option name="url" value="https://repo.maven.apache.org/maven2/" />
+    </remote-repository>
+    <remote-repository>
+      <option name="id" value="BintrayJCenter" />
+      <option name="name" value="BintrayJCenter" />
+      <option name="url" value="https://jcenter.bintray.com/" />
+    </remote-repository>
+    <remote-repository>
+      <option name="id" value="Google" />
+      <option name="name" value="Google" />
+      <option name="url" value="https://dl.google.com/dl/android/maven2/" />
+    </remote-repository>
+    <remote-repository>
+      <option name="id" value="maven" />
+      <option name="name" value="maven" />
+      <option name="url" value="file:$PROJECT_DIR$/../example/node_modules/react-native/android" />
+    </remote-repository>
+  </component>
+</project>

package/android/.idea/misc.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ExternalStorageConfigurationManager" enabled="true" />
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_1_8" default="true" project-jdk-name="Android Studio default JDK" project-jdk-type="JavaSDK">
+    <output url="file://$PROJECT_DIR$/build/classes" />
+  </component>
+  <component name="ProjectType">
+    <option name="id" value="Android" />
+  </component>
+</project>

package/android/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$/.." vcs="Git" />
+  </component>
+</project>

package/android/build.gradle

@@ -1,27 +1,27 @@
 buildscript {
-    // The Android Gradle plugin is only required when opening the android folder stand-alone.
-    // This avoids unnecessary downloads and potential conflicts when the library is included as a
-    // module dependency in an application project.
-    if (project == rootProject) {
-        repositories {
-            google()
-            jcenter()
-        }
-
-        dependencies {
-            classpath("com.android.tools.build:gradle:4.2.2")
-        }
-    }
+	// The Android Gradle plugin is only required when opening the android folder stand-alone.
+	// This avoids unnecessary downloads and potential conflicts when the library is included as a
+	// module dependency in an application project.
+	if (project == rootProject) {
+		repositories {
+			google()
+			jcenter()
+		}
+
+		dependencies {
+			classpath("com.android.tools.build:gradle:7.3.1")
+		}
+	}
 }
 apply plugin: 'com.android.library'
 
 def safeExtGet(prop, fallback) {
-    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+	rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
 }
 
 android {
-	compileSdkVersion safeExtGet("compileSdkVersion", 30)
-	
+	compileSdkVersion safeExtGet("compileSdkVersion", 31)
+
 	compileOptions {
 		sourceCompatibility JavaVersion.VERSION_1_8
 		targetCompatibility JavaVersion.VERSION_1_8
@@ -50,4 +50,4 @@ repositories {
 dependencies {
 	implementation "com.facebook.react:react-native:+"
 //	implementation "org.jetbrains.trove4j: trove4j: 20160824"
-}
+}

package/android/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.4-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

package/android/gradle.properties

@@ -1,2 +1,4 @@
 android.useAndroidX=true
-android.enableJetifier=true
+android.enableJetifier=true
+# https://github.com/facebook/react-native/issues/35168
+org.gradle.jvmargs=-Xmx4096M