Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →

@capacitor-community/bluetooth-le

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@capacitor-community/bluetooth-le

Capacitor plugin for Bluetooth Low Energy

1.4.0
Source
npm

Version published: 3 years ago

Weekly downloads: 4.9K; increased by17.4%

Maintainers: 34

Weekly downloads

Created: 4 years ago

Source

Bluetooth Low Energy

@capacitor-community/bluetooth-le

Capacitor plugin for Bluetooth Low Energy

Maintainers

Maintainer	GitHub	Social
Patrick Wespi	pwespi

Versions

Plugin	Capacitor	Documentation
1.x	3.x	README
0.x	2.x	README

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.

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

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 BLE is enabled on this device. Always returns true on web.

Returns: Promise<boolean>

startEnabledNotifications(...)

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

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

Param	Type	Description
`callback`	`(value: boolean) => void`	Callback function to use when the BLE state changes.

stopEnabledNotifications()

stopEnabledNotifications() => Promise<void>

Stop the enabled notifications registered with startEnabledNotifications.

setDisplayStrings(...)

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

Set the strings that are displayed in the requestDevice dialog.

Param	Type
`displayStrings`	`DisplayStrings`

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.

Param	Type	Description
`options`	`RequestBleDeviceOptions`	Device filters, see RequestBleDeviceOptions

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.

Param	Type
`options`	`RequestBleDeviceOptions`
`callback`	`(result: ScanResult) => void`

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.

Param	Type	Description
`deviceIds`	`string[]`	List of device IDs, e.g. saved from a previous app run. No used on web.

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.

Param	Type	Description
`services`	`string[]`	List of services to filter the devices by. If no service is specified, no devices will be returned. Only applies to iOS.

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.

Param	Type	Description
`deviceId`	`string`	The ID of the device to use (obtained from requestDevice or requestLEScan)
`onDisconnect`	`((deviceId: string) => void)`	Optional disconnect callback function that will be used when the device disconnects

createBond(...)

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

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

Param	Type	Description
`deviceId`	`string`	The ID of the device to use (obtained from requestDevice or requestLEScan)

isBonded(...)

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

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

Param	Type	Description
`deviceId`	`string`	The ID of the device to use (obtained from requestDevice or requestLEScan)

Returns: Promise<boolean>

disconnect(...)

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

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

Param	Type	Description
`deviceId`	`string`	The ID of the device to use (obtained from requestDevice or requestLEScan)

getServices(...)

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

Get services and characteristics of device.

Param	Type	Description
`deviceId`	`string`	The ID of the device to use (obtained from requestDevice or requestLEScan)

Returns: Promise<BleService[]>

readRssi(...)

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

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

Param	Type	Description
`deviceId`	`string`	The ID of the device to use (obtained from requestDevice or requestLEScan)

Returns: Promise<number>

read(...)

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

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

Param	Type	Description
`deviceId`	`string`	The ID of the device to use (obtained from requestDevice or requestLEScan)
`service`	`string`	UUID of the service (see UUID format)
`characteristic`	`string`	UUID of the characteristic (see UUID format)

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.

Param	Type	Description
`deviceId`	`string`	The ID of the device to use (obtained from requestDevice or requestLEScan)
`service`	`string`	UUID of the service (see UUID format)
`characteristic`	`string`	UUID of the characteristic (see UUID format)
`value`	`DataView`	The value to write as a DataView. To create a DataView from an array of numbers, there is a helper function, e.g. numbersToDataView([1, 0])

writeWithoutResponse(...)

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

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

Param	Type	Description
`deviceId`	`string`	The ID of the device to use (obtained from requestDevice or requestLEScan)
`service`	`string`	UUID of the service (see UUID format)
`characteristic`	`string`	UUID of the characteristic (see UUID format)
`value`	`DataView`	The value to write as a DataView. To create a DataView from an array of numbers, there is a helper function, e.g. numbersToDataView([1, 0])

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.

Param	Type	Description
`deviceId`	`string`	The ID of the device to use (obtained from requestDevice or requestLEScan)
`service`	`string`	UUID of the service (see UUID format)
`characteristic`	`string`	UUID of the characteristic (see UUID format)
`callback`	`(value: DataView) => void`	Callback function to use when the value of the characteristic changes

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.

