0.0.6 • Published 5 days ago

capacitor-bluetooth-le-tektician v0.0.6

Weekly downloads
-
License
MIT
Repository
github
Last release
5 days ago

Maintainers

MaintainerGitHub
Patrick Wespipwespi
Philip Peitschpeitschie

Versions

PluginCapacitorDocumentation
6.x6.xREADME
3.x5.xREADME
2.x4.xREADME
1.x3.xREADME
0.x2.xREADME

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:

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-bluetooth-le-tektician
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-bluetooth-le-tektician';
    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-bluetooth-le-tektician';

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.

Scanning API

Here is an example of using the scanning API.

import { BleClient, numberToUUID } from 'capacitor-bluetooth-le-tektician';

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

Platform Support

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

methodAndroidiOSweb
initialize()
isEnabled()--
<!--requestEnable()
enable()
disable()
startEnabledNotifications(...)--
stopEnabledNotifications()--
isLocationEnabled()
openLocationSettings()
openBluetoothSettings()
openAppSettings()
setDisplayStrings(...)--
requestDevice(...)-->
requestLEScan(...)🚩
stopLEScan()🚩
<!--getDevices(...)🚩
getConnectedDevices(...)🚩
connect(...)
createBond(...)
isBonded(...)
disconnect(...)
getServices(...)
discoverServices(...)
getMtu(...)
requestConnectionPriority(...)
readRssi(...)
read(...)
write(...)
readDescriptor(...)
writeDescriptor(...)
writeWithoutResponse(...)
startNotifications(...)
stopNotifications(...)-->

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(options?: InitializeOptions | undefined) => 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.

ParamType
optionsInitializeOptions

isEnabled()

isEnabled() => Promise<boolean>

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

Returns: Promise<boolean>


requestEnable()

requestEnable() => Promise<void>

Request enabling Bluetooth. Show a system activity that allows the user to turn on Bluetooth. See https://developer.android.com/reference/android/bluetooth/BluetoothAdapter#ACTION_REQUEST_ENABLE Only available on Android.


enable()

enable() => Promise<void>

Enable Bluetooth. Only available on Android. Deprecated Will fail on Android SDK >= 33. Use requestEnable instead. See https://developer.android.com/reference/android/bluetooth/BluetoothAdapter#enable()


disable()

disable() => Promise<void>

Disable Bluetooth. Only available on Android. Deprecated Will fail on Android SDK >= 33. See https://developer.android.com/reference/android/bluetooth/BluetoothAdapter#disable()


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

ParamTypeDescription
callback(value: boolean) => voidCallback function to use when the Bluetooth state changes.

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. Not available on web. 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 be able use it.


setDisplayStrings(...)

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

Set the strings that are displayed in the requestDevice dialog.

ParamType
displayStringsDisplayStrings

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.

ParamTypeDescription
optionsRequestBleDeviceOptionsDevice 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.

ParamType
optionsRequestBleDeviceOptions
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.

ParamTypeDescription
deviceIdsstring[]List of device IDs, e.g. saved from a previous app run.

Returns: Promise<BleDevice[]>


getBondedDevices()

getBondedDevices() => Promise<BleDevice[]>

Get a list of currently bonded devices. Only available on Android. Uses getBondedDevices on Android

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.

ParamTypeDescription
servicesstring[]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, options?: TimeoutOptions | undefined) => Promise<void>

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

ParamTypeDescription
deviceIdstringThe 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
optionsTimeoutOptionsOptions for plugin call

createBond(...)

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.

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)
optionsTimeoutOptionsOptions for plugin call

isBonded(...)

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

Report whether a peripheral BLE device is bonded. Only available on Android. On iOS bonding is handled by the OS.

ParamTypeDescription
deviceIdstringThe 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.

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)

getServices(...)

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

Get services, characteristics and descriptors of a device.

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)

Returns: Promise<BleService[]>


discoverServices(...)

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

Discover services, characteristics and descriptors of a device. You only need this method if your peripheral device changes its services and characteristics at runtime. If the discovery was successful, the remote services can be retrieved using the getServices function. Not available on web.

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)

getMtu(...)

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

Get the MTU of a connected device. Note that the maximum write value length is 3 bytes less than the MTU. Not available on web.

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)

Returns: Promise<number>


requestConnectionPriority(...)

requestConnectionPriority(deviceId: string, connectionPriority: ConnectionPriority) => Promise<void>

Request a connection parameter update. Only available on Android. https://developer.android.com/reference/android/bluetooth/BluetoothGatt#requestConnectionPriority(int)

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)
connectionPriorityConnectionPriorityRequest a specific connection priority. See ConnectionPriority

readRssi(...)

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

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

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)

Returns: Promise<number>


read(...)

read(deviceId: string, service: string, characteristic: string, options?: TimeoutOptions | undefined) => Promise<DataView>

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

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)
servicestringUUID of the service (see UUID format)
characteristicstringUUID of the characteristic (see UUID format)
optionsTimeoutOptionsOptions for plugin call

Returns: Promise<DataView>


write(...)

write(deviceId: string, service: string, characteristic: string, value: DataView, options?: TimeoutOptions | undefined) => Promise<void>

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

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)
servicestringUUID of the service (see UUID format)
characteristicstringUUID of the characteristic (see UUID format)
valueDataViewThe 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)
optionsTimeoutOptionsOptions for plugin call

writeWithoutResponse(...)

writeWithoutResponse(deviceId: string, service: string, characteristic: string, value: DataView, options?: TimeoutOptions | undefined) => Promise<void>

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

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)
servicestringUUID of the service (see UUID format)
characteristicstringUUID of the characteristic (see UUID format)
valueDataViewThe 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)
optionsTimeoutOptionsOptions for plugin call

