Bluetooth Low Energy (BLE) Central Plugin for Apache Cordova

This plugin enables communication between a phone and Bluetooth Low Energy (BLE) peripherals.

The plugin provides a simple JavaScript API for iOS and Android.

• Scan for peripherals
• Connect to a peripheral
• Read the value of a characteristic
• Write new value to a characteristic
• Get notified when characteristic's value changes
• Transfer data via L2CAP channels

Advertising information is returned when scanning for peripherals. Service, characteristic, and property info is returned when connecting to a peripheral. All access is via service and characteristic UUIDs. The plugin manages handles internally.

Simultaneous connections to multiple peripherals are supported.

This plugin isn't intended for scanning beacons. Try cordova-plugin-ibeacon for iBeacons.

If you want to create Bluetooth devices, try cordova-plugin-ble-peripheral.

See the examples for ideas on how this plugin can be used.

Supported Platforms

• iOS
• Android 6+ (8.1 or greater recommended)
• Browser (where navigator.bluetooth is supported)

Installing

Capacitor

$ npm install cordova-plugin-ble-central
$ npx cap sync

The plugin can be further configured via the cordova preferences section of the capacitor config file:

const config = {
  ...
  cordova: {
    preferences: {
      ...
      bluetooth_restore_state: "true",
      accessBackgroundLocation: "false",
    },
  }
}

• bluetooth_restore_state: [iOS] Enable Bluetooth state restoration, allowing an app to be woken up to receive scan results and peripheral notifications. This is needed for background scanning support. See iOS restore state. For more information about background operation with this plugin, see Background Scanning and Notifications on iOS.

• accessBackgroundLocation: [Android] Tells the plugin to request the ACCESS_BACKGROUND_LOCATION permission on Android 10 & Android 11 in order for scanning to function when the app is not visible.

iOS

After installation, the following additions should be made to the app's Info.plist

• Set NSBluetoothAlwaysUsageDescription to a descriptive text, to be shown to the user on first access to the Bluetooth adapter. If this is not defined the app will crash.
• (Optional) Add bluetooth-central to UIBackgroundModes to enable background receipt of scan information and BLE notifications

Cordova

$ cordova plugin add cordova-plugin-ble-central --variable BLUETOOTH_USAGE_DESCRIPTION="Your description here" --variable IOS_INIT_ON_LOAD=true|false --variable BLUETOOTH_RESTORE_STATE=true|false --variable ACCESS_BACKGROUND_LOCATION=true|false

It's recommended to always use the latest cordova and cordova platform packages in order to ensure correct function. This plugin generally best supports the following platforms and version ranges:

cordova	cordova-ios	cordova-android	cordova-browser
10+	6.2.0+	12.0+	not tested

All variables can be modified after installation by updating the values in package.json.

• BLUETOOTH_USAGE_DESCRIPTION: [iOS] defines the values for NSBluetoothAlwaysUsageDescription.

• IOS_INIT_ON_LOAD: [iOS] Prevents the Bluetooth plugin from being initialised until first access to the ble window object. This allows an application to warn the user before the Bluetooth access permission is requested.

• BLUETOOTH_RESTORE_STATE: [iOS] Enable Bluetooth state restoration, allowing an app to be woken up to receive scan results and peripheral notifications. This is needed for background scanning support. See iOS restore state. For more information about background operation with this plugin, see Background Scanning and Notifications on iOS.

• ACCESS_BACKGROUND_LOCATION: [Android] Tells the plugin to request the ACCESS_BACKGROUND_LOCATION permission on Android 10 & Android 11 in order for scanning to function when the app is not visible.

TypeScript

TypeScript definitions are provided by this plugin. These can be added to a file by adding a triple-slash reference at the top of any file using this plugin:

/// <reference types="cordova-plugin-ble-central" />

Android permission conflicts

If you are having Android permissions conflicts with other plugins, try using the slim variant of the plugin instead with cordova plugin add cordova-plugin-ble-central@slim. This variant excludes all Android permissions, leaving it to the developer to ensure the right entries are added manually to the AndroidManifest.xml (see below for an example).

To include the default set of permissions the plugin installs on Android SDK v31+, add the following snippet in your config.xml file, in the <platform name="android"> section:

    <config-file target="AndroidManifest.xml" parent="/manifest">
        <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="28" />
        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
        <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
        <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
        <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
        <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    </config-file>