Param	Type	Description
`deviceId`	`string`	The ID of the device to use (obtained from requestDevice or requestLEScan)
`service`	`string`	UUID of the service (see UUID format)
`characteristic`	`string`	UUID of the characteristic (see UUID format)

Interfaces

DisplayStrings

Prop	Type	Default	Since
`scanning`	`string`	`"Scanning..."`	0.0.1
`cancel`	`string`	`"Cancel"`	0.0.1
`availableDevices`	`string`	`"Available devices"`	0.0.1
`noDeviceFound`	`string`	`"No device found"`	0.0.1

BleDevice

Prop	Type	Description
`deviceId`	`string`	ID of the device, which will be needed for further calls. On Android this is the BLE MAC address. On iOS and web it is an identifier.
`name`	`string`	Name of the peripheral device.
`uuids`	`string[]`

RequestBleDeviceOptions

Prop	Type	Description
`services`	`string[]`	Filter devices by service UUIDs. UUIDs have to be specified as 128 bit UUID strings, e.g. ['0000180d-0000-1000-8000-00805f9b34fb'] There is a helper function to convert numbers to UUIDs. e.g. [numberToUUID(0x180f)]. (see UUID format)
`name`	`string`	Filter devices by name
`namePrefix`	`string`	Filter devices by name prefix
`optionalServices`	`string[]`	For web, all services that will be used have to be listed under services or optionalServices, e.g. [numberToUUID(0x180f)] (see UUID format)
`allowDuplicates`	`boolean`	Normally scans will discard the second and subsequent advertisements from a single device. If you need to receive them, set allowDuplicates to true (only applicable in `requestLEScan`). (default: false)
`scanMode`	`ScanMode`	Android scan mode (default: ScanMode.SCAN_MODE_BALANCED)

ScanResult

Prop	Type	Description
`device`	`BleDevice`	The peripheral device that was found in the scan. Android and web: `device.name` is always identical to `localName`. iOS: `device.name` is identical to `localName` the first time a device is discovered, but after connecting `device.name` is the cached GAP name in subsequent scans.
`localName`	`string`	The name of the peripheral device from the advertisement data.
`rssi`	`number`	Received Signal Strength Indication.
`txPower`	`number`	Transmit power in dBm. A value of 127 indicates that it is not available.
`manufacturerData`	`{ [key: string]: DataView; }`	Manufacturer data, key is a company identifier and value is the data.
`serviceData`	`{ [key: string]: DataView; }`	Service data, key is a service UUID and value is the data.
`uuids`	`string[]`	Advertised services.
`rawAdvertisement`	`DataView`	Raw advertisement data (Android only).

DataView

Prop	Type
`buffer`	`ArrayBuffer`
`byteLength`	`number`
`byteOffset`	`number`

Method	Signature	Description
getFloat32	(byteOffset: number, littleEndian?: boolean \| undefined) => number	Gets the Float32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getFloat64	(byteOffset: number, littleEndian?: boolean \| undefined) => number	Gets the Float64 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getInt8	(byteOffset: number) => number	Gets the Int8 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getInt16	(byteOffset: number, littleEndian?: boolean \| undefined) => number	Gets the Int16 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getInt32	(byteOffset: number, littleEndian?: boolean \| undefined) => number	Gets the Int32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getUint8	(byteOffset: number) => number	Gets the Uint8 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getUint16	(byteOffset: number, littleEndian?: boolean \| undefined) => number	Gets the Uint16 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
getUint32	(byteOffset: number, littleEndian?: boolean \| undefined) => number	Gets the Uint32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset.
setFloat32	(byteOffset: number, value: number, littleEndian?: boolean \| undefined) => void	Stores an Float32 value at the specified byte offset from the start of the view.
setFloat64	(byteOffset: number, value: number, littleEndian?: boolean \| undefined) => void	Stores an Float64 value at the specified byte offset from the start of the view.
setInt8	(byteOffset: number, value: number) => void	Stores an Int8 value at the specified byte offset from the start of the view.
setInt16	(byteOffset: number, value: number, littleEndian?: boolean \| undefined) => void	Stores an Int16 value at the specified byte offset from the start of the view.
setInt32	(byteOffset: number, value: number, littleEndian?: boolean \| undefined) => void	Stores an Int32 value at the specified byte offset from the start of the view.
setUint8	(byteOffset: number, value: number) => void	Stores an Uint8 value at the specified byte offset from the start of the view.
setUint16	(byteOffset: number, value: number, littleEndian?: boolean \| undefined) => void	Stores an Uint16 value at the specified byte offset from the start of the view.
setUint32	(byteOffset: number, value: number, littleEndian?: boolean \| undefined) => void	Stores an Uint32 value at the specified byte offset from the start of the view.

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.