readDescriptor(...)

readDescriptor(deviceId: string, service: string, characteristic: string, descriptor: string, options?: TimeoutOptions | undefined) => Promise<DataView>

Read the value of a descriptor.

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)
servicestringUUID of the service (see UUID format)
characteristicstringUUID of the characteristic (see UUID format)
descriptorstringUUID of the descriptor (see UUID format)
optionsTimeoutOptionsOptions for plugin call

Returns: Promise<DataView>


writeDescriptor(...)

writeDescriptor(deviceId: string, service: string, characteristic: string, descriptor: string, value: DataView, options?: TimeoutOptions | undefined) => Promise<void>

Write a value to a descriptor.

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)
servicestringUUID of the service (see UUID format)
characteristicstringUUID of the characteristic (see UUID format)
descriptorstringUUID of the descriptor (see UUID format)
valueDataViewThe 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)
optionsTimeoutOptionsOptions for plugin call

startNotifications(...)

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

Start listening to changes of the value of a characteristic. Note that you should only start the notifications once per characteristic in your app and share the data and not call startNotifications in every component that needs the data. For an example, see usage.

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)
servicestringUUID of the service (see UUID format)
characteristicstringUUID of the characteristic (see UUID format)
callback(value: DataView) => voidCallback 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.

ParamTypeDescription
deviceIdstringThe ID of the device to use (obtained from requestDevice or requestLEScan)
servicestringUUID of the service (see UUID format)
characteristicstringUUID of the characteristic (see UUID format)

Interfaces

InitializeOptions

PropTypeDescriptionDefault
androidNeverForLocationbooleanIf 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. (Android only) Requires adding 'neverForLocation' to AndroidManifest.xml https://developer.android.com/guide/topics/connectivity/bluetooth/permissions#assert-never-for-locationfalse

DisplayStrings

PropTypeDefaultSince
scanningstring"Scanning..."0.0.1
cancelstring"Cancel"0.0.1
availableDevicesstring"Available devices"0.0.1
noDeviceFoundstring"No device found"0.0.1

BleDevice

PropTypeDescription
deviceIdstringID 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.
namestringName of the peripheral device.
uuidsstring[]

RequestBleDeviceOptions

PropTypeDescription
servicesstring[]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)
namestringFilter devices by name
namePrefixstringFilter devices by name prefix
optionalServicesstring[]For web, all services that will be used have to be listed under services or optionalServices, e.g. numberToUUID(0x180f) (see UUID format)
allowDuplicatesbooleanNormally 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)
scanModeScanModeAndroid scan mode (default: ScanMode.SCAN_MODE_BALANCED)

ScanResult

PropTypeDescription
deviceBleDeviceThe 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.
localNamestringThe name of the peripheral device from the advertisement data.
rssinumberReceived Signal Strength Indication.
txPowernumberTransmit 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.
uuidsstring[]Advertised services.
rawAdvertisementDataViewRaw advertisement data (Android only).

DataView

PropType
bufferArrayBuffer
byteLengthnumber
byteOffsetnumber
MethodSignatureDescription
getFloat32(byteOffset: number, littleEndian?: boolean | undefined) => numberGets 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) => numberGets 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) => numberGets 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) => numberGets 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) => numberGets 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) => numberGets 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) => numberGets 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) => numberGets 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) => voidStores an Float32 value at the specified byte offset from the start of the view.
setFloat64(byteOffset: number, value: number, littleEndian?: boolean | undefined) => voidStores an Float64 value at the specified byte offset from the start of the view.
setInt8(byteOffset: number, value: number) => voidStores an Int8 value at the specified byte offset from the start of the view.
setInt16(byteOffset: number, value: number, littleEndian?: boolean | undefined) => voidStores an Int16 value at the specified byte offset from the start of the view.
setInt32(byteOffset: number, value: number, littleEndian?: boolean | undefined) => voidStores an Int32 value at the specified byte offset from the start of the view.
setUint8(byteOffset: number, value: number) => voidStores an Uint8 value at the specified byte offset from the start of the view.
setUint16(byteOffset: number, value: number, littleEndian?: boolean | undefined) => voidStores an Uint16 value at the specified byte offset from the start of the view.
setUint32(byteOffset: number, value: number, littleEndian?: boolean | undefined) => voidStores 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.

PropTypeDescription
byteLengthnumberRead-only. The length of the ArrayBuffer (in bytes).
MethodSignatureDescription
slice(begin: number, end?: number | undefined) => ArrayBufferReturns a section of an ArrayBuffer.

TimeoutOptions

PropTypeDescription
timeoutnumberTimeout in milliseconds for plugin call. Default is 10000 for connect and 5000 for other plugin methods.

BleService

PropType
uuidstring
characteristicsBleCharacteristic[]

BleCharacteristic

PropType
uuidstring
propertiesBleCharacteristicProperties
descriptorsBleDescriptor[]

BleCharacteristicProperties

PropType
broadcastboolean
readboolean
writeWithoutResponseboolean
writeboolean
notifyboolean
indicateboolean
authenticatedSignedWritesboolean
reliableWriteboolean
writableAuxiliariesboolean
extendedPropertiesboolean
notifyEncryptionRequiredboolean
indicateEncryptionRequiredboolean

BleDescriptor

PropType
uuidstring

Enums

ScanMode

MembersValueDescription
SCAN_MODE_LOW_POWER0Perform 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_BALANCED1Perform 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
0.0.6

5 days ago

0.0.5

5 days ago

0.0.4

5 days ago

0.0.3

7 days ago

0.0.2

7 days ago

0.0.1

7 days ago