For the best understanding about which permissions are needed for which combinations of target SDK version & OS version, see Android Bluetooth permissions

API

• ble.scan
• ble.startScan
• ble.startScanWithOptions
• ble.stopScan
• ble.setPin
• ble.bond
• ble.unbond
• ble.readBondState
• ble.connect
• ble.autoConnect
• ble.disconnect
• ble.requestMtu
• ble.requestConnectionPriority
• ble.refreshDeviceCache
• ble.read
• ble.write
• ble.writeWithoutResponse
• ble.startNotification
• ble.stopNotification
• ble.isConnected
• ble.isEnabled
• ble.isLocationEnabled
• ble.startLocationStateNotifications
• ble.stopLocationStateNotifications
• ble.startStateNotifications
• ble.stopStateNotifications
• ble.showBluetoothSettings
• ble.enable
• ble.readRSSI
• ble.connectedPeripheralsWithServices
• ble.peripheralsWithIdentifiers
• ble.restoredBluetoothState
• ble.list
• ble.bondedDevices
• ble.l2cap.open
• ble.l2cap.close
• ble.l2cap.receiveData
• ble.l2cap.write

scan

Scan and discover BLE peripherals.

ble.scan(services, seconds, success, failure);

Description

Function scan scans for BLE devices. The success callback is called each time a peripheral is discovered. Scanning automatically stops after the specified number of seconds.

{
    "name": "TI SensorTag",
    "id": "BD922605-1B07-4D55-8D09-B66653E51BBA",
    "rssi": -79,
    "advertising": /* ArrayBuffer or map */
}

Advertising information format varies depending on your platform. See Advertising Data for more information.

Location Permission Notes

With Android SDK >= 23 (6.0), additional permissions are required for Bluetooth low energy scanning. The location permission ACCESS_COARSE_LOCATION is required because Bluetooth beacons can be used to determine a user's location. If necessary, the plugin will prompt the user to allow the app to access to device's location. If the user denies permission, the scan failure callback will receive the error "Location permission not granted".

Location Services must be enabled for Bluetooth scanning. If location services are disabled, the failure callback will receive the error "Location services are disabled". If you want to manage location permission and screens, try the cordova-diagonostic-plugin or the Ionic Native Diagnostic plugin.

Parameters

• services: List of services to discover, or [] to find all devices
• seconds: Number of seconds to run discovery
• success: Success callback function that is invoked which each discovered device.
• failure: Error callback function, invoked when error occurs. [optional]

Quick Example

ble.scan(
    [],
    5,
    function (device) {
        console.log(JSON.stringify(device));
    },
    failure
);

startScan

Scan and discover BLE peripherals.

ble.startScan(services, success, failure);

Description

Function startScan scans for BLE devices. The success callback is called each time a peripheral is discovered. Scanning will continue until stopScan is called.

{
    "name": "TI SensorTag",
    "id": "BD922605-1B07-4D55-8D09-B66653E51BBA",
    "rssi": -79,
    "advertising": /* ArrayBuffer or map */
}

Advertising information format varies depending on your platform. See Advertising Data for more information.

See the location permission notes above for information about Location Services in Android SDK >= 23.

Parameters

• services: List of services to discover, or [] to find all devices
• success: Success callback function that is invoked which each discovered device.
• failure: Error callback function, invoked when error occurs. [optional]

Quick Example

ble.startScan(
    [],
    function (device) {
        console.log(JSON.stringify(device));
    },
    failure
);

setTimeout(
    ble.stopScan,
    5000,
    function () {
        console.log('Scan complete');
    },
    function () {
        console.log('stopScan failed');
    }
);

startScanWithOptions

Scan and discover BLE peripherals, specifying scan options.

ble.startScanWithOptions(services, options, success, failure);

Description

Function startScanWithOptions scans for BLE devices. It operates similarly to the startScan function, but allows you to specify extra options (like allowing duplicate device reports). The success callback is called each time a peripheral is discovered. Scanning will continue until stopScan is called.

{
    "name": "TI SensorTag",
    "id": "BD922605-1B07-4D55-8D09-B66653E51BBA",
    "rssi": -79,
    "advertising": /* ArrayBuffer or map */
}

Advertising information format varies depending on your platform. See Advertising Data for more information.

See the [location permission notes](#location-p