Prop	Type	Description
`byteLength`	`number`	Read-only. The length of the ArrayBuffer (in bytes).

Method	Signature	Description
slice	(begin: number, end?: number \| undefined) => ArrayBuffer	Returns a section of an ArrayBuffer.

BleService

Prop	Type
`uuid`	`string`
`characteristics`	`BleCharacteristic[]`

BleCharacteristic

Prop	Type
`uuid`	`string`
`properties`	`BleCharacteristicProperties`

BleCharacteristicProperties

Prop	Type
`broadcast`	`boolean`
`read`	`boolean`
`writeWithoutResponse`	`boolean`
`write`	`boolean`
`notify`	`boolean`
`indicate`	`boolean`
`authenticatedSignedWrites`	`boolean`
`reliableWrite`	`boolean`
`writableAuxiliaries`	`boolean`
`extendedProperties`	`boolean`
`notifyEncryptionRequired`	`boolean`
`indicateEncryptionRequired`	`boolean`

Enums

ScanMode

Members	Value	Description
`SCAN_MODE_LOW_POWER`	`0`	Perform Bluetooth LE scan in low power mode. This mode is enforced if the scanning application is not in foreground. https://developer.android.com/reference/android/bluetooth/le/ScanSettings#SCAN_MODE_LOW_POWER
`SCAN_MODE_BALANCED`	`1`	Perform Bluetooth LE scan in balanced power mode. (default) Scan results are returned at a rate that provides a good trade-off between scan frequency and power consumption. https://developer.android.com/reference/android/bluetooth/le/ScanSettings#SCAN_MODE_BALANCED
`SCAN_MODE_LOW_LATENCY`	`2`	Scan using highest duty cycle. It's recommended to only use this mode when the application is running in the foreground. https://developer.android.com/reference/android/bluetooth/le/ScanSettings#SCAN_MODE_LOW_LATENCY

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

_pwespi
💻

_{Dennis Ameling}
💻

_{Johannes la Poutre}
📖 💻

_{Kasymbekov Sultanmyrza}
💻

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

Keywords

FAQs

What is @capacitor-community/bluetooth-le?

Is @capacitor-community/bluetooth-le popular?

Is @capacitor-community/bluetooth-le well maintained?

Package last updated on 24 Sep 2021

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@capacitor-community/bluetooth-le

Bluetooth Low Energy

Maintainers

Versions

Introduction

Installation

iOS

Android

Configuration

Usage

API

initialize()

isEnabled()

startEnabledNotifications(...)

stopEnabledNotifications()

setDisplayStrings(...)

requestDevice(...)

requestLEScan(...)

stopLEScan()

getDevices(...)

getConnectedDevices(...)

connect(...)

createBond(...)

isBonded(...)

disconnect(...)

getServices(...)

readRssi(...)

read(...)

write(...)

writeWithoutResponse(...)

startNotifications(...)

stopNotifications(...)

Interfaces

DisplayStrings

BleDevice

RequestBleDeviceOptions

ScanResult

DataView

ArrayBuffer

BleService

BleCharacteristic

BleCharacteristicProperties

Enums

ScanMode

UUID format

Troubleshooting

Connection fails on Android

Contributors ✨

1.4.0 (2021-09-24)

Features

Bug Fixes

Keywords

Related posts

Weekly Downloads Now Available in npm Package Search Results

Tech's $90B Ghost Engineer Problem: Stanford Study Finds 9.5% of Engineers Do Almost Nothing