Name	Name	Last commit message	Last commit date
parent directory ..
docs/utils	docs/utils
BREAKING.md	BREAKING.md
CHANGELOG.md	CHANGELOG.md
LICENSE	LICENSE
README.md	README.md

Capacitor Bluetooth Low Energy Plugin

Capacitor plugin for Bluetooth Low Energy (BLE) communication in the central and peripheral role with advanced features like headless tasks, foreground services, and more.¹²

Deliver Live Updates to your Capacitor app with Capawesome Cloud

Features

The Capacitor Bluetooth Low Energy plugin is one of the most complete BLE communication solutions for Capacitor apps. Here are some of the key features:

🖥️ Cross-platform: Supports Android and iOS.
🔄 Central Role: Communicate with BLE peripherals as a central device.
📳 Peripheral Role: Act as a BLE peripheral to communicate with other central devices.
📡 Extended Advertising: Advertise larger payloads with BLE 5.0+ extended advertising.
🦾 Headless Task: Add custom native code for specific events.
🌙 Foreground Service: Keep the connection alive even when the app is in the background.
🔌 Auto Reconnection: Automatically reconnect to peripherals when the connection is lost.
⏳ Command Queue: Queue up incoming commands to prevent operation failures.
📱 Multiple Devices: Connect to multiple devices at the same time.
🛠️ Utils: Utility functions to make your life easier.
⚔️ Battle-Tested: Used in more than 300 projects.
🤝 Compatibility: Works alongside the Android Battery Optimization, Android Foreground Service and NFC plugins.
📦 CocoaPods & SPM: Supports CocoaPods and Swift Package Manager for iOS.
🔁 Up-to-date: Always supports the latest Capacitor version.
⭐️ Support: Priority support from the Capawesome Team.
✨ Handcrafted: Built from the ground up with care and expertise, not forked or AI-generated.

Missing a feature? Just open an issue and we'll take a look!

Use Cases

The Bluetooth Low Energy plugin is typically used to communicate with nearby BLE hardware, for example:

Connected hardware and IoT devices: Connect to BLE peripherals such as sensors or wearables and exchange data by reading and writing characteristics.
Health and fitness apps: Receive live measurements from devices like heart rate monitors via characteristic notifications.
Background data collection: Keep the connection alive while the app is in the background using a foreground service on Android.
Device-to-device communication: Act as a BLE peripheral and advertise your own services to other central devices.
Multi-device setups: Connect to and communicate with multiple BLE devices at the same time.
Tap-to-pair onboarding: Read a device's identifier from an NFC tag, then connect to it over BLE — no manual scanning or pairing UI needed.

Testimonials

We migrated PadelBand, a sports tech app, from the Capacitor Community BLE plugin to this one and the difference is remarkable. The reliable background support and the ability to run custom native code with headless tasks made all the difference for our use case. Highly recommended!

-- PadelBand Development Team

Compatibility

Plugin Version	Capacitor Version	Status
8.x.x	>=8.x.x	Active support
7.x.x	7.x.x	Deprecated
6.x.x	6.x.x	Deprecated

Demo

A working example can be found here.

Android	iOS

Guides

Installation

This plugin is only available to Capawesome Insiders. First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

Attention: Replace <YOUR_LICENSE_KEY> with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a Capawesome Insider.

Next, you can use our AI-Assisted Setup to install the plugin. Add the Capawesome Skills to your AI tool using the following command:

npx skills add capawesome-team/skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-bluetooth-low-energy` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capawesome-team/capacitor-bluetooth-low-energy
npx cap sync

Android

Features

Add the following element to your AndroidManifest.xml before or after the application tag:

<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />

Set the android:required attribute to true if your app can't function, or isn't designed to function, when Bluetooth Low Energy is not available on the device. If your app can function without Bluetooth Low Energy, set the android:required attribute to false. This will allow your app to be installed on devices that do not support Bluetooth Low Energy.

Permissions

This API requires the following elements be added to your AndroidManifest.xml before or after the application tag:

<!-- Required if you want to support Android 11 and below. -->
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<!-- Required if you want to advertise as a BLE device. -->
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<!-- Required if you want to scan for BLE devices. -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- Required if you want to be able to connect to paired Bluetooth devices. -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<!--Required if you want to start a foreground service.-->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

You can read more about Bluetooth permissions in the Android documentation.

Services

You also need to add the following service inside the application tag in your AndroidManifest.xml (usually android/app/src/main/AndroidManifest.xml):

<service android:name="io.capawesome.capacitorjs.plugins.bluetoothle.BluetoothLowEnergyService" android:foregroundServiceType="connectedDevice" />

Headless Task

If you want to run your own native code when a specific event occurs, you can create a headless task. For this, you need to create a Java class with the name BluetoothLowEnergyHeadlessTask in the same package as your MainActivity. Then implement the following methods:

import android.bluetooth.BluetoothGatt;
import android.bluetooth.BluetoothGattCharacteristic;
import android.bluetooth.BluetoothGattDescriptor;
import androidx.annotation.NonNull;

public class BluetoothLowEnergyHeadlessTask {
  public void onCharacteristicChanged(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic) {
    // Your code here
  }

  public void onCharacteristicChanged(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic, @NonNull byte[] value) {
    // Your code here
  }

  public void onCharacteristicRead(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic, int status) {
    // Your code here
  }

  public void onCharacteristicWrite(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic, int status) {
    // Your code here
  }

  public void onConnectionStateChange(@NonNull BluetoothGatt gatt, int status, int newState) {
    // Your code here
  }

  public void onDescriptorRead(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattDescriptor descriptor, int status, @NonNull byte[] value) {
    // Your code here
  }

  public void onDescriptorWrite(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattDescriptor descriptor, int status) {
    // Your code here
  }

  public void onMtuChanged(@NonNull BluetoothGatt gatt, int mtu, int status) {
    // Your code here
  }

  public void onReadRemoteRssi(@NonNull BluetoothGatt gatt, int rssi, int status) {
    // Your code here
  }

  public void onServiceChanged(@NonNull BluetoothGatt gatt) {
    // Your code here
  }

  public void onServicesDiscovered(@NonNull BluetoothGatt gatt, int status) {
    // Your code here
  }
}

Proguard

If you are using Proguard, you need to add the following rules to your proguard-rules.pro file:

-keep class io.capawesome.capacitorjs.plugins.** { *; }

iOS

Privacy Descriptions

Add the NSBluetoothAlwaysUsageDescription key to the Info.plist file (usually ios/App/App/Info.plist), which tells the user why the app needs access to Bluetooth peripherals:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>The app needs access to Bluetooth peripherals to communicate with Bluetooth devices.</string>

Capabilities

If you want your app to maintain Bluetooth Low Energy connections in the background, ensure the Background Modes capability is enabled with bluetooth-central in your Xcode project. See Add a capability to a target for more information.

Configuration

No configuration required for this plugin.

Usage

The following examples show how to initialize the plugin, manage permissions, scan for and connect to devices, discover services, read and write characteristics and descriptors, act as a peripheral, and listen for Bluetooth Low Energy events.

Initialize the plugin

Initialize the plugin in the central or peripheral role and check whether Bluetooth Low Energy is available and enabled on the device:

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const initialize = async () => {
  await BluetoothLowEnergy.initialize({ mode: 'central' });
};

const isAvailable = async () => {
  const result = await BluetoothLowEnergy.isAvailable();
  return result.isAvailable;
};

const isEnabled = async () => {
  const result = await BluetoothLowEnergy.isEnabled();
  return result.enabled;
};

Check and request permissions

Check and request the required Bluetooth permissions. Only available on Android:

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const checkPermissions = async () => {
  const result = await BluetoothLowEnergy.checkPermissions();
  return result;
};

const requestPermissions = async () => {
  const result = await BluetoothLowEnergy.requestPermissions();
  return result;
};

Scan for devices

Start and stop scanning for nearby BLE devices. Scanned devices are delivered via the deviceScanned event (see Listen for events):

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const startScan = async () => {
  await BluetoothLowEnergy.startScan();
};

const stopScan = async () => {
  await BluetoothLowEnergy.stopScan();
};

Connect to a device

Connect to a BLE device by its ID, disconnect from it, and retrieve the currently connected devices:

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const connect = async () => {
  await BluetoothLowEnergy.connect({ deviceId: '00:00:00:00:00:00' });
};

const disconnect = async () => {
  await BluetoothLowEnergy.disconnect({ deviceId: '00:00:00:00:00:00' });
};

const getConnectedDevices = async () => {
  const result = await BluetoothLowEnergy.getConnectedDevices();
  return result.devices;
};

Bond with a device

Create a bond with a BLE device and check whether a device is already bonded. Only available on Android:

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const createBond = async () => {
  await BluetoothLowEnergy.createBond({ deviceId: '00:00:00:00:00:00' });
};

const isBonded = async () => {
  const result = await BluetoothLowEnergy.isBonded({ deviceId: '00:00:00:00:00:00' });
  return result.bonded;
};

Discover services

Discover the services of a connected device and retrieve them along with their characteristics and descriptors:

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const discoverServices = async () => {
  await BluetoothLowEnergy.discoverServices({ deviceId: '00:00:00:00:00:00' });
};

const getServices = async () => {
  const result = await BluetoothLowEnergy.getServices({ deviceId: '00:00:00:00:00:00' });
  return result.services;
};

Read and write characteristics

Read the value of a characteristic or write a new value to it:

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const readCharacteristic = async () => {
  const result = await BluetoothLowEnergy.readCharacteristic({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
  });
  return result.value;
};

const writeCharacteristic = async () => {
  await BluetoothLowEnergy.writeCharacteristic({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
    value: [1, 2, 3],
  });
};

Read and write descriptors

Read the value of a descriptor or write a new value to it:

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const readDescriptor = async () => {
  const result = await BluetoothLowEnergy.readDescriptor({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    descriptorId: '00002902-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
  });
  return result.value;
};

const writeDescriptor = async () => {
  await BluetoothLowEnergy.writeDescriptor({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    descriptorId: '00002902-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
    value: [1, 2, 3],
  });
};

Receive characteristic notifications

Start and stop notifications for a characteristic to get notified when its value changes. The new values are delivered via the characteristicChanged event (see Listen for events):

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const startCharacteristicNotifications = async () => {
  await BluetoothLowEnergy.startCharacteristicNotifications({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
  });
};

const stopCharacteristicNotifications = async () => {
  await BluetoothLowEnergy.stopCharacteristicNotifications({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    deviceId: '00:00:00:00:00:00',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
  });
};

Tune the connection

Read the signal strength (RSSI) of a connected device. On Android, you can also request a higher connection priority or a larger MTU for faster data transfers (requestConnectionPriority(...) and requestMtu(...) are only available on Android):

import { BluetoothLowEnergy, ConnectionPriority } from '@capawesome-team/capacitor-bluetooth-low-energy';

const readRssi = async () => {
  const result = await BluetoothLowEnergy.readRssi({ deviceId: '00:00:00:00:00:00' });
  return result.rssi;
};

const requestConnectionPriority = async () => {
  await BluetoothLowEnergy.requestConnectionPriority({
    connectionPriority: ConnectionPriority.BALANCED,
    deviceId: '00:00:00:00:00:00',
  });
};

const requestMtu = async () => {
  await BluetoothLowEnergy.requestMtu({
    deviceId: '00:00:00:00:00:00',
    mtu: 512,
  });
};

Act as a peripheral

Advertise your own services to nearby central devices in the peripheral role. Use setCharacteristicValue(...) to update the value of a characteristic (only available on Android):

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const startAdvertising = async () => {
  await BluetoothLowEnergy.startAdvertising({
    manufacturerData: {
      0xffff: [1, 2, 3]
    },
    name: 'MyDevice',
    services: [
      {
        id: '0000180A-0000-1000-8000-00805F9B34FB',
        characteristics: [
          {
            id: '00002A29-0000-1000-8000-00805F9B34FB',
            descriptors: [], // Descriptors are ignored for now
            permissions: {
              read: true,
              write: true,
            },
            properties: {
              read: true,
              write: true,
              notify: true,
              indicate: true,
            },
          },
        ],
      },
    ],
  });
};

const setCharacteristicValue = async () => {
  await BluetoothLowEnergy.setCharacteristicValue({
    characteristicId: '00002a00-0000-1000-8000-00805f9b34fb',
    serviceId: '00001800-0000-1000-8000-00805f9b34fb',
    value: [1, 2, 3],
  });
};

const stopAdvertising = async () => {
  await BluetoothLowEnergy.stopAdvertising();
};

Keep the connection alive in the background

Start a foreground service to keep the connection alive while the app is in the background. Only available on Android (see Installation for the required service declaration and permissions):

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const startForegroundService = async () => {
  await BluetoothLowEnergy.startForegroundService({
    body: 'Body',
    id: 1,
    smallIcon: 'smallIcon',
    title: 'Title',
  });
};

const stopForegroundService = async () => {
  await BluetoothLowEnergy.stopForegroundService();
};

Open system settings

Open the app settings, Bluetooth settings, or location settings so the user can grant permissions or enable Bluetooth. openBluetoothSettings() and openLocationSettings() are only available on Android:

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const openAppSettings = async () => {
  await BluetoothLowEnergy.openAppSettings();
};

const openBluetoothSettings = async () => {
  await BluetoothLowEnergy.openBluetoothSettings();
};

const openLocationSettings = async () => {
  await BluetoothLowEnergy.openLocationSettings();
};

Listen for events

Listen for plugin events such as scanned, connected, and disconnected devices or changed characteristic values, and remove the listeners when they are no longer needed:

import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy';

const addListener = () => {
  BluetoothLowEnergy.addListener('characteristicChanged', (event) => {
    console.log('Characteristic changed', event);
  });

  BluetoothLowEnergy.addListener('characteristicWriteRequest', async (event) => {
    console.log('Characteristic write request', event);
  });

  BluetoothLowEnergy.addListener('deviceConnected', (event) => {
    console.log('Device connected', event);
  });

  BluetoothLowEnergy.addListener('deviceDisconnected', (event) => {
    console.log('Device disconnected', event);
  });

  BluetoothLowEnergy.addListener('deviceScanned', (event) => {
    console.log('Device scanned', event);
  });
};

const removeAllListeners = () => {
  BluetoothLowEnergy.removeAllListeners();
};

Convert byte arrays

Use the BluetoothLowEnergyUtils class to convert byte arrays to hexadecimal strings (see Utils for more information):

import { BluetoothLowEnergyUtils } from '@capawesome-team/capacitor-bluetooth-low-energy';

const convertBytesToHex = (bytes: number[]) => {
  return BluetoothLowEnergyUtils.convertBytesToHex({ bytes });
};

API

connect(...)
createBond(...)
disconnect(...)
discoverServices(...)
getConnectedDevices()
getServices(...)
initialize(...)
isAvailable()
isBonded(...)
isEnabled()
isExtendedAdvertisingAvailable()
isLocationEnabled()
openAppSettings()
openBluetoothSettings()
openLocationSettings()
readCharacteristic(...)
readDescriptor(...)
readRssi(...)
requestConnectionPriority(...)
requestMtu(...)
setCharacteristicValue(...)
startAdvertising(...)
startCharacteristicNotifications(...)
startForegroundService(...)
startScan(...)
stopAdvertising()
stopCharacteristicNotifications(...)
stopForegroundService()
stopScan()
writeCharacteristic(...)
writeDescriptor(...)
checkPermissions()
requestPermissions(...)
addListener('characteristicChanged', ...)
addListener('characteristicWriteRequest', ...)
addListener('deviceConnected', ...)
addListener('deviceDisconnected', ...)
addListener('deviceScanned', ...)
removeAllListeners()
Interfaces
Type Aliases
Enums

connect(...)

connect(options: ConnectOptions) => Promise<void>

Connect to a BLE device.

Only available on Android and iOS.

Param	Type
`options`	`ConnectOptions`

Since: 6.0.0

createBond(...)

createBond(options: CreateBondOptions) => Promise<void>

Create a bond with the BLE device.

Only available on Android.

Param	Type
`options`	`CreateBondOptions`

Since: 6.0.0

disconnect(...)

disconnect(options: DisconnectOptions) => Promise<void>

Disconnect from the BLE device.

Only available on Android and iOS.

Param	Type
`options`	`DisconnectOptions`

Since: 6.0.0

discoverServices(...)

discoverServices(options: DiscoverServiceOptions) => Promise<void>

Discover services provided by the device.

On iOS, this operation may take up to 30 seconds.

Only available on Android and iOS.

Param	Type
`options`	`DiscoverServiceOptions`

Since: 6.0.0

getConnectedDevices()

getConnectedDevices() => Promise<GetConnectedDevicesResult>

Get a list of connected devices.

Only available on Android and iOS.

Returns: Promise<GetConnectedDevicesResult>

Since: 6.0.0

getServices(...)

getServices(options: GetServicesOptions) => Promise<GetServicesResult>

Get a list of services provided by the device.

Only available on Android and iOS.

Param	Type
`options`	`GetServicesOptions`

Returns: Promise<GetServicesResult>

Since: 6.0.0

initialize(...)

initialize(options?: InitializeOptions | undefined) => Promise<void>

Initialize the plugin. This method must be called before any other method.

On iOS, this will prompt the user for Bluetooth permissions. On Android and Web, this does nothing.

Param	Type
`options`	`InitializeOptions`

Since: 6.0.0

isAvailable()

isAvailable() => Promise<IsAvailableResult>

Check whether or not Bluetooth Low Energy is available on the device.

Returns: Promise<IsAvailableResult>

Since: 7.3.0

isBonded(...)

isBonded(options: IsBondedOptions) => Promise<IsBondedResult>

Check if the device is bonded.

Only available on Android.

Param	Type
`options`	`IsBondedOptions`

Returns: Promise<IsBondedResult>

Since: 6.0.0

isEnabled()

isEnabled() => Promise<IsEnabledResult>

Check if Bluetooth is enabled.

On iOS, requires the plugin to be initialized. Returns false if not initialized.

Only available on Android and iOS.

Returns: Promise<IsEnabledResult>

Since: 6.0.0

isExtendedAdvertisingAvailable()

isExtendedAdvertisingAvailable() => Promise<IsExtendedAdvertisingAvailableResult>

Check if extended advertising is available on the device.

Extended advertising (BLE 5.0+) allows for larger advertising payloads (up to ~250 bytes in a single packet or ~1650 bytes with chaining) compared to legacy advertising (~27-31 bytes).

On Android, Bluetooth must be enabled; otherwise this always resolves to false, even if the device supports extended advertising. Use isEnabled() to check whether Bluetooth is enabled.

On iOS, this always resolves to false, since extended advertisements cannot be transmitted via CoreBluetooth.

Returns: Promise<IsExtendedAdvertisingAvailableResult>

Since: 8.2.0

isLocationEnabled()

isLocationEnabled() => Promise<IsLocationEnabledResult>

Check if location services are enabled.

Only available on Android.

Returns: Promise<IsLocationEnabledResult>

Since: 7.7.0

openAppSettings()

openAppSettings() => Promise<void>

Open the Bluetooth settings on the device.

Only available on Android and iOS.

Since: 6.0.0

openBluetoothSettings()

openBluetoothSettings() => Promise<void>

Open the Bluetooth settings on the device.

Only available on Android.

Since: 6.0.0

openLocationSettings()

openLocationSettings() => Promise<void>

Open the location settings on the device.

Only available on Android.

Since: 6.0.0

readCharacteristic(...)

readCharacteristic(options: ReadCharacteristicOptions) => Promise<ReadCharacteristicResult>

Read the value of a characteristic.

Only available on Android and iOS.

Param	Type
`options`	`ReadCharacteristicOptions`

Returns: Promise<ReadCharacteristicResult>

Since: 6.0.0

readDescriptor(...)

readDescriptor(options: ReadDescriptorOptions) => Promise<ReadDescriptorResult>

Read the value of a descriptor.

Only available on Android and iOS.

Param	Type
`options`	`ReadDescriptorOptions`

Returns: Promise<ReadDescriptorResult>

Since: 6.0.0

readRssi(...)

readRssi(options: ReadRssiOptions) => Promise<ReadRssiResult>

Read the RSSI value of the device.

Only available on Android and iOS.

Param	Type
`options`	`ReadRssiOptions`

Returns: Promise<ReadRssiResult>

Since: 6.0.0

requestConnectionPriority(...)

requestConnectionPriority(options: RequestConnectionPriorityOptions) => Promise<void>

Request a connection priority.

Only available on Android.

Param	Type
`options`	`RequestConnectionPriorityOptions`

Since: 6.0.0

requestMtu(...)

requestMtu(options: RequestMtuOptions) => Promise<void>

Request an MTU size.

Only available on Android.

Param	Type
`options`	`RequestMtuOptions`

Since: 6.0.0

setCharacteristicValue(...)

setCharacteristicValue(options: SetCharacteristicValueOptions) => Promise<void>

Set the value of a characteristic.

Only available on Android and iOS.

Param	Type
`options`	`SetCharacteristicValueOptions`

Since: 7.2.0

startAdvertising(...)

startAdvertising(options: StartAdvertisingOptions) => Promise<void>

Start advertising as a BLE device.

Only available on Android and iOS.

Param	Type
`options`	`StartAdvertisingOptions`

Since: 7.2.0

startCharacteristicNotifications(...)

startCharacteristicNotifications(options: StartCharacteristicNotificationsOptions) => Promise<void>

Start listening for characteristic value changes. This will emit the characteristicChanged event when a value changes.

Only available on Android and iOS.

Param	Type
`options`	`StartCharacteristicNotificationsOptions`

Since: 6.0.0

startForegroundService(...)

startForegroundService(options?: StartForegroundServiceOptions | undefined) => Promise<void>

Start the foreground service and show a notification.

This method should be called when the app is moved to the background to keep the Bluetooth connections alive.

Only available on Android.

Param	Type
`options`	`StartForegroundServiceOptions`

Since: 6.0.0

startScan(...)

startScan(options?: StartScanOptions | undefined) => Promise<void>

Start scanning for BLE devices. This will emit the deviceScanned event when a device is found.

Only available on Android and iOS.

Param	Type
`options`	`StartScanOptions`

Since: 6.0.0

stopAdvertising()

stopAdvertising() => Promise<void>

Stop advertising as a BLE device.

Only available on Android and iOS.

Since: 7.2.0

stopCharacteristicNotifications(...)

stopCharacteristicNotifications(options: StopCharacteristicNotificationsOptions) => Promise<void>

Stop listening for characteristic value changes.

Only available on Android and iOS.

Param	Type
`options`	`StopCharacteristicNotificationsOptions`

Since: 6.0.0

stopForegroundService()

stopForegroundService() => Promise<void>

Stop the foreground service and remove the notification.

This method should be called when the app is moved to the foreground since the foreground service is no longer needed.

Only available on Android.

Since: 6.0.0

stopScan()

stopScan() => Promise<void>

Stop scanning for BLE devices.

Only available on Android and iOS.

Since: 6.0.0

writeCharacteristic(...)

writeCharacteristic(options: WriteCharacteristicOptions) => Promise<void>

Write a value to a characteristic.

Only available on Android and iOS.

Param	Type
`options`	`WriteCharacteristicOptions`

Since: 6.0.0

writeDescriptor(...)

writeDescriptor(options: WriteDescriptorOptions) => Promise<void>

Write a value to a descriptor.

Only available on Android and iOS.

Param	Type
`options`	`WriteDescriptorOptions`

Since: 6.0.0

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check permissions for the plugin.

Only available on Android.

Returns: Promise<PermissionStatus>

Since: 6.0.0

requestPermissions(...)

requestPermissions(permissions?: BluetoothLowEnergyPluginPermission | undefined) => Promise<PermissionStatus>

Request permissions for the plugin.

Only available on Android.

Param	Type
`permissions`	`BluetoothLowEnergyPluginPermission`

Returns: Promise<PermissionStatus>

Since: 6.0.0

addListener('characteristicChanged', ...)

addListener(eventName: 'characteristicChanged', listenerFunc: (event: CharacteristicChangedEvent) => void) => Promise<PluginListenerHandle>

Called when a characteristic value changes.

Only available on Android and iOS.

Param	Type
`eventName`	`'characteristicChanged'`
`listenerFunc`	`(event: CharacteristicChangedEvent) => void`

Returns: Promise<PluginListenerHandle>

Since: 6.0.0

addListener('characteristicWriteRequest', ...)

addListener(eventName: 'characteristicWriteRequest', listenerFunc: (event: CharacteristicWriteRequestEvent) => void) => Promise<PluginListenerHandle>

Called when a characteristic write request is received.

Only available on Android.

Param	Type
`eventName`	`'characteristicWriteRequest'`
`listenerFunc`	`(event: CharacteristicWriteRequestEvent) => void`

Returns: Promise<PluginListenerHandle>

Since: 7.2.0

addListener('deviceConnected', ...)

addListener(eventName: 'deviceConnected', listenerFunc: (event: DeviceConnectedEvent) => void) => Promise<PluginListenerHandle>

Called when a device is connected.

Only available on Android and iOS.

Param	Type
`eventName`	`'deviceConnected'`
`listenerFunc`	`(event: DeviceConnectedEvent) => void`

Returns: Promise<PluginListenerHandle>

Since: 7.1.0

addListener('deviceDisconnected', ...)

addListener(eventName: 'deviceDisconnected', listenerFunc: (event: DeviceDisconnectedEvent) => void) => Promise<PluginListenerHandle>

Called when a device is disconnected.

Only available on Android and iOS.

Param	Type
`eventName`	`'deviceDisconnected'`
`listenerFunc`	`(event: DeviceDisconnectedEvent) => void`

Returns: Promise<PluginListenerHandle>

Since: 6.0.0

addListener('deviceScanned', ...)

addListener(eventName: 'deviceScanned', listenerFunc: (event: DeviceScannedEvent) => void) => Promise<PluginListenerHandle>

Called when an error occurs during the scan session.

Only available on Android and iOS.

Param	Type
`eventName`	`'deviceScanned'`
`listenerFunc`	`(event: DeviceScannedEvent) => void`

Returns: Promise<PluginListenerHandle>

Since: 6.0.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 6.0.0

Interfaces

ConnectOptions

Prop	Type	Description	Default	Since
`autoConnect`	`boolean`	Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true). Only available on Android.	`false`	7.1.0
`autoReconnect`	`boolean`	Whether to enable automatic reconnection to the peripheral when the connection is lost. Only available on Android and iOS (17.0+).	`false`	7.6.0
`deviceId`	`string`	The address of the device to connect to.		6.0.0
`timeout`	`number`	The timeout for the connect operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`10000`	6.0.0

CreateBondOptions

Prop	Type	Description	Default	Since
`deviceId`	`string`	The address of the device to create a bond with.		6.0.0
`timeout`	`number`	The timeout for the create bond operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`10000`	6.0.0

DisconnectOptions

Prop	Type	Description	Default	Since
`deviceId`	`string`	The address of the device to disconnect from.		6.0.0
`timeout`	`number`	The timeout for the disconnect operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`5000`	6.0.0

DiscoverServiceOptions

Prop	Type	Description	Default	Since
`deviceId`	`string`	The address of the device to discover services for.		6.0.0
`timeout`	`number`	The timeout for the discover services operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`20000`	6.0.0

GetConnectedDevicesResult

Prop	Type	Description	Since
`devices`	`Device[]`	An array of connected devices.	6.0.0

Device

Prop	Type	Description	Since
`id`	`string`	The UUID of the connected device.	6.0.0
`name`	`string`	The name of the connected device.	6.0.0

GetServicesResult

Prop	Type	Description	Since
`services`	`Service[]`	An array of services provided by the device.	6.0.0

Service

Prop	Type	Description	Since
`id`	`string`	The UUID of the service.	6.0.0
`characteristics`	`Characteristic[]`	The characteristics of the service.	6.0.0

Characteristic

Prop	Type	Description	Since
`id`	`string`	The UUID of the characteristic.	6.0.0
`descriptors`	`Descriptor[]`	The descriptors of the characteristic. Note: This property is currently ignored when advertising a characteristic.	6.0.0
`permissions`	`CharacteristicPermissions`	The permissions of the characteristic. Only available on Android.	7.2.0
`properties`	`CharacteristicProperties`	The properties of the characteristic.	6.0.0

Descriptor

Prop	Type	Description	Since
`id`	`string`	The UUID of the descriptor.	6.0.0

CharacteristicPermissions

Prop	Type	Description	Since
`read`	`boolean`	Whether or not the characteristic can be read.	7.2.0
`readEncrypted`	`boolean`	Whether or not the characteristic can be read with encryption.	7.2.0
`readEncryptedMitm`	`boolean`	Whether or not the characteristic can be read with encryption and MITM protection. Only available on Android.	7.2.0
`write`	`boolean`	Whether or not the characteristic can be written.	7.2.0
`writeEncrypted`	`boolean`	Whether or not the characteristic can be written with encryption.	7.2.0
`writeEncryptedMitm`	`boolean`	Whether or not the characteristic can be written with encryption and MITM protection. Only available on Android.	7.2.0
`writeSigned`	`boolean`	Whether or not the characteristic can be written signed. Only available on Android.	7.2.0
`writeSignedMitm`	`boolean`	Whether or not the characteristic can be written signed with encryption. Only available on Android.	7.2.0

CharacteristicProperties

Prop	Type	Description	Since
`broadcast`	`boolean`	Whether or not the characteristic can be broadcast.	6.0.0
`read`	`boolean`	Whether or not the characteristic can be read.	6.0.0
`writeWithoutResponse`	`boolean`	Whether or not the characteristic can be written without response.	6.0.0
`write`	`boolean`	Whether or not the characteristic can be written.	6.0.0
`notify`	`boolean`	Whether or not the characteristic supports notifications.	6.0.0
`indicate`	`boolean`	Whether or not the characteristic supports indications.	6.0.0
`authenticatedSignedWrites`	`boolean`	Whether or not the characteristic supports signed writes.	6.0.0
`extendedProperties`	`boolean`	Whether or not the characteristic supports extended properties.	6.0.0
`notifyEncryptionRequired`	`boolean`	Whether or not the characteristic supports reliable writes.	6.0.0
`indicateEncryptionRequired`	`boolean`	Whether or not the characteristic supports writable auxiliaries.	6.0.0

GetServicesOptions

Prop	Type	Description	Default	Since
`deviceId`	`string`	The address of the device to get the services for.		6.0.0
`timeout`	`number`	The timeout for the get services operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`5000`	6.0.0

InitializeOptions

Prop	Type	Description	Default	Since
`mode`	`'central' \| 'peripheral'`	The mode of the Bluetooth Low Energy plugin. Only available on iOS.	`'central'`	7.2.0
`showPowerAlert`	`boolean`	Whether the system should display a warning dialog to the user if Bluetooth is powered off when the plugin is initialized. If not specified, the default value is `true` in `central` mode and `false` in `peripheral` mode. Only available on iOS.		8.1.0

IsAvailableResult

Prop	Type	Description	Since
`isAvailable`	`boolean`	Whether or not Bluetooth Low Energy is available on the device.	7.3.0

IsBondedResult

Prop	Type	Description	Since
`bonded`	`boolean`	Whether or not the device is bonded.	6.0.0

IsBondedOptions

Prop	Type	Description	Since
`deviceId`	`string`	The address of the device to check if it is bonded.	6.0.0
`timeout`	`number`	The timeout for the is bonded operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	6.0.0

IsEnabledResult

Prop	Type	Description	Since
`enabled`	`boolean`	Whether or not Bluetooth is enabled.	6.0.0

IsExtendedAdvertisingAvailableResult

Prop	Type	Description	Since
`isAvailable`	`boolean`	Whether extended advertising is available on the device.	8.2.0
`maxAdvertisingDataLength`	`number`	Maximum advertising data length in bytes. This is only available when `isAvailable` is `true`.	8.2.0

IsLocationEnabledResult

Prop	Type	Description	Since
`enabled`	`boolean`	Whether or not location services are enabled.	7.7.0

ReadCharacteristicResult

Prop	Type	Description	Since
`value`	`number[]`	The value bytes of the characteristic.	6.0.0

ReadCharacteristicOptions

Prop	Type	Description	Default	Since
`characteristicId`	`string`	The UUID of the characteristic to read.		6.0.0
`deviceId`	`string`	The address of the device to read the characteristic from.		6.0.0
`serviceId`	`string`	The UUID of the service to read the characteristic from.		6.0.0
`timeout`	`number`	The timeout for the read operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`5000`	6.0.0

ReadDescriptorResult

Prop	Type	Description	Since
`value`	`number[]`	The value bytes of the descriptor.	6.0.0

ReadDescriptorOptions

Prop	Type	Description	Default	Since
`characteristicId`	`string`	The UUID of the characteristic that the descriptor belongs to.		6.0.0
`descriptorId`	`string`	The UUID of the descriptor to read.		6.0.0
`deviceId`	`string`	The address of the device to read the descriptor from.		6.0.0
`serviceId`	`string`	The UUID of the service that the descriptor belongs to.		6.0.0
`timeout`	`number`	The timeout for the read operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`5000`	6.0.0

ReadRssiResult

Prop	Type	Description	Since
`rssi`	`number`	The RSSI value.	6.0.0

ReadRssiOptions

Prop	Type	Description	Default	Since
`deviceId`	`string`	The address of the device to read the RSSI for.		6.0.0
`timeout`	`number`	The timeout for the read RSSI operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`5000`	6.0.0

RequestConnectionPriorityOptions

Prop	Type	Description	Since
`deviceId`	`string`	The address of the device to request the connection priority for.	6.0.0
`connectionPriority`	`ConnectionPriority`	The connection priority to request.	6.0.0
`timeout`	`number`	The timeout for the request connection priority operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	6.0.0

RequestMtuOptions

Prop	Type	Description	Since
`deviceId`	`string`	The address of the device to request the MTU size for.	6.0.0
`mtu`	`number`	The mtu size to request.	6.0.0
`timeout`	`number`	The timeout for the request MTU operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	6.0.0

SetCharacteristicValueOptions

Prop	Type	Description	Since
`characteristicId`	`string`	The UUID of the characteristic to set the value for.	7.2.0
`serviceId`	`string`	The UUID of the service to set the value for.	7.2.0
`value`	`number[]`	The value bytes to set for the characteristic.	7.2.0

StartAdvertisingOptions

Prop	Type	Description	Since
`manufacturerData`	`{ [key: number]: number[]; }`	The manufacturer specific data to advertise. Only available on Android.	7.5.0
`name`	`string`	The name of the local device to advertise. On Android, for apps targeting `Build.VERSION_CODES.R` or lower, this requires the `BLUETOOTH_ADMIN` permission. For apps targeting `Build.VERSION_CODES.S` or higher, this requires the `BLUETOOTH_CONNECT` permission. Only available on Android and iOS.	7.2.0
`serviceData`	`{ [key: string]: number[]; }`	Service data to advertise (UUID -> byte array). Only available on Android and only when `settings.legacyMode` is `false`.	8.2.0
`services`	`Service[]`	The services to advertise.	7.2.0
`settings`	`AdvertisingSettings`	Extended advertising settings (BLE 5.0+). Only available on Android.	8.2.0

AdvertisingSettings

Prop	Type	Description	Default	Since
`legacyMode`	`boolean`	Whether to use legacy advertising mode (BLE 4.x compatible). When `true`, uses legacy advertising which is compatible with all BLE devices but limited to ~27-31 bytes of advertising data. When `false`, uses extended advertising (BLE 5.0+) which supports larger payloads.	`true`	8.2.0
`connectable`	`boolean`	Whether the advertisement is connectable.	`true`	8.2.0
`scannable`	`boolean`	Whether the advertisement is scannable. Only applies when `legacyMode` is `false`.	`false`	8.2.0
`interval`	`AdvertisingInterval`	Advertising interval.	`AdvertisingInterval.LOW_LATENCY`	8.2.0
`txPowerLevel`	`AdvertisingTxPowerLevel`	TX power level.	`AdvertisingTxPowerLevel.HIGH`	8.2.0
`primaryPhy`	`AdvertisingPhy`	Primary PHY for advertising. Only applies when `legacyMode` is `false`.	`AdvertisingPhy.PHY_LE_1M`	8.2.0
`secondaryPhy`	`AdvertisingPhy`	Secondary PHY for advertising. Only applies when `legacyMode` is `false`.	`AdvertisingPhy.PHY_LE_1M`	8.2.0

StartCharacteristicNotificationsOptions

Prop	Type	Description	Default	Since
`characteristicId`	`string`	The UUID of the characteristic to start notifications for.		6.0.0
`deviceId`	`string`	The address of the device to start notifications for.		6.0.0
`serviceId`	`string`	The UUID of the service to start notifications for.		6.0.0
`timeout`	`number`	The timeout for the start notifications operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`5000`	6.0.0

StartForegroundServiceOptions

Prop	Type	Description	Default	Since
`body`	`string`	The body of the notification, shown below the title.	`"App is running in the background to keep Bluetooth connections alive."`	6.0.0
`id`	`number`	The notification identifier.	`105`	6.0.0
`smallIcon`	`string`	The status bar icon for the notification. Icons should be placed in your app's `res/drawable` folder. The value for this option should be the drawable resource ID, which is the filename without an extension.		6.0.0
`title`	`string`	The title of the notification.	`"Bluetooth Low Energy"`	6.0.0

StartScanOptions

Prop	Type	Description	Default	Since
`allowDuplicates`	`boolean`	Whether to emit the `deviceScanned` event for every advertisement packet received, instead of only the first advertisement of each device. This is required to receive manufacturer data or service data that is spread across multiple advertisement packets (e.g. when the value is delivered in the scan response packet on iOS). On iOS, this maps to `CBCentralManagerScanOptionAllowDuplicatesKey` and is only honored while the app is in the foreground.	`false`	8.2.0
`extended`	`boolean`	Whether to use extended advertising scanning (BLE 5.0+) to also discover devices that use extended advertising. When enabled, both legacy and extended advertisements are reported. On iOS, extended advertisements are received automatically during a normal scan, so this option is not needed and has no effect. Only available on Android.	`false`	8.2.0
`phy`	`ScanPhy`	The PHY to use for scanning. Only applies when `extended` is `true`. Only available on Android.	`ScanPhy.PHY_LE_ALL_SUPPORTED`	8.2.0
`serviceIds`	`string[]`	Find devices with services that match any of the provided UUIDs. Only available on iOS.		6.0.0

StopCharacteristicNotificationsOptions

Prop	Type	Description	Default	Since
`characteristicId`	`string`	The UUID of the characteristic to stop notifications for.		6.0.0
`deviceId`	`string`	The address of the device to stop notifications for.		6.0.0
`serviceId`	`string`	The UUID of the service to stop notifications for.		6.0.0
`timeout`	`number`	The timeout for the stop notifications operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`5000`	6.0.0

WriteCharacteristicOptions

Prop	Type	Description	Default	Since
`characteristicId`	`string`	The UUID of the characteristic to write.		6.0.0
`deviceId`	`string`	The address of the device to write the characteristic to.		6.0.0
`serviceId`	`string`	The UUID of the service to write the characteristic to.		6.0.0
`timeout`	`number`	The timeout for the write operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`5000`	6.0.0
`type`	`'default' \| 'withoutResponse'`	The type of write operation.	`'default'`	6.1.0
`value`	`number[]`	The value bytes to write to the characteristic.		6.0.0

WriteDescriptorOptions

Prop	Type	Description	Default	Since
`characteristicId`	`string`	The UUID of the characteristic that the descriptor belongs to.		6.0.0
`descriptorId`	`string`	The UUID of the descriptor.		6.0.0
`deviceId`	`string`	The address of the device that the descriptor belongs to.		6.0.0
`serviceId`	`string`	The UUID of the service that the descriptor belongs to.		6.0.0
`timeout`	`number`	The timeout for the write operation in milliseconds. If the operation takes longer than this value, the promise will be rejected.	`5000`	6.0.0
`value`	`number[]`	The value bytes of the descriptor.		6.0.0

PermissionStatus

Prop	Type	Description	Since
`bluetooth`	`PermissionState`	Permission state for using bluetooth. Only available on iOS.	6.0.0
`bluetoothConnect`	`PermissionState`	Permission state for connecting to a BLE device. Only available on Android.	6.0.0
`bluetoothScan`	`PermissionState`	Permission state for scanning for BLE devices. Only available on Android.	6.0.0
`location`	`PermissionState`	Permission state for using location services. Only available on Android.	6.0.0
`notifications`	`PermissionState`	Permission state for using notifications. Only available on Android.	6.0.0

BluetoothLowEnergyPluginPermission

Prop	Type	Description	Default
`permissions`	`BluetoothLowEnergyPermissionType[]`	The permissions to request.	`['bluetooth', 'bluetoothAdmin', 'bluetoothConnect', 'bluetoothScan', 'location', 'notifications']`

PluginListenerHandle

Prop	Type
`remove`	`() => Promise<void>`

CharacteristicChangedEvent

Prop	Type	Description	Since
`characteristicId`	`string`	The UUID of the characteristic.	6.0.0
`deviceId`	`string`	The address of the device.	6.0.0
`serviceId`	`string`	The UUID of the service.	6.0.0
`value`	`number[]`	The changed value bytes of the characteristic.	6.0.0

CharacteristicWriteRequestEvent

Prop	Type	Description	Since
`characteristicId`	`string`	The UUID of the characteristic.	7.2.0
`serviceId`	`string`	The address of the device.	7.2.0
`value`	`number[]`	The value bytes to write to the characteristic.	7.2.0

DeviceConnectedEvent

Prop	Type	Description	Since
`deviceId`	`string`	The address of the connected device.	7.1.0
`name`	`string`	The name of the connected device.	7.1.0

DeviceDisconnectedEvent

Prop	Type	Description	Since
`deviceId`	`string`	The address of the disconnected device.	6.0.0
`name`	`string`	The name of the disconnected device.	6.0.0

DeviceScannedEvent

Prop	Type	Description	Since
`id`	`string`	The address of the scanned device.	6.0.0
`localName`	`string`	The local name of the scanned device from the advertisement data. In contrast to `name`, this always reflects the value from the current advertisement packet.	8.2.0
`manufacturerData`	`{ [key: number]: number[]; }`	The manufacturer specific data from the advertisement data. The key is the 16-bit company identifier and the value is the payload bytes.	8.2.0
`name`	`string`	The name of the scanned device. On iOS, this returns the cached GAP name and may differ from `localName` after a previous connection to the device.	6.0.0
`rawAdvertisement`	`number[]`	The raw bytes of the advertisement data. Only available on Android.	8.2.0
`rssi`	`number`	The RSSI value of the scanned device.	6.0.0
`serviceData`	`{ [uuid: string]: number[]; }`	The service data from the advertisement data. The key is the service UUID and the value is the payload bytes.	8.2.0
`serviceUuids`	`string[]`	The UUIDs of the services advertised by the device.	8.2.0
`txPower`	`number`	The transmit power of the scanned device in dBm.	8.2.0

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

BluetoothLowEnergyPermissionType

Enums

ConnectionPriority

Members	Value	Description	Since
`BALANCED`	`0`	Balanced connection priority.	6.0.0
`HIGH`	`1`	High connection priority.	6.0.0
`LOW_POWER`	`2`	Low power connection priority.	6.0.0
`PRIORITY_DCK`	`3`	Digital Car Key connection priority.	6.0.0

AdvertisingInterval

Members	Value	Description	Since
`LOW_LATENCY`	`'LOW_LATENCY'`	Low latency advertising interval (~100ms).	8.2.0
`BALANCED`	`'BALANCED'`	Balanced advertising interval (~250ms).	8.2.0
`LOW_POWER`	`'LOW_POWER'`	Low power advertising interval (~1000ms).	8.2.0

AdvertisingTxPowerLevel

Members	Value	Description	Since
`ULTRA_LOW`	`'ULTRA_LOW'`	Ultra-low TX power level.	8.2.0
`LOW`	`'LOW'`	Low TX power level.	8.2.0
`MEDIUM`	`'MEDIUM'`	Medium TX power level.	8.2.0
`HIGH`	`'HIGH'`	High TX power level.	8.2.0

AdvertisingPhy

Members	Value	Description	Since
`PHY_LE_1M`	`'PHY_LE_1M'`	LE 1M PHY (default, compatible with BLE 4.x).	8.2.0
`PHY_LE_2M`	`'PHY_LE_2M'`	LE 2M PHY (higher throughput, BLE 5.0+).	8.2.0
`PHY_LE_CODED`	`'PHY_LE_CODED'`	LE Coded PHY (longer range, BLE 5.0+).	8.2.0

ScanPhy

Members	Value	Description	Since
`PHY_LE_1M`	`'PHY_LE_1M'`	LE 1M PHY (compatible with BLE 4.x).	8.2.0
`PHY_LE_CODED`	`'PHY_LE_CODED'`	LE Coded PHY (longer range, BLE 5.0+).	8.2.0
`PHY_LE_ALL_SUPPORTED`	`'PHY_LE_ALL_SUPPORTED'`	Scan on all supported PHYs (default).	8.2.0

Utils

This plugin provides a utility class BluetoothLowEnergyUtils that can be used for various Bluetooth Low Energy related operations, for example, converting byte arrays to hexadecimal strings:

import { BluetoothLowEnergyUtils } from '@capacitor-community/bluetooth-low-energy';

const convertBytesToHex = (bytes: number[]) => {
  return BluetoothLowEnergyUtils.convertBytesToHex({ bytes });
};

See docs/utils/README.md for more information.

Bluetooth 5.0 (BLE 5) support

Several BLE 5 capabilities behave differently across platforms due to operating system constraints. These are platform limitations, not limitations of the plugin.

Capability	Android	iOS
Extended advertising (large payloads, manufacturer/service data, PHY, interval, TX power)	✅ Supported	❌ Not supported (no CoreBluetooth API)
Extended advertisement scanning	✅ Supported and configurable (`extended`, `phy`)	✅ Handled automatically, not configurable
Coded PHY (LE Long Range)	✅ Supported	⚠️ Not reliably supported

FAQ

Does the plugin work on the Web?

No, the plugin supports Android and iOS. Web browsers do not provide the required APIs for the full feature set of this plugin, such as the peripheral role or foreground services.

Which permissions do I need on Android?

The required permissions depend on the features you use: BLUETOOTH_SCAN and ACCESS_FINE_LOCATION for scanning, BLUETOOTH_CONNECT for connecting to paired devices, BLUETOOTH_ADVERTISE for advertising as a peripheral, and the foreground service permissions if you want to start a foreground service. On Android 11 and below, the legacy BLUETOOTH and BLUETOOTH_ADMIN permissions are required instead. See Installation for the complete list and use checkPermissions() and requestPermissions() at runtime.

How do I keep the BLE connection alive while the app is in the background?

On Android, start a foreground service using the startForegroundService(...) method, which requires the service declaration and foreground service permissions described in the Installation section. On iOS, enable the Background Modes capability with bluetooth-central in your Xcode project.

Can my app act as a BLE peripheral?

Yes, the plugin supports the peripheral role in addition to the central role. Use startAdvertising(...) to advertise your own services to nearby central devices. Note that setCharacteristicValue(...) and the characteristicWriteRequest event are only available on Android.

Can I connect to multiple devices at the same time?

Yes, the plugin supports connections to multiple devices at the same time. Each method that operates on a device takes a deviceId parameter, and you can retrieve all currently connected devices using the getConnectedDevices() method.

What is a headless task and when do I need one?

A headless task lets you run your own native code when a specific Bluetooth Low Energy event occurs, for example when a characteristic value changes. For this, you create a Java class named BluetoothLowEnergyHeadlessTask in the same package as your MainActivity on Android, as described in the Installation section. This is useful if you need to react to events even when the web view is not running.

Related Plugins

Android Battery Optimization: Manage battery optimization settings and request exemptions to keep background work running reliably.
Android Foreground Service: Run a foreground service on Android.
Network: Access network information such as connection status and type, and listen for network changes.
NFC: Read, write, and emulate NFC tags with advanced features like HCE and raw command handling.
Wi-Fi: Manage Wi-Fi connectivity, including adding, connecting, and disconnecting networks.

Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our Capawesome Newsletter.

Changelog

See CHANGELOG.md.

Breaking Changes

See BREAKING.md.

License

See LICENSE.

This project is not affiliated with, endorsed by, sponsored by, or approved by Bluetooth SIG, Inc. or any of their affiliates or subsidiaries. ↩
Bluetooth is a registered trademark of Bluetooth SIG, Inc. ↩

Uh oh!

Uh oh!

FilesExpand file tree

bluetooth-low-energy

Directory actions

More options

Directory actions

More options

Latest commit

History

bluetooth-low-energy

Folders and files

parent directory

README.md

Capacitor Bluetooth Low Energy Plugin

Features

Use Cases

Testimonials

Compatibility

Demo

Guides

Installation

Android

Features

Permissions

Services

Headless Task

Proguard

iOS

Privacy Descriptions

Capabilities

Configuration

Usage

Initialize the plugin

Check and request permissions

Scan for devices

Connect to a device

Bond with a device

Discover services

Read and write characteristics

Read and write descriptors

Receive characteristic notifications

Tune the connection

Act as a peripheral

Keep the connection alive in the background

Open system settings

Listen for events

Convert byte arrays

API

connect(...)

createBond(...)

disconnect(...)

discoverServices(...)

getConnectedDevices()

getServices(...)

initialize(...)

isAvailable()

isBonded(...)

isEnabled()

isExtendedAdvertisingAvailable()

isLocationEnabled()

openAppSettings()

openBluetoothSettings()

openLocationSettings()

readCharacteristic(...)

readDescriptor(...)

readRssi(...)

requestConnectionPriority(...)

requestMtu(...)

setCharacteristicValue(...)

startAdvertising(...)

startCharacteristicNotifications(...)

startForegroundService(...)

startScan(...)

stopAdvertising()

stopCharacteristicNotifications(...)

stopForegroundService()

stopScan()

writeCharacteristic(...)

writeDescriptor(...)