Bluetooth Low Energy

@capacitor-community/bluetooth-le

Capacitor plugin for Bluetooth Low Energy

Maintainers

Versions

Introduction

This is a Capacitor plugin for Bluetooth Low Energy. It supports the web, Android and iOS.

The goal is to support the same features on all platforms. Therefore the Web Bluetooth API is taken as a guidline for what features to implement.

This plugin only supports Bluetooth Low Energy, not Bluetooth serial / classic.

Furthermore the plugin only supports the central role of the Bluetooth Low Energy protocol. If you need the peripheral role, take a look a these plugins:

• https://github.com/randdusing/cordova-plugin-bluetoothle
• https://github.com/don/cordova-plugin-ble-peripheral

For support of Web Bluetooth in various browsers, see implementation status.

Below is an index of all the methods available.

See Platform Support for an overview of supported methods on Android, iOS and web.

Installation

npm install @capacitor-community/bluetooth-le
npx cap sync

iOS

On iOS, add the NSBluetoothAlwaysUsageDescription to Info.plist, otherwise the app will crash when trying to use Bluetooth (see here).

If the app needs to use Bluetooth while it is in the background, you also have to add bluetooth-central to UIBackgroundModes (for details see here).

./ios/App/App/Info.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleDevelopmentRegion</key>
    <string>en</string>
  ...
+   <key>NSBluetoothAlwaysUsageDescription</key>
+   <string>Uses Bluetooth to connect and interact with peripheral BLE devices.</string>
+   <key>UIBackgroundModes</key>
+   <array>
+       <string>bluetooth-central</string>
+   </array>
</dict>
</plist>

Note: Bluetooth is not available in the iOS simulator. The initialize call will be rejected with an error "BLE unsupported". You have to test your app on a real device.

Android

On Android, no further steps are required to use the plugin.

(Optional) Android 12 Bluetooth permissions

If your app targets Android 12 (API level 31) or higher and 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. This allows the app to scan for Bluetooth devices without asking for location permissions. See the Android documentation.

The following steps are required to scan for Bluetooth devices without location permission on Android 12 devices:

• In android/variables.gradle, make sure compileSdkVersion and targetSdkVersion are at least 31 (changing those values can have other consequences on your app, so make sure you know what you're doing).
• In android/app/src/main/AndroidManifest.xml, update the permissions:

    <!-- Permissions -->
  +   <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="30" />
  +   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
  +   <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
  +     android:usesPermissionFlags="neverForLocation"
  +     tools:targetApi="s" />

• Set the androidNeverForLocation flag to true when initializing the BleClient.

  import { BleClient } from '@capacitor-community/bluetooth-le';
  await BleClient.initialize({ androidNeverForLocation: true });

Note: If you include neverForLocation in your android:usesPermissionFlags, some BLE beacons are filtered from the scan results.

Configuration

You can configure the strings that are displayed in the device selection dialog on iOS and Android when using requestDevice():

./capacitor.config.json:

{
  "...": "other configuration",
  "plugins": {
    "BluetoothLe": {
      "displayStrings": {
        "scanning": "Am Scannen...",
        "cancel": "Abbrechen",
        "availableDevices": "Verfügbare Geräte",
        "noDeviceFound": "Kein Gerät gefunden"
      }
    }
  }
}

The default values are:

{
  "plugins": {
    "BluetoothLe": {
      "displayStrings": {
        "scanning": "Scanning...",
        "cancel": "Cancel",
        "availableDevices": "Available devices",
        "noDeviceFound": "No device found"
      }
    }
  }
}

The display strings can also be set at run-time using setDisplayStrings(...).

Usage

There is a plugin wrapper class BleClient which makes events and method arguments easier to work with.

// Import the wrapper class
import { BleClient } from '@capacitor-community/bluetooth-le';

Note: It is not recommended to use the BluetoothLe plugin class directly.

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.

import { BleClient, numbersToDataView, numberToUUID } from '@capacitor-community/bluetooth-le';

const HEART_RATE_SERVICE = '0000180d-0000-1000-8000-00805f9b34fb';
const HEART_RATE_MEASUREMENT_CHARACTERISTIC = '00002a37-0000-1000-8000-00805f9b34fb';
const BODY_SENSOR_LOCATION_CHARACTERISTIC = '00002a38-0000-1000-8000-00805f9b34fb';
const BATTERY_SERVICE = numberToUUID(0x180f);
const BATTERY_CHARACTERISTIC = numberToUUID(0x2a19);
const POLAR_PMD_SERVICE = 'fb005c80-02e7-f387-1cad-8acd2d8df0c8';
const POLAR_PMD_CONTROL_POINT = 'fb005c81-02e7-f387-1cad-8acd2d8df0c8';

export async function main(): Promise<void> {
  try {
    await BleClient.initialize();

    const device = await BleClient.requestDevice({
      services: [HEART_RATE_SERVICE],
      optionalServices: [BATTERY_SERVICE, POLAR_PMD_SERVICE],
    });

    // connect to device, the onDisconnect callback is optional
    await BleClient.connect(device.deviceId, (deviceId) => onDisconnect(deviceId));
    console.log('connected to device', device);

    const result = await BleClient.read(device.deviceId, HEART_RATE_SERVICE, BODY_SENSOR_LOCATION_CHARACTERISTIC);
    console.log('body sensor location', result.getUint8(0));

    const battery = await BleClient.read(device.deviceId, BATTERY_SERVICE, BATTERY_CHARACTERISTIC);
    console.log('battery level', battery.getUint8(0));

    await BleClient.write(device.deviceId, POLAR_PMD_SERVICE, POLAR_PMD_CONTROL_POINT, numbersToDataView([1, 0]));
    console.log('written [1, 0] to control point');

    await BleClient.startNotifications(
      device.deviceId,
      HEART_RATE_SERVICE,
      HEART_RATE_MEASUREMENT_CHARACTERISTIC,
      (value) => {
        console.log('current heart rate', parseHeartRate(value));
      }
    );

    // disconnect after 10 sec
    setTimeout(async () => {
      await BleClient.stopNotifications(device.deviceId, HEART_RATE_SERVICE, HEART_RATE_MEASUREMENT_CHARACTERISTIC);
      await BleClient.disconnect(device.deviceId);
      console.log('disconnected from device', device);
    }, 10000);
  } catch (error) {
    console.error(error);
  }
}

function onDisconnect(deviceId: string): void {
  console.log(`device ${deviceId} disconnected`);
}

function parseHeartRate(value: DataView): number {
  const flags = value.getUint8(0);
  const rate16Bits = flags & 0x1;
  let heartRate: number;
  if (rate16Bits > 0) {
    heartRate = value.getUint16(1, true);
  } else {
    heartRate = value.getUint8(1);
  }
  return heartRate;
}

Scanning API

Here is an example of using the scanning API.

import { BleClient, numberToUUID } from '@capacitor-community/bluetooth-le';

const HEART_RATE_SERVICE = numberToUUID(0x180d);

export async function scan(): Promise<void> {
  try {
    await BleClient.initialize();

    await BleClient.requestLEScan(
      {
        services: [HEART_RATE_SERVICE],
      },
      (result) => {
        console.log('received new scan result', result);
      }
    );

    setTimeout(async () => {
      await BleClient.stopLEScan();
      console.log('stopped scanning');
    }, 5000);
  } catch (error) {
    console.error(error);
  }
}

Example Applications

• BLE Tester (Ionic/React)
• OpenGoPro (Ionic/Angular)
• Quasar BLE (Quasar/Vue)

Platform Support

Note: web support depends on the browser, see implementation status.

Legend

• ✅ supported
• ❌ not supported (throws an unavailable error)
• 🚩 behind a flag in Chrome (see implementation status)
• -- not supported, but does not throw an error

API

UUID format

All UUIDs have to be provided in 128 bit format as string, e.g. '0000180d-0000-1000-8000-00805f9b34fb'. There is a helper function to convert 16 bit UUID numbers to string:

import { numberToUUID } from '@capacitor-community/bluetooth-le';

const HEART_RATE_SERVICE = numberToUUID(0x180d);
// '0000180d-0000-1000-8000-00805f9b34fb'

Troubleshooting

Connection fails on Android

On some Android devices connect() may fail when the device was connected before, even if the device is not actually connected. In that case you should first call disconnect(), e.g.:

const device = await BleClient.requestDevice({
   // ...
});
// ...
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.

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):

pwespi 💻 📖	Dennis Ameling 💻	Johannes la Poutre 📖 💻	Kasymbekov Sultanmyrza 💻	Mutasim Issa 📖	Marco Marche 💻	Johannes Koch 💻
Johnny Robeson 💻	Aadit Olkar 💻	Yoann N. 💻	Andy3189 💻	Sammy 📖	td-tomasz-joniec 💻	Michele Ferrari 💻
mchl18 📖	Daniel Stefani 💻	Laurent 💻	Philip Peitsch 💻 💬

This project follows the all-contributors specification. Contributions of any kind welcome!