react-native-ble-manager - npm Package Compare versions

Comparing version 8.8.0 to 9.0.0

package.json

 {
   "name": "react-native-ble-manager",
-  "version": "8.8.0",
+  "version": "9.0.0",
   "description": "A BLE module for react native.",
-  "main": "BleManager",
-  "types": "./index.d.ts",
   "repository": {
@@ -27,6 +25,35 @@ "type": "git",
   },
+  "main": "dist/cjs/index.js",
+  "types": "dist/esm/index.d.ts",
+  "module": "dist/esm/index.js",
+  "react-native": "src/index.ts",
+  "files": [
+    "/dist",
+    "/src",
+    "/android",
+    "!/android/build",
+    "/ios",
+    "/*.podspec"
+  ],
   "scripts": {
     "version": "git add -A",
-    "postversion": "git push && git push --tags"
+    "clean": "rimraf dist",
+    "type:check": "tsc -p tsconfig.json --noEmit",
+    "prebuild": "npm run clean",
+    "build:cjs": "tsc --module commonjs --outDir dist/cjs",
+    "build:esm": "tsc --outDir dist/esm",
+    "build": "npm run build:esm && npm run build:cjs",
+    "watch": "npm run build --watch",
+    "prepare": "npm run build",
+    "preversion": "npm run build",
+    "postversion": "git push --follow-tags"
+  },
+  "peerDependencies": {
+    "react-native": ">=0.60.0"
+  },
+  "devDependencies": {
+    "react-native": "0.71.0",
+    "rimraf": "4.1.2",
+    "typescript": "4.9.5"
   }
 }

README.md

@@ -7,4 +7,10 @@ # react-native-ble-manager
 
-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
@@ -39,24 +45,37 @@
 
-    <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
-         -->
+    <!-- 
+      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. -->
+    <!-- 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" />
@@ -80,3 +99,3 @@ ...
 - 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.
 
@@ -92,7 +111,10 @@ ## Example
 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)
 
@@ -138,5 +160,5 @@ ## Methods
 - `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`.
@@ -146,2 +168,3 @@ - `reportDelay` - `Number` - [Android only] corresponding to [`setReportDelay`](<https://developer.android.com/reference/android/bluetooth/le/ScanSettings.Builder.html#setReportDelay(long)>). Defaults to `0ms`.
   - `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))
 
@@ -247,3 +270,4 @@ **Examples**
 
-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.
 
@@ -253,3 +277,3 @@ **Examples**
 ```js
-BleManager.checkState();
+BleManager.checkState().then(state => console.log(`current BLE state = '${state}'.`));
 ```
@@ -331,3 +355,4 @@
 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).
 
@@ -352,3 +377,5 @@ **Arguments**
 
-    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);
@@ -372,3 +399,3 @@ })
 - `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
@@ -378,16 +405,22 @@
 
-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:
+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/).
 
-```shell
-npm install convert-string
-```
+You can create a buffer from files, numbers or strings easily (see examples bellow).
 
-Then use it in your application:
+```js
+// https://github.com/feross/buffer
+import { Buffer } from 'buffer';
 
-```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);
+ * // 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');
 ```
@@ -404,3 +437,5 @@
   "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
 )
@@ -427,3 +462,3 @@ .then(() => {
 - `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
@@ -434,3 +469,3 @@ - `queueSleepTime` - `Integer` - (Optional) specify the wait time before each write if the data is greater than maxByteSize
 
-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.
 
@@ -594,3 +629,3 @@ **Example**
 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.
 
@@ -857,1 +892,15 @@ **Examples**
 - `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`).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Native code

Supply chain risk

Contains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.

Found 6 instances in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

520420

increased by134.73%

Number of package files

71

increased by108.82%

Lines of code

2923

increased by358.15%

Number of lines in readme file

890

increased by5.83%

Worsened metrics

Dependency count

1

increased byInfinity%

Dev dependency count

3

increased byInfinity%

Number of medium supply chain risk alerts

7

increased byInfinity%

No dependency changes