@capacitor-community/bluetooth-le 3.0.1 → 3.0.2

package/README.md

@@ -13,7 +13,7 @@
   <a href="https://www.npmjs.com/package/@capacitor-community/bluetooth-le"><img src="https://img.shields.io/npm/dw/@capacitor-community/bluetooth-le?style=flat-square" /></a>
   <a href="https://www.npmjs.com/package/@capacitor-community/bluetooth-le"><img src="https://img.shields.io/npm/v/@capacitor-community/bluetooth-le?style=flat-square" /></a>
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
-<a href="#contributors-"><img src="https://img.shields.io/badge/all%20contributors-11-orange?style=flat-square" /></a>
+<a href="#contributors-"><img src="https://img.shields.io/badge/all%20contributors-14-orange?style=flat-square" /></a>
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 </p>
 
@@ -207,6 +207,8 @@ import { BleClient } from '@capacitor-community/bluetooth-le';
 import { BluetoothLe } from '@capacitor-community/bluetooth-le';
 ```
 
+### Heart rate monitor
+
 Here is an example of how to use the plugin. It shows how to read the heart rate from a BLE heart rate monitor such as the Polar H10.
 
 ```typescript
@@ -279,7 +281,9 @@ function parseHeartRate(value: DataView): number {
 }
 ```
 
-An example of using the scanning API:
+### Scanning API
+
+Here is an example of using the scanning API.
 
 ```typescript
 import { BleClient, numberToUUID } from '@capacitor-community/bluetooth-le';
