capacitor-bluetooth-le v1.5.0-alpha.10

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.

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

Below is an index of all the methods available.

• initialize()
• isEnabled()
• enable()
• disable()
• startEnabledNotifications(...)
• stopEnabledNotifications()
• isLocationEnabled()
• openLocationSettings()
• openBluetoothSettings()
• openAppSettings()
• setDisplayStrings(...)
• requestDevice(...)
• requestLEScan(...)
• stopLEScan()
• getDevices(...)
• getConnectedDevices(...)
• connect(...)
• createBond(...)
• isBonded(...)
• disconnect(...)
• getServices(...)
• readRssi(...)
• read(...)
• write(...)
• writeWithoutResponse(...)
• readDescriptor(...)
• writeDescriptor(...)
• startNotifications(...)
• stopNotifications(...)
• Interfaces
• Enums

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>

Android

On Android, no further steps are required to use the plugin (if you are using Capacitor 2, see here).

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

It is recommended to not use the plugin class directly. There is a wrapper class BleClient which makes events and method arguments easier to work with.

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

// DO NOT use this
import { BluetoothLe } from '@capacitor-community/bluetooth-le';

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],
    });

    await BleClient.connect(device.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));
      }
    );

    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 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;
}

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

initialize()

initialize() => Promise<void>

Initialize Bluetooth Low Energy (BLE). If it fails, BLE might be unavailable on this device. On Android it will ask for the location permission. On iOS it will ask for the Bluetooth permission. For an example, see usage.

isEnabled()

isEnabled() => Promise<boolean>

Reports whether Bluetooth is enabled on this device. Always returns true on web.

Returns: Promise<boolean>

enable()

enable() => Promise<void>

Enable Bluetooth. Only available on Android.

disable()

disable() => Promise<void>

Disable Bluetooth. Only available on Android.

startEnabledNotifications(...)

startEnabledNotifications(callback: (value: boolean) => void) => Promise<void>

Register a callback function that will be invoked when Bluetooth is enabled (true) or disabled (false) on this device. Not available on web (the callback will never be invoked).

stopEnabledNotifications()

stopEnabledNotifications() => Promise<void>

Stop the enabled notifications registered with startEnabledNotifications.

isLocationEnabled()

isLocationEnabled() => Promise<boolean>

Reports whether Location Services are enabled on this device. Only available on Android.

Returns: Promise<boolean>

openLocationSettings()

openLocationSettings() => Promise<void>

Open Location settings. Only available on Android.

openBluetoothSettings()

openBluetoothSettings() => Promise<void>

Open Bluetooth settings. Only available on Android.

openAppSettings()

openAppSettings() => Promise<void>

Open App settings. Only available on iOS. On iOS when a user declines the request to use Bluetooth on the first call of initialize, it is not possible to request for Bluetooth again from within the app. In this case Bluetooth has to be enabled in the app settings for the app to use it.

setDisplayStrings(...)

setDisplayStrings(displayStrings: DisplayStrings) => Promise<void>

Set the strings that are displayed in the requestDevice dialog.

requestDevice(...)

requestDevice(options?: RequestBleDeviceOptions | undefined) => Promise<BleDevice>

Request a peripheral BLE device to interact with. This will scan for available devices according to the filters in the options and show a dialog to pick a device. For an example, see usage.

Returns: Promise<BleDevice>

requestLEScan(...)

requestLEScan(options: RequestBleDeviceOptions, callback: (result: ScanResult) => void) => Promise<void>

Start scanning for BLE devices to interact with according to the filters in the options. The callback will be invoked on each device that is found. Scanning will continue until stopLEScan is called. For an example, see usage. NOTE: Use with care on web platform, the required API is still behind a flag in most browsers.

stopLEScan()

stopLEScan() => Promise<void>

Stop scanning for BLE devices. For an example, see usage.

getDevices(...)

getDevices(deviceIds: string[]) => Promise<BleDevice[]>

On iOS and web, if you want to connect to a previously connected device without scanning first, you can use getDevice. Uses retrievePeripherals on iOS and getDevices on web. On Android, you can directly connect to the device with the deviceId.

Returns: Promise<BleDevice[]>

getConnectedDevices(...)

getConnectedDevices(services: string[]) => Promise<BleDevice[]>

Get a list of currently connected devices. Uses retrieveConnectedPeripherals on iOS, getConnectedDevices on Android and getDevices on web.

Returns: Promise<BleDevice[]>

connect(...)

connect(deviceId: string, onDisconnect?: ((deviceId: string) => void) | undefined) => Promise<void>

Connect to a peripheral BLE device. For an example, see usage.

createBond(...)

createBond(deviceId: string) => Promise<void>

Create a bond with a peripheral BLE device. Only available on Android.

isBonded(...)

isBonded(deviceId: string) => Promise<boolean>

Report whether a peripheral BLE device is bonded. Only available on Android.

Returns: Promise<boolean>

disconnect(...)

disconnect(deviceId: string) => Promise<void>

Disconnect from a peripheral BLE device. For an example, see usage.

getServices(...)

getServices(deviceId: string) => Promise<BleService[]>

Get services and characteristics of device.

Returns: Promise<BleService[]>

readRssi(...)

readRssi(deviceId: string) => Promise<number>

Read the RSSI value of a connected device. Not available on web.

Returns: Promise<number>

read(...)

read(deviceId: string, service: string, characteristic: string) => Promise<DataView>

Read the value of a characteristic. For an example, see usage.

Returns: Promise<DataView>

write(...)

write(deviceId: string, service: string, characteristic: string, value: DataView) => Promise<void>

Write a value to a characteristic. For an example, see usage.

writeWithoutResponse(...)

writeWithoutResponse(deviceId: string, service: string, characteristic: string, value: DataView) => Promise<void>

Write a value to a characteristic without waiting for a response.

readDescriptor(...)

readDescriptor(deviceId: string, service: string, characteristic: string, descriptor: string) => Promise<DataView>

Read the value of a descriptor.

Returns: Promise<DataView>

writeDescriptor(...)

writeDescriptor(deviceId: string, service: string, characteristic: string, descriptor: string, value: DataView) => Promise<void>

Write a value to a descriptor.

startNotifications(...)

startNotifications(deviceId: string, service: string, characteristic: string, callback: (value: DataView) => void) => Promise<void>

Start listening to changes of the value of a characteristic. For an example, see usage.

stopNotifications(...)

stopNotifications(deviceId: string, service: string, characteristic: string) => Promise<void>

Stop listening to the changes of the value of a characteristic. For an example, see usage.

Interfaces

DisplayStrings

BleDevice

RequestBleDeviceOptions

ScanResult

DataView

ArrayBuffer

Represents a raw buffer of binary data, which is used to store data for the different typed arrays. ArrayBuffers cannot be read from or written to directly, but can be passed to a typed array or DataView Object to interpret the raw buffer as needed.

BleService

BleCharacteristic

BleCharacteristicProperties

BleDescriptor

Enums

ScanMode

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

Contributors ✨

Thanks goes to these wonderful people (emoji key):

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