--- title: Capacitor Bluetooth Low Energy Plugin for Android & iOS description: Capacitor plugin for Bluetooth Low Energy (BLE) communication with advanced features like headless tasks, foreground services, and more. tags: - Insiders - Android - iOS search: boost: 2 faq: true github_repo: capawesome-team/capacitor-plugins --- # 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.[^1][^2]
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](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/), [Android Foreground Service](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/) and [NFC](https://capawesome.io/docs/sdks/capacitor/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](https://github.com/capawesome-team/capacitor-plugins/issues) 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](https://capawesome.io/docs/sdks/capacitor/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](https://padel-band.com) 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](https://github.com/capawesome-team/capacitor-heart-rate-monitor-app). | Android | iOS | | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | Android Demo | iOS Demo | ## Guides - [Announcing the Capacitor Bluetooth Low Energy Plugin](https://capawesome.io/blog/announcing-the-capacitor-bluetooth-low-energy-plugin/) - [How to Build a Heart Rate Monitor with Capacitor](https://capawesome.io/blog/how-to-build-a-heart-rate-monitor-with-capacitor/) ## Installation This plugin is only available to [Capawesome Insiders](https://capawesome.io/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 ``` **Attention**: Replace `` 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](https://capawesome.io/insiders/). Next, you can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: ```bash 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: ```bash 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: ```xml ``` 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: ```xml ``` You can read more about Bluetooth permissions in the [Android documentation](https://developer.android.com/develop/connectivity/bluetooth/bt-permissions). #### Services You also need to add the following service **inside** the `application` tag in your `AndroidManifest.xml` (usually `android/app/src/main/AndroidManifest.xml`): ```xml ``` #### 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: ```java 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: ```xml NSBluetoothAlwaysUsageDescription The app needs access to Bluetooth peripherals to communicate with Bluetooth devices. ``` #### 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](https://help.apple.com/xcode/mac/current/#/dev88ff319e7) 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: ```typescript 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: ```typescript 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](#listen-for-events)): ```typescript 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: ```typescript 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: ```typescript 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: ```typescript 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: ```typescript 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: ```typescript 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](#listen-for-events)): ```typescript 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): ```typescript 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): ```typescript 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](#installation) for the required service declaration and permissions): ```typescript 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: ```typescript 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: ```typescript 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](#utils) for more information): ```typescript import { BluetoothLowEnergyUtils } from '@capawesome-team/capacitor-bluetooth-low-energy'; const convertBytesToHex = (bytes: number[]) => { return BluetoothLowEnergyUtils.convertBytesToHex({ bytes }); }; ``` ## API * [`connect(...)`](#connect) * [`createBond(...)`](#createbond) * [`disconnect(...)`](#disconnect) * [`discoverServices(...)`](#discoverservices) * [`getConnectedDevices()`](#getconnecteddevices) * [`getServices(...)`](#getservices) * [`initialize(...)`](#initialize) * [`isAvailable()`](#isavailable) * [`isBonded(...)`](#isbonded) * [`isEnabled()`](#isenabled) * [`isExtendedAdvertisingAvailable()`](#isextendedadvertisingavailable) * [`isLocationEnabled()`](#islocationenabled) * [`openAppSettings()`](#openappsettings) * [`openBluetoothSettings()`](#openbluetoothsettings) * [`openLocationSettings()`](#openlocationsettings) * [`readCharacteristic(...)`](#readcharacteristic) * [`readDescriptor(...)`](#readdescriptor) * [`readRssi(...)`](#readrssi) * [`requestConnectionPriority(...)`](#requestconnectionpriority) * [`requestMtu(...)`](#requestmtu) * [`setCharacteristicValue(...)`](#setcharacteristicvalue) * [`startAdvertising(...)`](#startadvertising) * [`startCharacteristicNotifications(...)`](#startcharacteristicnotifications) * [`startForegroundService(...)`](#startforegroundservice) * [`startScan(...)`](#startscan) * [`stopAdvertising()`](#stopadvertising) * [`stopCharacteristicNotifications(...)`](#stopcharacteristicnotifications) * [`stopForegroundService()`](#stopforegroundservice) * [`stopScan()`](#stopscan) * [`writeCharacteristic(...)`](#writecharacteristic) * [`writeDescriptor(...)`](#writedescriptor) * [`checkPermissions()`](#checkpermissions) * [`requestPermissions(...)`](#requestpermissions) * [`addListener('characteristicChanged', ...)`](#addlistenercharacteristicchanged-) * [`addListener('characteristicWriteRequest', ...)`](#addlistenercharacteristicwriterequest-) * [`addListener('deviceConnected', ...)`](#addlistenerdeviceconnected-) * [`addListener('deviceDisconnected', ...)`](#addlistenerdevicedisconnected-) * [`addListener('deviceScanned', ...)`](#addlistenerdevicescanned-) * [`removeAllListeners()`](#removealllisteners) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) ### connect(...) ```typescript connect(options: ConnectOptions) => Promise ``` Connect to a BLE device. Only available on Android and iOS. | Param | Type | | ------------- | --------------------------------------------------------- | | **`options`** | ConnectOptions | **Since:** 6.0.0 -------------------- ### createBond(...) ```typescript createBond(options: CreateBondOptions) => Promise ``` Create a bond with the BLE device. Only available on Android. | Param | Type | | ------------- | --------------------------------------------------------------- | | **`options`** | CreateBondOptions | **Since:** 6.0.0 -------------------- ### disconnect(...) ```typescript disconnect(options: DisconnectOptions) => Promise ``` Disconnect from the BLE device. Only available on Android and iOS. | Param | Type | | ------------- | --------------------------------------------------------------- | | **`options`** | DisconnectOptions | **Since:** 6.0.0 -------------------- ### discoverServices(...) ```typescript discoverServices(options: DiscoverServiceOptions) => Promise ``` 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() ```typescript getConnectedDevices() => Promise ``` Get a list of connected devices. Only available on Android and iOS. **Returns:** Promise<GetConnectedDevicesResult> **Since:** 6.0.0 -------------------- ### getServices(...) ```typescript getServices(options: GetServicesOptions) => Promise ``` 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(...) ```typescript initialize(options?: InitializeOptions | undefined) => Promise ``` 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() ```typescript isAvailable() => Promise ``` Check whether or not Bluetooth Low Energy is available on the device. **Returns:** Promise<IsAvailableResult> **Since:** 7.3.0 -------------------- ### isBonded(...) ```typescript isBonded(options: IsBondedOptions) => Promise ``` Check if the device is bonded. Only available on Android. | Param | Type | | ------------- | ----------------------------------------------------------- | | **`options`** | IsBondedOptions | **Returns:** Promise<IsBondedResult> **Since:** 6.0.0 -------------------- ### isEnabled() ```typescript isEnabled() => Promise ``` 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() ```typescript isExtendedAdvertisingAvailable() => Promise ``` 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() ```typescript isLocationEnabled() => Promise ``` Check if location services are enabled. Only available on Android. **Returns:** Promise<IsLocationEnabledResult> **Since:** 7.7.0 -------------------- ### openAppSettings() ```typescript openAppSettings() => Promise ``` Open the Bluetooth settings on the device. Only available on Android and iOS. **Since:** 6.0.0 -------------------- ### openBluetoothSettings() ```typescript openBluetoothSettings() => Promise ``` Open the Bluetooth settings on the device. Only available on Android. **Since:** 6.0.0 -------------------- ### openLocationSettings() ```typescript openLocationSettings() => Promise ``` Open the location settings on the device. Only available on Android. **Since:** 6.0.0 -------------------- ### readCharacteristic(...) ```typescript readCharacteristic(options: ReadCharacteristicOptions) => Promise ``` Read the value of a characteristic. Only available on Android and iOS. | Param | Type | | ------------- | ------------------------------------------------------------------------------- | | **`options`** | ReadCharacteristicOptions | **Returns:** Promise<ReadCharacteristicResult> **Since:** 6.0.0 -------------------- ### readDescriptor(...) ```typescript readDescriptor(options: ReadDescriptorOptions) => Promise ``` Read the value of a descriptor. Only available on Android and iOS. | Param | Type | | ------------- | ----------------------------------------------------------------------- | | **`options`** | ReadDescriptorOptions | **Returns:** Promise<ReadDescriptorResult> **Since:** 6.0.0 -------------------- ### readRssi(...) ```typescript readRssi(options: ReadRssiOptions) => Promise ``` 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(...) ```typescript requestConnectionPriority(options: RequestConnectionPriorityOptions) => Promise ``` Request a connection priority. Only available on Android. | Param | Type | | ------------- | --------------------------------------------------------------------------------------------- | | **`options`** | RequestConnectionPriorityOptions | **Since:** 6.0.0 -------------------- ### requestMtu(...) ```typescript requestMtu(options: RequestMtuOptions) => Promise ``` Request an MTU size. Only available on Android. | Param | Type | | ------------- | --------------------------------------------------------------- | | **`options`** | RequestMtuOptions | **Since:** 6.0.0 -------------------- ### setCharacteristicValue(...) ```typescript setCharacteristicValue(options: SetCharacteristicValueOptions) => Promise ``` Set the value of a characteristic. Only available on Android and iOS. | Param | Type | | ------------- | --------------------------------------------------------------------------------------- | | **`options`** | SetCharacteristicValueOptions | **Since:** 7.2.0 -------------------- ### startAdvertising(...) ```typescript startAdvertising(options: StartAdvertisingOptions) => Promise ``` Start advertising as a BLE device. Only available on Android and iOS. | Param | Type | | ------------- | --------------------------------------------------------------------------- | | **`options`** | StartAdvertisingOptions | **Since:** 7.2.0 -------------------- ### startCharacteristicNotifications(...) ```typescript startCharacteristicNotifications(options: StartCharacteristicNotificationsOptions) => Promise ``` 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(...) ```typescript startForegroundService(options?: StartForegroundServiceOptions | undefined) => Promise ``` 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(...) ```typescript startScan(options?: StartScanOptions | undefined) => Promise ``` 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() ```typescript stopAdvertising() => Promise ``` Stop advertising as a BLE device. Only available on Android and iOS. **Since:** 7.2.0 -------------------- ### stopCharacteristicNotifications(...) ```typescript stopCharacteristicNotifications(options: StopCharacteristicNotificationsOptions) => Promise ``` Stop listening for characteristic value changes. Only available on Android and iOS. | Param | Type | | ------------- | --------------------------------------------------------------------------------------------------------- | | **`options`** | StopCharacteristicNotificationsOptions | **Since:** 6.0.0 -------------------- ### stopForegroundService() ```typescript stopForegroundService() => Promise ``` 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() ```typescript stopScan() => Promise ``` Stop scanning for BLE devices. Only available on Android and iOS. **Since:** 6.0.0 -------------------- ### writeCharacteristic(...) ```typescript writeCharacteristic(options: WriteCharacteristicOptions) => Promise ``` Write a value to a characteristic. Only available on Android and iOS. | Param | Type | | ------------- | --------------------------------------------------------------------------------- | | **`options`** | WriteCharacteristicOptions | **Since:** 6.0.0 -------------------- ### writeDescriptor(...) ```typescript writeDescriptor(options: WriteDescriptorOptions) => Promise ``` Write a value to a descriptor. Only available on Android and iOS. | Param | Type | | ------------- | ------------------------------------------------------------------------- | | **`options`** | WriteDescriptorOptions | **Since:** 6.0.0 -------------------- ### checkPermissions() ```typescript checkPermissions() => Promise ``` Check permissions for the plugin. Only available on Android. **Returns:** Promise<PermissionStatus> **Since:** 6.0.0 -------------------- ### requestPermissions(...) ```typescript requestPermissions(permissions?: BluetoothLowEnergyPluginPermission | undefined) => Promise ``` Request permissions for the plugin. Only available on Android. | Param | Type | | ----------------- | ------------------------------------------------------------------------------------------------- | | **`permissions`** | BluetoothLowEnergyPluginPermission | **Returns:** Promise<PermissionStatus> **Since:** 6.0.0 -------------------- ### addListener('characteristicChanged', ...) ```typescript addListener(eventName: 'characteristicChanged', listenerFunc: (event: CharacteristicChangedEvent) => void) => Promise ``` 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', ...) ```typescript addListener(eventName: 'characteristicWriteRequest', listenerFunc: (event: CharacteristicWriteRequestEvent) => void) => Promise ``` 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', ...) ```typescript addListener(eventName: 'deviceConnected', listenerFunc: (event: DeviceConnectedEvent) => void) => Promise ``` 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', ...) ```typescript addListener(eventName: 'deviceDisconnected', listenerFunc: (event: DeviceDisconnectedEvent) => void) => Promise ``` 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', ...) ```typescript addListener(eventName: 'deviceScanned', listenerFunc: (event: DeviceScannedEvent) => void) => Promise ``` 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() ```typescript removeAllListeners() => Promise ``` 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 'bluetooth' | 'bluetoothAdmin' | 'bluetoothAdvertise' | 'bluetoothConnect' | 'bluetoothScan' | 'location' | 'notifications' ### 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: ```ts import { BluetoothLowEnergyUtils } from '@capacitor-community/bluetooth-low-energy'; const convertBytesToHex = (bytes: number[]) => { return BluetoothLowEnergyUtils.convertBytesToHex({ bytes }); }; ``` See [docs/utils/README.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/bluetooth-low-energy/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](#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](#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](#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](https://capawesome.io/docs/sdks/capacitor/android-battery-optimization/): Manage battery optimization settings and request exemptions to keep background work running reliably. - [Android Foreground Service](https://capawesome.io/docs/sdks/capacitor/android-foreground-service/): Run a foreground service on Android. - [Network](https://capawesome.io/docs/sdks/capacitor/network/): Access network information such as connection status and type, and listen for network changes. - [NFC](https://capawesome.io/docs/sdks/capacitor/nfc/): Read, write, and emulate NFC tags with advanced features like HCE and raw command handling. - [Wi-Fi](https://capawesome.io/docs/sdks/capacitor/wifi/): Manage Wi-Fi connectivity, including adding, connecting, and disconnecting networks. ## Newsletter Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/bluetooth-low-energy/CHANGELOG.md). ## Breaking Changes See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/bluetooth-low-energy/BREAKING.md). ## License See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/bluetooth-low-energy/LICENSE). [^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Bluetooth SIG, Inc. or any of their affiliates or subsidiaries. [^2]: `Bluetooth` is a registered trademark of Bluetooth SIG, Inc.