@@ -608,15 +612,16 @@ Connect to a peripheral BLE device. For an example, see [usage](#usage).
 ### createBond(...)
 
 ```typescript
-createBond(deviceId: string) => Promise<void>
+createBond(deviceId: string, options?: TimeoutOptions | undefined) => Promise<void>
 ```
 
 Create a bond with a peripheral BLE device.
 Only available on **Android**. On iOS bonding is handled by the OS.
 
-| Param          | Type                | Description                                                                                                    |
-| -------------- | ------------------- | -------------------------------------------------------------------------------------------------------------- |
-| **`deviceId`** | <code>string</code> | The ID of the device to use (obtained from [requestDevice](#requestDevice) or [requestLEScan](#requestLEScan)) |
+| Param          | Type                                                      | Description                                                                                                    |
+| -------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **`deviceId`** | <code>string</code>                                       | The ID of the device to use (obtained from [requestDevice](#requestDevice) or [requestLEScan](#requestLEScan)) |
+| **`options`**  | <code><a href="#timeoutoptions">TimeoutOptions</a></code> | Options for plugin call                                                                                        |
 
 ---
 
@@ -1046,6 +1051,23 @@ await BleClient.disconnect(device.deviceId);
 await BleClient.connect(device.deviceId);
 ```
 
+#### No devices found on Android
+
+On Android, the `initialize` call requests the location permission. However, if location services are disable on the OS level, the app will not find any devices. You can check if the location is enabled and open the settings when not.
+
+```typescript
+async function initialize() {
+  // Check if location is enabled
+  if (this.platform.is('android')) {
+    const isLocationEnabled = await BleClient.isLocationEnabled();
+    if (!isLocationEnabled) {
+      await BleClient.openLocationSettings();
+    }
+  }
+  await BleClient.initialize();
+}
+```
+
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
@@ -1069,6 +1091,9 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/aadito123"><img src="https://avatars.githubusercontent.com/u/63646058?v=4?s=100" width="100px;" alt="Aadit Olkar"/><br /><sub><b>Aadit Olkar</b></sub></a><br /><a href="https://github.com/capacitor-community/bluetooth-le/commits?author=aadito123" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/y3nd"><img src="https://avatars.githubusercontent.com/u/18102153?v=4?s=100" width="100px;" alt="Yoann N."/><br /><sub><b>Yoann N.</b></sub></a><br /><a href="https://github.com/capacitor-community/bluetooth-le/commits?author=y3nd" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Andy3189"><img src="https://avatars.githubusercontent.com/u/2084016?v=4?s=100" width="100px;" alt="Andy3189"/><br /><sub><b>Andy3189</b></sub></a><br /><a href="https://github.com/capacitor-community/bluetooth-le/commits?author=Andy3189" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/RFM69CW"><img src="https://avatars.githubusercontent.com/u/20404734?v=4?s=100" width="100px;" alt="Sammy"/><br /><sub><b>Sammy</b></sub></a><br /><a href="https://github.com/capacitor-community/bluetooth-le/commits?author=RFM69CW" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/td-tomasz-joniec"><img src="https://avatars.githubusercontent.com/u/109506928?v=4?s=100" width="100px;" alt="td-tomasz-joniec"/><br /><sub><b>td-tomasz-joniec</b></sub></a><br /><a href="https://github.com/capacitor-community/bluetooth-le/commits?author=td-tomasz-joniec" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://fanxj.com"><img src="https://avatars.githubusercontent.com/u/10436013?v=4?s=100" width="100px;" alt="Michele Ferrari"/><br /><sub><b>Michele Ferrari</b></sub></a><br /><a href="https://github.com/capacitor-community/bluetooth-le/commits?author=micheleypf" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>

package/android/src/main/java/com/capacitorjs/community/plugins/bluetoothle/BluetoothLe.kt

@@ -1,6 +1,7 @@
 package com.capacitorjs.community.plugins.bluetoothle
 
 import android.Manifest
+import android.annotation.SuppressLint
 import android.bluetooth.BluetoothAdapter
 import android.bluetooth.BluetoothDevice
 import android.bluetooth.BluetoothGatt
@@ -36,6 +37,7 @@ import com.getcapacitor.annotation.PermissionCallback
 import java.util.UUID
 
 
+@SuppressLint("MissingPermission")
 @CapacitorPlugin(
     name = "BluetoothLe",
     permissions = [
@@ -96,8 +98,7 @@ class BluetoothLe : Plugin() {
 
     @PluginMethod
     fun initialize(call: PluginCall) {
-        // Build.VERSION_CODES.S = 31
-        if (Build.VERSION.SDK_INT >= 31) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
             val neverForLocation = call.getBoolean("androidNeverForLocation", false) as Boolean
             aliases = if (neverForLocation) {
                 arrayOf(
@@ -439,7 +440,8 @@ class BluetoothLe : Plugin() {
     @PluginMethod
     fun createBond(call: PluginCall) {
         val device = getOrCreateDevice(call) ?: return
-        device.createBond { response ->
+        val timeout = call.getFloat("timeout", DEFAULT_TIMEOUT)!!.toLong()
+        device.createBond(timeout) { response ->
             run {
                 if (response.success) {
                     call.resolve()

package/android/src/main/java/com/capacitorjs/community/plugins/bluetoothle/Device.kt

@@ -1,5 +1,7 @@
 package com.capacitorjs.community.plugins.bluetoothle
 
+import android.annotation.SuppressLint
+import android.annotation.TargetApi
 import android.bluetooth.BluetoothAdapter
 import android.bluetooth.BluetoothDevice
 import android.bluetooth.BluetoothGatt
@@ -8,6 +10,7 @@ import android.bluetooth.BluetoothGattCharacteristic
 import android.bluetooth.BluetoothGattDescriptor
 import android.bluetooth.BluetoothGattService
 import android.bluetooth.BluetoothProfile
+import android.bluetooth.BluetoothStatusCodes
 import android.content.BroadcastReceiver
 import android.content.Context
 import android.content.Intent
@@ -15,6 +18,7 @@ import android.content.IntentFilter
 import android.os.Build
 import android.os.Handler
 import android.os.Looper
+import androidx.annotation.RequiresApi
 import com.getcapacitor.Logger
 import java.util.UUID
 import java.util.concurrent.ConcurrentLinkedQueue
@@ -43,6 +47,7 @@ fun <T> ConcurrentLinkedQueue<T>.popFirstMatch(predicate: (T) -> Boolean): T? {
     }
 }
 
+@SuppressLint("MissingPermission")
 class Device(
     private val context: Context,
     bluetoothAdapter: BluetoothAdapter,
@@ -123,9 +128,15 @@ class Device(
             }
         }
 
+        @TargetApi(Build.VERSION_CODES.S_V2)
         override fun onCharacteristicRead(
             gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int
         ) {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                // handled by new callback below
+                return
+            }
+            Logger.verbose(TAG, "Using deprecated onCharacteristicRead.")
             super.onCharacteristicRead(gatt, characteristic, status)
             val key = "read|${characteristic.service.uuid}|${characteristic.uuid}"
             if (status == BluetoothGatt.GATT_SUCCESS) {
@@ -141,6 +152,24 @@ class Device(
             }
         }
 
+        @RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
+        override fun onCharacteristicRead(
+            gatt: BluetoothGatt,
+            characteristic: BluetoothGattCharacteristic,
+            data: ByteArray,
+            status: Int
+        ) {
+            Logger.verbose(TAG, "Using onCharacteristicRead from API level 33.")
+            super.onCharacteristicRead(gatt, characteristic, data, status)
+            val key = "read|${characteristic.service.uuid}|${characteristic.uuid}"
+            if (status == BluetoothGatt.GATT_SUCCESS) {
+                val value = bytesToString(data)
+                resolve(key, value)
+            } else {
+                reject(key, "Reading characteristic failed.")
+            }
+        }
+
         override fun onCharacteristicWrite(
             gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int
         ) {
@@ -154,9 +183,15 @@ class Device(
 
         }
 
+        @TargetApi(Build.VERSION_CODES.S_V2)
         override fun onCharacteristicChanged(
             gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic
         ) {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                // handled by new callback below
+                return
+            }
+            Logger.verbose(TAG, "Using deprecated onCharacteristicChanged.")
             super.onCharacteristicChanged(gatt, characteristic)
             val notifyKey = "notification|${characteristic.service.uuid}|${characteristic.uuid}"
             val data = characteristic.value
@@ -166,9 +201,26 @@ class Device(
             }
         }
 
+        @RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
+        override fun onCharacteristicChanged(
+            gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, data: ByteArray
+        ) {
+            Logger.verbose(TAG, "Using onCharacteristicChanged from API level 33.")
+            super.onCharacteristicChanged(gatt, characteristic, data)
+            val notifyKey = "notification|${characteristic.service.uuid}|${characteristic.uuid}"
+            val value = bytesToString(data)
+            callbackMap[notifyKey]?.invoke(CallbackResponse(true, value))
+        }
+
+        @TargetApi(Build.VERSION_CODES.S_V2)
         override fun onDescriptorRead(
             gatt: BluetoothGatt, descriptor: BluetoothGattDescriptor, status: Int
         ) {
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                // handled by new callback below
+                return
+            }
+            Logger.verbose(TAG, "Using deprecated onDescriptorRead.")
             super.onDescriptorRead(gatt, descriptor, status)
             val key =
                 "readDescriptor|${descriptor.characteristic.service.uuid}|${descriptor.characteristic.uuid}|${descriptor.uuid}"
@@ -185,6 +237,22 @@ class Device(
             }
         }
 
+        @RequiresApi(api = Build.VERSION_CODES.TIRAMISU)
+        override fun onDescriptorRead(
+            gatt: BluetoothGatt, descriptor: BluetoothGattDescriptor, status: Int, data: ByteArray
+        ) {
+            Logger.verbose(TAG, "Using onDescriptorRead from API level 33.")
+            super.onDescriptorRead(gatt, descriptor, status, data)
+            val key =
+                "readDescriptor|${descriptor.characteristic.service.uuid}|${descriptor.characteristic.uuid}|${descriptor.uuid}"
+            if (status == BluetoothGatt.GATT_SUCCESS) {
+                val value = bytesToString(data)
+                resolve(key, value)
+            } else {
+                reject(key, "Reading descriptor failed.")
+            }
+        }
+
         override fun onDescriptorWrite(
             gatt: BluetoothGatt, descriptor: BluetoothGattDescriptor, status: Int
         ) {
@@ -256,7 +324,7 @@ class Device(
         return bluetoothGatt?.requestConnectionPriority(connectionPriority) ?: false
     }
 
-    fun createBond(callback: (CallbackResponse) -> Unit) {
+    fun createBond(timeout: Long, callback: (CallbackResponse) -> Unit) {
         val key = "createBond"
         callbackMap[key] = callback
         try {
@@ -277,6 +345,7 @@ class Device(
             return
         }
         // otherwise, wait for bond state change
+        setTimeout(key, "Bonding timeout.", timeout)
     }
 
     private fun createBondStateReceiver() {
@@ -287,7 +356,14 @@ class Device(
                     if (action == BluetoothDevice.ACTION_BOND_STATE_CHANGED) {
                         val key = "createBond"
                         val updatedDevice =
-                            intent.getParcelableExtra<BluetoothDevice>(BluetoothDevice.EXTRA_DEVICE)
+                            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+                                intent.getParcelableExtra(
+                                    BluetoothDevice.EXTRA_DEVICE,
+                                    BluetoothDevice::class.java
+                                )
+                            } else {
+                                intent.getParcelableExtra<BluetoothDevice>(BluetoothDevice.EXTRA_DEVICE)
+                            }
                         // BroadcastReceiver receives bond state updates from all devices, need to filter by device
                         if (device.address == updatedDevice?.address) {
                             val bondState = intent.getIntExtra(BluetoothDevice.EXTRA_BOND_STATE, -1)
@@ -415,12 +491,21 @@ class Device(
             return
         }
         val bytes = stringToBytes(value)
-        characteristic.value = bytes
-        characteristic.writeType = writeType
-        val result = bluetoothGatt?.writeCharacteristic(characteristic)
-        if (result != true) {
-            reject(key, "Writing characteristic failed.")
-            return
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            val statusCode = bluetoothGatt?.writeCharacteristic(characteristic, bytes, writeType)
+            if (statusCode != BluetoothStatusCodes.SUCCESS) {
+                reject(key, "Writing characteristic failed with status code $statusCode.")
+                return
+            }
+        } else {
+            characteristic.value = bytes
+            characteristic.writeType = writeType
+            val result = bluetoothGatt?.writeCharacteristic(characteristic)
+            if (result != true) {
+                reject(key, "Writing characteristic failed.")
+                return
+            }
         }
         setTimeout(key, "Write timeout.", timeout)
     }
@@ -457,20 +542,32 @@ class Device(
             return
         }
 
-        if (enable) {
+        val value = if (enable) {
             if ((characteristic.properties and BluetoothGattCharacteristic.PROPERTY_NOTIFY) != 0) {
-                descriptor.value = BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE
+                BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE
             } else if ((characteristic.properties and BluetoothGattCharacteristic.PROPERTY_INDICATE) != 0) {
-                descriptor.value = BluetoothGattDescriptor.ENABLE_INDICATION_VALUE
+                BluetoothGattDescriptor.ENABLE_INDICATION_VALUE
+            } else {
+                BluetoothGattDescriptor.DISABLE_NOTIFICATION_VALUE
             }
         } else {
-            descriptor.value = BluetoothGattDescriptor.DISABLE_NOTIFICATION_VALUE
+            BluetoothGattDescriptor.DISABLE_NOTIFICATION_VALUE
         }
 
-        val resultDesc = bluetoothGatt?.writeDescriptor(descriptor)
-        if (resultDesc != true) {
-            reject(key, "Setting notification failed.")
-            return
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            val statusCode = bluetoothGatt?.writeDescriptor(descriptor, value)
+            if (statusCode != BluetoothStatusCodes.SUCCESS) {
+                reject(key, "Setting notification failed with status code $statusCode.")
+                return
+            }
+        } else {
+            descriptor.value = value
+            val resultDesc = bluetoothGatt?.writeDescriptor(descriptor)
+            if (resultDesc != true) {
+                reject(key, "Setting notification failed.")
+                return
+            }
+
         }
         // wait for onDescriptorWrite
     }
@@ -525,11 +622,20 @@ class Device(
             return
         }
         val bytes = stringToBytes(value)
-        descriptor.value = bytes
-        val result = bluetoothGatt?.writeDescriptor(descriptor)
-        if (result != true) {
-            reject(key, "Writing characteristic failed.")
-            return
+
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            val statusCode = bluetoothGatt?.writeDescriptor(descriptor, bytes)
+            if (statusCode != BluetoothStatusCodes.SUCCESS) {
+                reject(key, "Writing descriptor failed with status code $statusCode.")
+                return
+            }
+        } else {
+            descriptor.value = bytes
+            val result = bluetoothGatt?.writeDescriptor(descriptor)
+            if (result != true) {
+                reject(key, "Writing descriptor failed.")
+                return
+            }
         }
         setTimeout(key, "Write timeout.", timeout)
     }

package/android/src/main/java/com/capacitorjs/community/plugins/bluetoothle/DeviceScanner.kt

@@ -1,5 +1,6 @@
 package com.capacitorjs.community.plugins.bluetoothle
 
+import android.annotation.SuppressLint
 import android.app.AlertDialog
 import android.bluetooth.BluetoothAdapter
 import android.bluetooth.BluetoothDevice
@@ -27,6 +28,7 @@ class DisplayStrings(
     val noDeviceFound: String,
 )
 
+@SuppressLint("MissingPermission")
 class DeviceScanner(
     private val context: Context,
     bluetoothAdapter: BluetoothAdapter,

package/dist/docs.json

@@ -313,12 +313,17 @@
       },
       {
         "name": "createBond",
-        "signature": "(deviceId: string) => Promise<void>",
+        "signature": "(deviceId: string, options?: TimeoutOptions | undefined) => Promise<void>",
         "parameters": [
           {
             "name": "deviceId",
             "docs": "The ID of the device to use (obtained from [requestDevice](#requestDevice) or [requestLEScan](#requestLEScan))",
             "type": "string"
+          },
+          {
+            "name": "options",
+            "docs": "Options for plugin call",
+            "type": "TimeoutOptions | undefined"
           }
         ],
         "returns": "Promise<void>",
@@ -326,10 +331,16 @@
           {
             "name": "param",
             "text": "deviceId The ID of the device to use (obtained from [requestDevice](#requestDevice) or [requestLEScan](#requestLEScan))"
+          },
+          {
+            "name": "param",
+            "text": "options Options for plugin call"
           }
         ],
         "docs": "Create a bond with a peripheral BLE device.\nOnly available on **Android**. On iOS bonding is handled by the OS.",
-        "complexTypes": [],
+        "complexTypes": [
+          "TimeoutOptions"
+        ],
         "slug": "createbond"
       },
       {

package/dist/esm/bleClient.d.ts

@@ -109,8 +109,9 @@ export interface BleClientInterface {
      * Create a bond with a peripheral BLE device.
      * Only available on **Android**. On iOS bonding is handled by the OS.
      * @param deviceId  The ID of the device to use (obtained from [requestDevice](#requestDevice) or [requestLEScan](#requestLEScan))
+     * @param options Options for plugin call
      */
-    createBond(deviceId: string): Promise<void>;
+    createBond(deviceId: string, options?: TimeoutOptions): Promise<void>;
     /**
      * Report whether a peripheral BLE device is bonded.
      * Only available on **Android**. On iOS bonding is handled by the OS.
@@ -241,7 +242,7 @@ declare class BleClientClass implements BleClientInterface {
     getDevices(deviceIds: string[]): Promise<BleDevice[]>;
     getConnectedDevices(services: string[]): Promise<BleDevice[]>;
     connect(deviceId: string, onDisconnect?: (deviceId: string) => void, options?: TimeoutOptions): Promise<void>;
-    createBond(deviceId: string): Promise<void>;
+    createBond(deviceId: string, options?: TimeoutOptions): Promise<void>;
     isBonded(deviceId: string): Promise<boolean>;
     disconnect(deviceId: string): Promise<void>;
     getServices(deviceId: string): Promise<BleService[]>;

package/dist/esm/bleClient.js

@@ -148,9 +148,9 @@ class BleClientClass {
             await BluetoothLe.connect(Object.assign({ deviceId }, options));
         });
     }
-    async createBond(deviceId) {
+    async createBond(deviceId, options) {
         await this.queue(async () => {
-            await BluetoothLe.createBond({ deviceId });
+            await BluetoothLe.createBond(Object.assign({ deviceId }, options));
         });
     }
     async isBonded(deviceId) {