--- description: Capacitor plugin for Bluetooth Low Energy (BLE) communication with advanced features like headless tasks, foreground services, and more. title: Capacitor Bluetooth Low Energy Plugin for Android & iOS - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/bluetooth-low-energy.png --- [Skip to content ](#capacitor-bluetooth-low-energy-plugin) [πŸ” Introducing the **Capacitor Vault** plugin β€” store secrets behind biometrics or a device passcode. ](/blog/announcing-the-capacitor-vault-plugin/) * [ SDKs ](/docs/sdks/) * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Enums ](#enums) * [ Utils ](#utils) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ Clipboard ](/docs/sdks/capacitor/clipboard/) * [ Cloudinary ](/docs/sdks/capacitor/cloudinary/) * [ Compass ](/docs/sdks/capacitor/compass/) * [ Contacts ](/docs/sdks/capacitor/contacts/) * [ Datetime Picker ](/docs/sdks/capacitor/datetime-picker/) * [ Device Info ](/docs/sdks/capacitor/device-info/) * [ Dialog ](/docs/sdks/capacitor/dialog/) * [ Exif ](/docs/sdks/capacitor/exif/) * [ Facebook Sign-In ](/docs/sdks/capacitor/facebook-sign-in/) * [ File Compressor ](/docs/sdks/capacitor/file-compressor/) * [ File Opener ](/docs/sdks/capacitor/file-opener/) * [ File Picker ](/docs/sdks/capacitor/file-picker/) * [ Firebase ](/docs/sdks/capacitor/firebase/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ iOS ](#ios) * [ Configuration ](#configuration) * [ Usage ](#usage) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Enums ](#enums) * [ Utils ](#utils) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) # Capacitor Bluetooth Low Energy Plugin[ΒΆ](#capacitor-bluetooth-low-energy-plugin "Permanent link") 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](#fn:1)[2](#fn:2) [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Features[ΒΆ](#features "Permanent link") 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. * 🦾 **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. * πŸ“¦ **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[ΒΆ](#use-cases "Permanent link") 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. ## Testimonials[ΒΆ](#testimonials "Permanent link") > 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[ΒΆ](#compatibility "Permanent link") | 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[ΒΆ](#demo "Permanent link") A working example can be found [here](https://github.com/capawesome-team/capacitor-heart-rate-monitor-app). | Android | iOS | | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | ![Android Demo](../../../assets/external/github.com/user-attachments/assets/c4cf7ddc-7f98-42e1-8334-34a26dfdf457.gif) | ![iOS Demo](../../../assets/external/github.com/user-attachments/assets/3cfac38f-22ef-4b8e-a439-529079926a4e.gif) | ## Guides[ΒΆ](#guides "Permanent link") * [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[ΒΆ](#installation "Permanent link") 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: `[](#%5F%5Fcodelineno-0-1)npm config set @capawesome-team:registry https://npm.registry.capawesome.io [](#%5F%5Fcodelineno-0-2)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: `[](#%5F%5Fcodelineno-1-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-2-1)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: `[](#%5F%5Fcodelineno-3-1)npm install @capawesome-team/capacitor-bluetooth-low-energy [](#%5F%5Fcodelineno-3-2)npx cap sync ` ### Android[ΒΆ](#android "Permanent link") #### Features[ΒΆ](#features%5F1 "Permanent link") Add the following element to your `AndroidManifest.xml` before or after the `application` tag: `[](#%5F%5Fcodelineno-4-1) ` 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[ΒΆ](#permissions "Permanent link") This API requires the following elements be added to your `AndroidManifest.xml` before or after the `application` tag: `[](#%5F%5Fcodelineno-5-1) [](#%5F%5Fcodelineno-5-2) [](#%5F%5Fcodelineno-5-3) [](#%5F%5Fcodelineno-5-4) [](#%5F%5Fcodelineno-5-5) [](#%5F%5Fcodelineno-5-6) [](#%5F%5Fcodelineno-5-7) [](#%5F%5Fcodelineno-5-8) [](#%5F%5Fcodelineno-5-9) [](#%5F%5Fcodelineno-5-10) [](#%5F%5Fcodelineno-5-11) [](#%5F%5Fcodelineno-5-12) [](#%5F%5Fcodelineno-5-13) [](#%5F%5Fcodelineno-5-14) ` You can read more about Bluetooth permissions in the [Android documentation](https://developer.android.com/develop/connectivity/bluetooth/bt-permissions). #### Services[ΒΆ](#services "Permanent link") You also need to add the following service **inside** the `application` tag in your `AndroidManifest.xml` (usually `android/app/src/main/AndroidManifest.xml`): `[](#%5F%5Fcodelineno-6-1) ` #### Headless Task[ΒΆ](#headless-task "Permanent link") 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: `[](#%5F%5Fcodelineno-7-1)import android.bluetooth.BluetoothGatt; [](#%5F%5Fcodelineno-7-2)import android.bluetooth.BluetoothGattCharacteristic; [](#%5F%5Fcodelineno-7-3)import android.bluetooth.BluetoothGattDescriptor; [](#%5F%5Fcodelineno-7-4)import androidx.annotation.NonNull; [](#%5F%5Fcodelineno-7-5) [](#%5F%5Fcodelineno-7-6)public class BluetoothLowEnergyHeadlessTask { [](#%5F%5Fcodelineno-7-7) public void onCharacteristicChanged(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic) { [](#%5F%5Fcodelineno-7-8) // Your code here [](#%5F%5Fcodelineno-7-9) } [](#%5F%5Fcodelineno-7-10) [](#%5F%5Fcodelineno-7-11) public void onCharacteristicChanged(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic, @NonNull byte[] value) { [](#%5F%5Fcodelineno-7-12) // Your code here [](#%5F%5Fcodelineno-7-13) } [](#%5F%5Fcodelineno-7-14) [](#%5F%5Fcodelineno-7-15) public void onCharacteristicRead(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic, int status) { [](#%5F%5Fcodelineno-7-16) // Your code here [](#%5F%5Fcodelineno-7-17) } [](#%5F%5Fcodelineno-7-18) [](#%5F%5Fcodelineno-7-19) public void onCharacteristicWrite(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic, int status) { [](#%5F%5Fcodelineno-7-20) // Your code here [](#%5F%5Fcodelineno-7-21) } [](#%5F%5Fcodelineno-7-22) [](#%5F%5Fcodelineno-7-23) public void onConnectionStateChange(@NonNull BluetoothGatt gatt, int status, int newState) { [](#%5F%5Fcodelineno-7-24) // Your code here [](#%5F%5Fcodelineno-7-25) } [](#%5F%5Fcodelineno-7-26) [](#%5F%5Fcodelineno-7-27) public void onDescriptorRead(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattDescriptor descriptor, int status, @NonNull byte[] value) { [](#%5F%5Fcodelineno-7-28) // Your code here [](#%5F%5Fcodelineno-7-29) } [](#%5F%5Fcodelineno-7-30) [](#%5F%5Fcodelineno-7-31) public void onDescriptorWrite(@NonNull BluetoothGatt gatt, @NonNull BluetoothGattDescriptor descriptor, int status) { [](#%5F%5Fcodelineno-7-32) // Your code here [](#%5F%5Fcodelineno-7-33) } [](#%5F%5Fcodelineno-7-34) [](#%5F%5Fcodelineno-7-35) public void onMtuChanged(@NonNull BluetoothGatt gatt, int mtu, int status) { [](#%5F%5Fcodelineno-7-36) // Your code here [](#%5F%5Fcodelineno-7-37) } [](#%5F%5Fcodelineno-7-38) [](#%5F%5Fcodelineno-7-39) public void onReadRemoteRssi(@NonNull BluetoothGatt gatt, int rssi, int status) { [](#%5F%5Fcodelineno-7-40) // Your code here [](#%5F%5Fcodelineno-7-41) } [](#%5F%5Fcodelineno-7-42) [](#%5F%5Fcodelineno-7-43) public void onServiceChanged(@NonNull BluetoothGatt gatt) { [](#%5F%5Fcodelineno-7-44) // Your code here [](#%5F%5Fcodelineno-7-45) } [](#%5F%5Fcodelineno-7-46) [](#%5F%5Fcodelineno-7-47) public void onServicesDiscovered(@NonNull BluetoothGatt gatt, int status) { [](#%5F%5Fcodelineno-7-48) // Your code here [](#%5F%5Fcodelineno-7-49) } [](#%5F%5Fcodelineno-7-50)} ` #### Proguard[ΒΆ](#proguard "Permanent link") If you are using Proguard, you need to add the following rules to your `proguard-rules.pro` file: `[](#%5F%5Fcodelineno-8-1)-keep class io.capawesome.capacitorjs.plugins.** { *; } ` ### iOS[ΒΆ](#ios "Permanent link") #### Privacy Descriptions[ΒΆ](#privacy-descriptions "Permanent link") 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: `[](#%5F%5Fcodelineno-9-1)NSBluetoothAlwaysUsageDescription [](#%5F%5Fcodelineno-9-2)The app needs access to Bluetooth peripherals to communicate with Bluetooth devices. ` #### Capabilities[ΒΆ](#capabilities "Permanent link") 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[ΒΆ](#configuration "Permanent link") No configuration required for this plugin. ## Usage[ΒΆ](#usage "Permanent link") 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 "Permanent link") Initialize the plugin in the central or peripheral role and check whether Bluetooth Low Energy is available and enabled on the device: `[](#%5F%5Fcodelineno-10-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-10-2) [](#%5F%5Fcodelineno-10-3)const initialize = async () => { [](#%5F%5Fcodelineno-10-4) await BluetoothLowEnergy.initialize({ mode: 'central' }); [](#%5F%5Fcodelineno-10-5)}; [](#%5F%5Fcodelineno-10-6) [](#%5F%5Fcodelineno-10-7)const isAvailable = async () => { [](#%5F%5Fcodelineno-10-8) const result = await BluetoothLowEnergy.isAvailable(); [](#%5F%5Fcodelineno-10-9) return result.isAvailable; [](#%5F%5Fcodelineno-10-10)}; [](#%5F%5Fcodelineno-10-11) [](#%5F%5Fcodelineno-10-12)const isEnabled = async () => { [](#%5F%5Fcodelineno-10-13) const result = await BluetoothLowEnergy.isEnabled(); [](#%5F%5Fcodelineno-10-14) return result.enabled; [](#%5F%5Fcodelineno-10-15)}; ` ### Check and request permissions[ΒΆ](#check-and-request-permissions "Permanent link") Check and request the required Bluetooth permissions. Only available on Android: `[](#%5F%5Fcodelineno-11-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-11-2) [](#%5F%5Fcodelineno-11-3)const checkPermissions = async () => { [](#%5F%5Fcodelineno-11-4) const result = await BluetoothLowEnergy.checkPermissions(); [](#%5F%5Fcodelineno-11-5) return result; [](#%5F%5Fcodelineno-11-6)}; [](#%5F%5Fcodelineno-11-7) [](#%5F%5Fcodelineno-11-8)const requestPermissions = async () => { [](#%5F%5Fcodelineno-11-9) const result = await BluetoothLowEnergy.requestPermissions(); [](#%5F%5Fcodelineno-11-10) return result; [](#%5F%5Fcodelineno-11-11)}; ` ### Scan for devices[ΒΆ](#scan-for-devices "Permanent link") Start and stop scanning for nearby BLE devices. Scanned devices are delivered via the `deviceScanned` event (see [Listen for events](#listen-for-events)): `[](#%5F%5Fcodelineno-12-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-12-2) [](#%5F%5Fcodelineno-12-3)const startScan = async () => { [](#%5F%5Fcodelineno-12-4) await BluetoothLowEnergy.startScan(); [](#%5F%5Fcodelineno-12-5)}; [](#%5F%5Fcodelineno-12-6) [](#%5F%5Fcodelineno-12-7)const stopScan = async () => { [](#%5F%5Fcodelineno-12-8) await BluetoothLowEnergy.stopScan(); [](#%5F%5Fcodelineno-12-9)}; ` ### Connect to a device[ΒΆ](#connect-to-a-device "Permanent link") Connect to a BLE device by its ID, disconnect from it, and retrieve the currently connected devices: `[](#%5F%5Fcodelineno-13-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-13-2) [](#%5F%5Fcodelineno-13-3)const connect = async () => { [](#%5F%5Fcodelineno-13-4) await BluetoothLowEnergy.connect({ deviceId: '00:00:00:00:00:00' }); [](#%5F%5Fcodelineno-13-5)}; [](#%5F%5Fcodelineno-13-6) [](#%5F%5Fcodelineno-13-7)const disconnect = async () => { [](#%5F%5Fcodelineno-13-8) await BluetoothLowEnergy.disconnect({ deviceId: '00:00:00:00:00:00' }); [](#%5F%5Fcodelineno-13-9)}; [](#%5F%5Fcodelineno-13-10) [](#%5F%5Fcodelineno-13-11)const getConnectedDevices = async () => { [](#%5F%5Fcodelineno-13-12) const result = await BluetoothLowEnergy.getConnectedDevices(); [](#%5F%5Fcodelineno-13-13) return result.devices; [](#%5F%5Fcodelineno-13-14)}; ` ### Bond with a device[ΒΆ](#bond-with-a-device "Permanent link") Create a bond with a BLE device and check whether a device is already bonded. Only available on Android: `[](#%5F%5Fcodelineno-14-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-14-2) [](#%5F%5Fcodelineno-14-3)const createBond = async () => { [](#%5F%5Fcodelineno-14-4) await BluetoothLowEnergy.createBond({ deviceId: '00:00:00:00:00:00' }); [](#%5F%5Fcodelineno-14-5)}; [](#%5F%5Fcodelineno-14-6) [](#%5F%5Fcodelineno-14-7)const isBonded = async () => { [](#%5F%5Fcodelineno-14-8) const result = await BluetoothLowEnergy.isBonded({ deviceId: '00:00:00:00:00:00' }); [](#%5F%5Fcodelineno-14-9) return result.bonded; [](#%5F%5Fcodelineno-14-10)}; ` ### Discover services[ΒΆ](#discover-services "Permanent link") Discover the services of a connected device and retrieve them along with their characteristics and descriptors: `[](#%5F%5Fcodelineno-15-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-15-2) [](#%5F%5Fcodelineno-15-3)const discoverServices = async () => { [](#%5F%5Fcodelineno-15-4) await BluetoothLowEnergy.discoverServices({ deviceId: '00:00:00:00:00:00' }); [](#%5F%5Fcodelineno-15-5)}; [](#%5F%5Fcodelineno-15-6) [](#%5F%5Fcodelineno-15-7)const getServices = async () => { [](#%5F%5Fcodelineno-15-8) const result = await BluetoothLowEnergy.getServices({ deviceId: '00:00:00:00:00:00' }); [](#%5F%5Fcodelineno-15-9) return result.services; [](#%5F%5Fcodelineno-15-10)}; ` ### Read and write characteristics[ΒΆ](#read-and-write-characteristics "Permanent link") Read the value of a characteristic or write a new value to it: `[](#%5F%5Fcodelineno-16-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-16-2) [](#%5F%5Fcodelineno-16-3)const readCharacteristic = async () => { [](#%5F%5Fcodelineno-16-4) const result = await BluetoothLowEnergy.readCharacteristic({ [](#%5F%5Fcodelineno-16-5) characteristicId: '00002a00-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-16-6) deviceId: '00:00:00:00:00:00', [](#%5F%5Fcodelineno-16-7) serviceId: '00001800-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-16-8) }); [](#%5F%5Fcodelineno-16-9) return result.value; [](#%5F%5Fcodelineno-16-10)}; [](#%5F%5Fcodelineno-16-11) [](#%5F%5Fcodelineno-16-12)const writeCharacteristic = async () => { [](#%5F%5Fcodelineno-16-13) await BluetoothLowEnergy.writeCharacteristic({ [](#%5F%5Fcodelineno-16-14) characteristicId: '00002a00-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-16-15) deviceId: '00:00:00:00:00:00', [](#%5F%5Fcodelineno-16-16) serviceId: '00001800-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-16-17) value: [1, 2, 3], [](#%5F%5Fcodelineno-16-18) }); [](#%5F%5Fcodelineno-16-19)}; ` ### Read and write descriptors[ΒΆ](#read-and-write-descriptors "Permanent link") Read the value of a descriptor or write a new value to it: `[](#%5F%5Fcodelineno-17-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-17-2) [](#%5F%5Fcodelineno-17-3)const readDescriptor = async () => { [](#%5F%5Fcodelineno-17-4) const result = await BluetoothLowEnergy.readDescriptor({ [](#%5F%5Fcodelineno-17-5) characteristicId: '00002a00-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-17-6) descriptorId: '00002902-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-17-7) deviceId: '00:00:00:00:00:00', [](#%5F%5Fcodelineno-17-8) serviceId: '00001800-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-17-9) }); [](#%5F%5Fcodelineno-17-10) return result.value; [](#%5F%5Fcodelineno-17-11)}; [](#%5F%5Fcodelineno-17-12) [](#%5F%5Fcodelineno-17-13)const writeDescriptor = async () => { [](#%5F%5Fcodelineno-17-14) await BluetoothLowEnergy.writeDescriptor({ [](#%5F%5Fcodelineno-17-15) characteristicId: '00002a00-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-17-16) descriptorId: '00002902-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-17-17) deviceId: '00:00:00:00:00:00', [](#%5F%5Fcodelineno-17-18) serviceId: '00001800-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-17-19) value: [1, 2, 3], [](#%5F%5Fcodelineno-17-20) }); [](#%5F%5Fcodelineno-17-21)}; ` ### Receive characteristic notifications[ΒΆ](#receive-characteristic-notifications "Permanent link") 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)): `[](#%5F%5Fcodelineno-18-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-18-2) [](#%5F%5Fcodelineno-18-3)const startCharacteristicNotifications = async () => { [](#%5F%5Fcodelineno-18-4) await BluetoothLowEnergy.startCharacteristicNotifications({ [](#%5F%5Fcodelineno-18-5) characteristicId: '00002a00-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-18-6) deviceId: '00:00:00:00:00:00', [](#%5F%5Fcodelineno-18-7) serviceId: '00001800-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-18-8) }); [](#%5F%5Fcodelineno-18-9)}; [](#%5F%5Fcodelineno-18-10) [](#%5F%5Fcodelineno-18-11)const stopCharacteristicNotifications = async () => { [](#%5F%5Fcodelineno-18-12) await BluetoothLowEnergy.stopCharacteristicNotifications({ [](#%5F%5Fcodelineno-18-13) characteristicId: '00002a00-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-18-14) deviceId: '00:00:00:00:00:00', [](#%5F%5Fcodelineno-18-15) serviceId: '00001800-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-18-16) }); [](#%5F%5Fcodelineno-18-17)}; ` ### Tune the connection[ΒΆ](#tune-the-connection "Permanent link") 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): `[](#%5F%5Fcodelineno-19-1)import { BluetoothLowEnergy, ConnectionPriority } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-19-2) [](#%5F%5Fcodelineno-19-3)const readRssi = async () => { [](#%5F%5Fcodelineno-19-4) const result = await BluetoothLowEnergy.readRssi({ deviceId: '00:00:00:00:00:00' }); [](#%5F%5Fcodelineno-19-5) return result.rssi; [](#%5F%5Fcodelineno-19-6)}; [](#%5F%5Fcodelineno-19-7) [](#%5F%5Fcodelineno-19-8)const requestConnectionPriority = async () => { [](#%5F%5Fcodelineno-19-9) await BluetoothLowEnergy.requestConnectionPriority({ [](#%5F%5Fcodelineno-19-10) connectionPriority: ConnectionPriority.BALANCED, [](#%5F%5Fcodelineno-19-11) deviceId: '00:00:00:00:00:00', [](#%5F%5Fcodelineno-19-12) }); [](#%5F%5Fcodelineno-19-13)}; [](#%5F%5Fcodelineno-19-14) [](#%5F%5Fcodelineno-19-15)const requestMtu = async () => { [](#%5F%5Fcodelineno-19-16) await BluetoothLowEnergy.requestMtu({ [](#%5F%5Fcodelineno-19-17) deviceId: '00:00:00:00:00:00', [](#%5F%5Fcodelineno-19-18) mtu: 512, [](#%5F%5Fcodelineno-19-19) }); [](#%5F%5Fcodelineno-19-20)}; ` ### Act as a peripheral[ΒΆ](#act-as-a-peripheral "Permanent link") 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): `[](#%5F%5Fcodelineno-20-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-20-2) [](#%5F%5Fcodelineno-20-3)const startAdvertising = async () => { [](#%5F%5Fcodelineno-20-4) await BluetoothLowEnergy.startAdvertising({ [](#%5F%5Fcodelineno-20-5) manufacturerData: { [](#%5F%5Fcodelineno-20-6) 0xffff: [1, 2, 3] [](#%5F%5Fcodelineno-20-7) }, [](#%5F%5Fcodelineno-20-8) name: 'MyDevice', [](#%5F%5Fcodelineno-20-9) services: [ [](#%5F%5Fcodelineno-20-10) { [](#%5F%5Fcodelineno-20-11) id: '0000180A-0000-1000-8000-00805F9B34FB', [](#%5F%5Fcodelineno-20-12) characteristics: [ [](#%5F%5Fcodelineno-20-13) { [](#%5F%5Fcodelineno-20-14) id: '00002A29-0000-1000-8000-00805F9B34FB', [](#%5F%5Fcodelineno-20-15) descriptors: [], // Descriptors are ignored for now [](#%5F%5Fcodelineno-20-16) permissions: { [](#%5F%5Fcodelineno-20-17) read: true, [](#%5F%5Fcodelineno-20-18) write: true, [](#%5F%5Fcodelineno-20-19) }, [](#%5F%5Fcodelineno-20-20) properties: { [](#%5F%5Fcodelineno-20-21) read: true, [](#%5F%5Fcodelineno-20-22) write: true, [](#%5F%5Fcodelineno-20-23) notify: true, [](#%5F%5Fcodelineno-20-24) indicate: true, [](#%5F%5Fcodelineno-20-25) }, [](#%5F%5Fcodelineno-20-26) }, [](#%5F%5Fcodelineno-20-27) ], [](#%5F%5Fcodelineno-20-28) }, [](#%5F%5Fcodelineno-20-29) ], [](#%5F%5Fcodelineno-20-30) }); [](#%5F%5Fcodelineno-20-31)}; [](#%5F%5Fcodelineno-20-32) [](#%5F%5Fcodelineno-20-33)const setCharacteristicValue = async () => { [](#%5F%5Fcodelineno-20-34) await BluetoothLowEnergy.setCharacteristicValue({ [](#%5F%5Fcodelineno-20-35) characteristicId: '00002a00-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-20-36) serviceId: '00001800-0000-1000-8000-00805f9b34fb', [](#%5F%5Fcodelineno-20-37) value: [1, 2, 3], [](#%5F%5Fcodelineno-20-38) }); [](#%5F%5Fcodelineno-20-39)}; [](#%5F%5Fcodelineno-20-40) [](#%5F%5Fcodelineno-20-41)const stopAdvertising = async () => { [](#%5F%5Fcodelineno-20-42) await BluetoothLowEnergy.stopAdvertising(); [](#%5F%5Fcodelineno-20-43)}; ` ### Keep the connection alive in the background[ΒΆ](#keep-the-connection-alive-in-the-background "Permanent link") 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): `[](#%5F%5Fcodelineno-21-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-21-2) [](#%5F%5Fcodelineno-21-3)const startForegroundService = async () => { [](#%5F%5Fcodelineno-21-4) await BluetoothLowEnergy.startForegroundService({ [](#%5F%5Fcodelineno-21-5) body: 'Body', [](#%5F%5Fcodelineno-21-6) id: 1, [](#%5F%5Fcodelineno-21-7) smallIcon: 'smallIcon', [](#%5F%5Fcodelineno-21-8) title: 'Title', [](#%5F%5Fcodelineno-21-9) }); [](#%5F%5Fcodelineno-21-10)}; [](#%5F%5Fcodelineno-21-11) [](#%5F%5Fcodelineno-21-12)const stopForegroundService = async () => { [](#%5F%5Fcodelineno-21-13) await BluetoothLowEnergy.stopForegroundService(); [](#%5F%5Fcodelineno-21-14)}; ` ### Open system settings[ΒΆ](#open-system-settings "Permanent link") 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: `[](#%5F%5Fcodelineno-22-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-22-2) [](#%5F%5Fcodelineno-22-3)const openAppSettings = async () => { [](#%5F%5Fcodelineno-22-4) await BluetoothLowEnergy.openAppSettings(); [](#%5F%5Fcodelineno-22-5)}; [](#%5F%5Fcodelineno-22-6) [](#%5F%5Fcodelineno-22-7)const openBluetoothSettings = async () => { [](#%5F%5Fcodelineno-22-8) await BluetoothLowEnergy.openBluetoothSettings(); [](#%5F%5Fcodelineno-22-9)}; [](#%5F%5Fcodelineno-22-10) [](#%5F%5Fcodelineno-22-11)const openLocationSettings = async () => { [](#%5F%5Fcodelineno-22-12) await BluetoothLowEnergy.openLocationSettings(); [](#%5F%5Fcodelineno-22-13)}; ` ### Listen for events[ΒΆ](#listen-for-events "Permanent link") 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: `[](#%5F%5Fcodelineno-23-1)import { BluetoothLowEnergy } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-23-2) [](#%5F%5Fcodelineno-23-3)const addListener = () => { [](#%5F%5Fcodelineno-23-4) BluetoothLowEnergy.addListener('characteristicChanged', (event) => { [](#%5F%5Fcodelineno-23-5) console.log('Characteristic changed', event); [](#%5F%5Fcodelineno-23-6) }); [](#%5F%5Fcodelineno-23-7) [](#%5F%5Fcodelineno-23-8) BluetoothLowEnergy.addListener('characteristicWriteRequest', async (event) => { [](#%5F%5Fcodelineno-23-9) console.log('Characteristic write request', event); [](#%5F%5Fcodelineno-23-10) }); [](#%5F%5Fcodelineno-23-11) [](#%5F%5Fcodelineno-23-12) BluetoothLowEnergy.addListener('deviceConnected', (event) => { [](#%5F%5Fcodelineno-23-13) console.log('Device connected', event); [](#%5F%5Fcodelineno-23-14) }); [](#%5F%5Fcodelineno-23-15) [](#%5F%5Fcodelineno-23-16) BluetoothLowEnergy.addListener('deviceDisconnected', (event) => { [](#%5F%5Fcodelineno-23-17) console.log('Device disconnected', event); [](#%5F%5Fcodelineno-23-18) }); [](#%5F%5Fcodelineno-23-19) [](#%5F%5Fcodelineno-23-20) BluetoothLowEnergy.addListener('deviceScanned', (event) => { [](#%5F%5Fcodelineno-23-21) console.log('Device scanned', event); [](#%5F%5Fcodelineno-23-22) }); [](#%5F%5Fcodelineno-23-23)}; [](#%5F%5Fcodelineno-23-24) [](#%5F%5Fcodelineno-23-25)const removeAllListeners = () => { [](#%5F%5Fcodelineno-23-26) BluetoothLowEnergy.removeAllListeners(); [](#%5F%5Fcodelineno-23-27)}; ` ### Convert byte arrays[ΒΆ](#convert-byte-arrays "Permanent link") Use the `BluetoothLowEnergyUtils` class to convert byte arrays to hexadecimal strings (see [Utils](#utils) for more information): `[](#%5F%5Fcodelineno-24-1)import { BluetoothLowEnergyUtils } from '@capawesome-team/capacitor-bluetooth-low-energy'; [](#%5F%5Fcodelineno-24-2) [](#%5F%5Fcodelineno-24-3)const convertBytesToHex = (bytes: number[]) => { [](#%5F%5Fcodelineno-24-4) return BluetoothLowEnergyUtils.convertBytesToHex({ bytes }); [](#%5F%5Fcodelineno-24-5)}; ` ## API[ΒΆ](#api "Permanent link") * [connect(...)](#connect) * [createBond(...)](#createbond) * [disconnect(...)](#disconnect) * [discoverServices(...)](#discoverservices) * [getConnectedDevices()](#getconnecteddevices) * [getServices(...)](#getservices) * [initialize(...)](#initialize) * [isAvailable()](#isavailable) * [isBonded(...)](#isbonded) * [isEnabled()](#isenabled) * [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(...)[ΒΆ](#connect "Permanent link") `[](#%5F%5Fcodelineno-25-1)connect(options: ConnectOptions) => Promise ` Connect to a BLE device. Only available on Android and iOS. | Param | Type | | ----------- | --------------------------------- | | **options** | [ConnectOptions](#connectoptions) | **Since:** 6.0.0 --- ### createBond(...)[ΒΆ](#createbond "Permanent link") `[](#%5F%5Fcodelineno-26-1)createBond(options: CreateBondOptions) => Promise ` Create a bond with the BLE device. Only available on Android. | Param | Type | | ----------- | --------------------------------------- | | **options** | [CreateBondOptions](#createbondoptions) | **Since:** 6.0.0 --- ### disconnect(...)[ΒΆ](#disconnect "Permanent link") `[](#%5F%5Fcodelineno-27-1)disconnect(options: DisconnectOptions) => Promise ` Disconnect from the BLE device. Only available on Android and iOS. | Param | Type | | ----------- | --------------------------------------- | | **options** | [DisconnectOptions](#disconnectoptions) | **Since:** 6.0.0 --- ### discoverServices(...)[ΒΆ](#discoverservices "Permanent link") `[](#%5F%5Fcodelineno-28-1)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](#discoverserviceoptions) | **Since:** 6.0.0 --- ### getConnectedDevices()[ΒΆ](#getconnecteddevices "Permanent link") `[](#%5F%5Fcodelineno-29-1)getConnectedDevices() => Promise ` Get a list of connected devices. Only available on Android and iOS. **Returns:** `Promise<[GetConnectedDevicesResult](#getconnecteddevicesresult)>` **Since:** 6.0.0 --- ### getServices(...)[ΒΆ](#getservices "Permanent link") `[](#%5F%5Fcodelineno-30-1)getServices(options: GetServicesOptions) => Promise ` Get a list of services provided by the device. Only available on Android and iOS. | Param | Type | | ----------- | ----------------------------------------- | | **options** | [GetServicesOptions](#getservicesoptions) | **Returns:** `Promise<[GetServicesResult](#getservicesresult)>` **Since:** 6.0.0 --- ### initialize(...)[ΒΆ](#initialize "Permanent link") `[](#%5F%5Fcodelineno-31-1)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](#initializeoptions) | **Since:** 6.0.0 --- ### isAvailable()[ΒΆ](#isavailable "Permanent link") `[](#%5F%5Fcodelineno-32-1)isAvailable() => Promise ` Check whether or not Bluetooth Low Energy is available on the device. **Returns:** `Promise<[IsAvailableResult](#isavailableresult)>` **Since:** 7.3.0 --- ### isBonded(...)[ΒΆ](#isbonded "Permanent link") `[](#%5F%5Fcodelineno-33-1)isBonded(options: IsBondedOptions) => Promise ` Check if the device is bonded. Only available on Android. | Param | Type | | ----------- | ----------------------------------- | | **options** | [IsBondedOptions](#isbondedoptions) | **Returns:** `Promise<[IsBondedResult](#isbondedresult)>` **Since:** 6.0.0 --- ### isEnabled()[ΒΆ](#isenabled "Permanent link") `[](#%5F%5Fcodelineno-34-1)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](#isenabledresult)>` **Since:** 6.0.0 --- ### isLocationEnabled()[ΒΆ](#islocationenabled "Permanent link") `[](#%5F%5Fcodelineno-35-1)isLocationEnabled() => Promise ` Check if location services are enabled. Only available on Android. **Returns:** `Promise<[IsLocationEnabledResult](#islocationenabledresult)>` **Since:** 7.7.0 --- ### openAppSettings()[ΒΆ](#openappsettings "Permanent link") `[](#%5F%5Fcodelineno-36-1)openAppSettings() => Promise ` Open the Bluetooth settings on the device. Only available on Android and iOS. **Since:** 6.0.0 --- ### openBluetoothSettings()[ΒΆ](#openbluetoothsettings "Permanent link") `[](#%5F%5Fcodelineno-37-1)openBluetoothSettings() => Promise ` Open the Bluetooth settings on the device. Only available on Android. **Since:** 6.0.0 --- ### openLocationSettings()[ΒΆ](#openlocationsettings "Permanent link") `[](#%5F%5Fcodelineno-38-1)openLocationSettings() => Promise ` Open the location settings on the device. Only available on Android. **Since:** 6.0.0 --- ### readCharacteristic(...)[ΒΆ](#readcharacteristic "Permanent link") `[](#%5F%5Fcodelineno-39-1)readCharacteristic(options: ReadCharacteristicOptions) => Promise ` Read the value of a characteristic. Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------------------------------- | | **options** | [ReadCharacteristicOptions](#readcharacteristicoptions) | **Returns:** `Promise<[ReadCharacteristicResult](#readcharacteristicresult)>` **Since:** 6.0.0 --- ### readDescriptor(...)[ΒΆ](#readdescriptor "Permanent link") `[](#%5F%5Fcodelineno-40-1)readDescriptor(options: ReadDescriptorOptions) => Promise ` Read the value of a descriptor. Only available on Android and iOS. | Param | Type | | ----------- | ----------------------------------------------- | | **options** | [ReadDescriptorOptions](#readdescriptoroptions) | **Returns:** `Promise<[ReadDescriptorResult](#readdescriptorresult)>` **Since:** 6.0.0 --- ### readRssi(...)[ΒΆ](#readrssi "Permanent link") `[](#%5F%5Fcodelineno-41-1)readRssi(options: ReadRssiOptions) => Promise ` Read the RSSI value of the device. Only available on Android and iOS. | Param | Type | | ----------- | ----------------------------------- | | **options** | [ReadRssiOptions](#readrssioptions) | **Returns:** `Promise<[ReadRssiResult](#readrssiresult)>` **Since:** 6.0.0 --- ### requestConnectionPriority(...)[ΒΆ](#requestconnectionpriority "Permanent link") `[](#%5F%5Fcodelineno-42-1)requestConnectionPriority(options: RequestConnectionPriorityOptions) => Promise ` Request a connection priority. Only available on Android. | Param | Type | | ----------- | --------------------------------------------------------------------- | | **options** | [RequestConnectionPriorityOptions](#requestconnectionpriorityoptions) | **Since:** 6.0.0 --- ### requestMtu(...)[ΒΆ](#requestmtu "Permanent link") `[](#%5F%5Fcodelineno-43-1)requestMtu(options: RequestMtuOptions) => Promise ` Request an MTU size. Only available on Android. | Param | Type | | ----------- | --------------------------------------- | | **options** | [RequestMtuOptions](#requestmtuoptions) | **Since:** 6.0.0 --- ### setCharacteristicValue(...)[ΒΆ](#setcharacteristicvalue "Permanent link") `[](#%5F%5Fcodelineno-44-1)setCharacteristicValue(options: SetCharacteristicValueOptions) => Promise ` Set the value of a characteristic. Only available on Android. | Param | Type | | ----------- | --------------------------------------------------------------- | | **options** | [SetCharacteristicValueOptions](#setcharacteristicvalueoptions) | **Since:** 7.2.0 --- ### startAdvertising(...)[ΒΆ](#startadvertising "Permanent link") `[](#%5F%5Fcodelineno-45-1)startAdvertising(options: StartAdvertisingOptions) => Promise ` Start advertising as a BLE device. Only available on Android and iOS. | Param | Type | | ----------- | --------------------------------------------------- | | **options** | [StartAdvertisingOptions](#startadvertisingoptions) | **Since:** 7.2.0 --- ### startCharacteristicNotifications(...)[ΒΆ](#startcharacteristicnotifications "Permanent link") `[](#%5F%5Fcodelineno-46-1)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](#startcharacteristicnotificationsoptions) | **Since:** 6.0.0 --- ### startForegroundService(...)[ΒΆ](#startforegroundservice "Permanent link") `[](#%5F%5Fcodelineno-47-1)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](#startforegroundserviceoptions) | **Since:** 6.0.0 --- ### startScan(...)[ΒΆ](#startscan "Permanent link") `[](#%5F%5Fcodelineno-48-1)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](#startscanoptions) | **Since:** 6.0.0 --- ### stopAdvertising()[ΒΆ](#stopadvertising "Permanent link") `[](#%5F%5Fcodelineno-49-1)stopAdvertising() => Promise ` Stop advertising as a BLE device. Only available on Android and iOS. **Since:** 7.2.0 --- ### stopCharacteristicNotifications(...)[ΒΆ](#stopcharacteristicnotifications "Permanent link") `[](#%5F%5Fcodelineno-50-1)stopCharacteristicNotifications(options: StopCharacteristicNotificationsOptions) => Promise ` Stop listening for characteristic value changes. Only available on Android and iOS. | Param | Type | | ----------- | --------------------------------------------------------------------------------- | | **options** | [StopCharacteristicNotificationsOptions](#stopcharacteristicnotificationsoptions) | **Since:** 6.0.0 --- ### stopForegroundService()[ΒΆ](#stopforegroundservice "Permanent link") `[](#%5F%5Fcodelineno-51-1)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()[ΒΆ](#stopscan "Permanent link") `[](#%5F%5Fcodelineno-52-1)stopScan() => Promise ` Stop scanning for BLE devices. Only available on Android and iOS. **Since:** 6.0.0 --- ### writeCharacteristic(...)[ΒΆ](#writecharacteristic "Permanent link") `[](#%5F%5Fcodelineno-53-1)writeCharacteristic(options: WriteCharacteristicOptions) => Promise ` Write a value to a characteristic. Only available on Android and iOS. | Param | Type | | ----------- | --------------------------------------------------------- | | **options** | [WriteCharacteristicOptions](#writecharacteristicoptions) | **Since:** 6.0.0 --- ### writeDescriptor(...)[ΒΆ](#writedescriptor "Permanent link") `[](#%5F%5Fcodelineno-54-1)writeDescriptor(options: WriteDescriptorOptions) => Promise ` Write a value to a descriptor. Only available on Android and iOS. | Param | Type | | ----------- | ------------------------------------------------- | | **options** | [WriteDescriptorOptions](#writedescriptoroptions) | **Since:** 6.0.0 --- ### checkPermissions()[ΒΆ](#checkpermissions "Permanent link") `[](#%5F%5Fcodelineno-55-1)checkPermissions() => Promise ` Check permissions for the plugin. Only available on Android. **Returns:** `Promise<[PermissionStatus](#permissionstatus)>` **Since:** 6.0.0 --- ### requestPermissions(...)[ΒΆ](#requestpermissions "Permanent link") `[](#%5F%5Fcodelineno-56-1)requestPermissions(permissions?: BluetoothLowEnergyPluginPermission | undefined) => Promise ` Request permissions for the plugin. Only available on Android. | Param | Type | | --------------- | ------------------------------------------------------------------------- | | **permissions** | [BluetoothLowEnergyPluginPermission](#bluetoothlowenergypluginpermission) | **Returns:** `Promise<[PermissionStatus](#permissionstatus)>` **Since:** 6.0.0 --- ### addListener('characteristicChanged', ...)[ΒΆ](#addlistenercharacteristicchanged "Permanent link") `[](#%5F%5Fcodelineno-57-1)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](#characteristicchangedevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 6.0.0 --- ### addListener('characteristicWriteRequest', ...)[ΒΆ](#addlistenercharacteristicwriterequest "Permanent link") `[](#%5F%5Fcodelineno-58-1)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](#characteristicwriterequestevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 7.2.0 --- ### addListener('deviceConnected', ...)[ΒΆ](#addlistenerdeviceconnected "Permanent link") `[](#%5F%5Fcodelineno-59-1)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](#deviceconnectedevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 7.1.0 --- ### addListener('deviceDisconnected', ...)[ΒΆ](#addlistenerdevicedisconnected "Permanent link") `[](#%5F%5Fcodelineno-60-1)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](#devicedisconnectedevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 6.0.0 --- ### addListener('deviceScanned', ...)[ΒΆ](#addlistenerdevicescanned "Permanent link") `[](#%5F%5Fcodelineno-61-1)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](#devicescannedevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 6.0.0 --- ### removeAllListeners()[ΒΆ](#removealllisteners "Permanent link") `[](#%5F%5Fcodelineno-62-1)removeAllListeners() => Promise ` Remove all listeners for this plugin. **Since:** 6.0.0 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### ConnectOptions[ΒΆ](#connectoptions "Permanent link") | 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[ΒΆ](#createbondoptions "Permanent link") | 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[ΒΆ](#disconnectoptions "Permanent link") | 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[ΒΆ](#discoverserviceoptions "Permanent link") | 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[ΒΆ](#getconnecteddevicesresult "Permanent link") | Prop | Type | Description | Since | | ----------- | ---------- | ------------------------------ | ----- | | **devices** | Device\[\] | An array of connected devices. | 6.0.0 | #### Device[ΒΆ](#device "Permanent link") | 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[ΒΆ](#getservicesresult "Permanent link") | Prop | Type | Description | Since | | ------------ | ----------- | -------------------------------------------- | ----- | | **services** | Service\[\] | An array of services provided by the device. | 6.0.0 | #### Service[ΒΆ](#service "Permanent link") | 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[ΒΆ](#characteristic "Permanent link") | 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](#characteristicpermissions) | The permissions of the characteristic. Only available on Android. | 7.2.0 | | **properties** | [CharacteristicProperties](#characteristicproperties) | The properties of the characteristic. | 6.0.0 | #### Descriptor[ΒΆ](#descriptor "Permanent link") | Prop | Type | Description | Since | | ------ | ------ | --------------------------- | ----- | | **id** | string | The UUID of the descriptor. | 6.0.0 | #### CharacteristicPermissions[ΒΆ](#characteristicpermissions "Permanent link") | 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[ΒΆ](#characteristicproperties "Permanent link") | 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[ΒΆ](#getservicesoptions "Permanent link") | 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[ΒΆ](#initializeoptions "Permanent link") | 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[ΒΆ](#isavailableresult "Permanent link") | Prop | Type | Description | Since | | --------------- | ------- | --------------------------------------------------------------- | ----- | | **isAvailable** | boolean | Whether or not Bluetooth Low Energy is available on the device. | 7.3.0 | #### IsBondedResult[ΒΆ](#isbondedresult "Permanent link") | Prop | Type | Description | Since | | ---------- | ------- | ------------------------------------ | ----- | | **bonded** | boolean | Whether or not the device is bonded. | 6.0.0 | #### IsBondedOptions[ΒΆ](#isbondedoptions "Permanent link") | 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[ΒΆ](#isenabledresult "Permanent link") | Prop | Type | Description | Since | | ----------- | ------- | ------------------------------------ | ----- | | **enabled** | boolean | Whether or not Bluetooth is enabled. | 6.0.0 | #### IsLocationEnabledResult[ΒΆ](#islocationenabledresult "Permanent link") | Prop | Type | Description | Since | | ----------- | ------- | --------------------------------------------- | ----- | | **enabled** | boolean | Whether or not location services are enabled. | 7.7.0 | #### ReadCharacteristicResult[ΒΆ](#readcharacteristicresult "Permanent link") | Prop | Type | Description | Since | | --------- | ---------- | -------------------------------------- | ----- | | **value** | number\[\] | The value bytes of the characteristic. | 6.0.0 | #### ReadCharacteristicOptions[ΒΆ](#readcharacteristicoptions "Permanent link") | 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[ΒΆ](#readdescriptorresult "Permanent link") | Prop | Type | Description | Since | | --------- | ---------- | ---------------------------------- | ----- | | **value** | number\[\] | The value bytes of the descriptor. | 6.0.0 | #### ReadDescriptorOptions[ΒΆ](#readdescriptoroptions "Permanent link") | 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[ΒΆ](#readrssiresult "Permanent link") | Prop | Type | Description | Since | | -------- | ------ | --------------- | ----- | | **rssi** | number | The RSSI value. | 6.0.0 | #### ReadRssiOptions[ΒΆ](#readrssioptions "Permanent link") | 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[ΒΆ](#requestconnectionpriorityoptions "Permanent link") | Prop | Type | Description | Since | | ---------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | | **deviceId** | string | The address of the device to request the connection priority for. | 6.0.0 | | **connectionPriority** | [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[ΒΆ](#requestmtuoptions "Permanent link") | 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[ΒΆ](#setcharacteristicvalueoptions "Permanent link") | 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[ΒΆ](#startadvertisingoptions "Permanent link") | 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 | | **services** | Service\[\] | The services to advertise. | 7.2.0 | #### StartCharacteristicNotificationsOptions[ΒΆ](#startcharacteristicnotificationsoptions "Permanent link") | 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[ΒΆ](#startforegroundserviceoptions "Permanent link") | 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[ΒΆ](#startscanoptions "Permanent link") | Prop | Type | Description | Since | | -------------- | ---------- | --------------------------------------------------------------------------------------- | ----- | | **serviceIds** | string\[\] | Find devices with services that match any of the provided UUIDs. Only available on iOS. | 6.0.0 | #### StopCharacteristicNotificationsOptions[ΒΆ](#stopcharacteristicnotificationsoptions "Permanent link") | 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[ΒΆ](#writecharacteristicoptions "Permanent link") | 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[ΒΆ](#writedescriptoroptions "Permanent link") | 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[ΒΆ](#permissionstatus "Permanent link") | Prop | Type | Description | Since | | -------------------- | ----------------------------------- | --------------------------------------------------------------------------- | ----- | | **bluetooth** | [PermissionState](#permissionstate) | Permission state for using bluetooth. Only available on iOS. | 6.0.0 | | **bluetoothConnect** | [PermissionState](#permissionstate) | Permission state for connecting to a BLE device. Only available on Android. | 6.0.0 | | **bluetoothScan** | [PermissionState](#permissionstate) | Permission state for scanning for BLE devices. Only available on Android. | 6.0.0 | | **location** | [PermissionState](#permissionstate) | Permission state for using location services. Only available on Android. | 6.0.0 | | **notifications** | [PermissionState](#permissionstate) | Permission state for using notifications. Only available on Android. | 6.0.0 | #### BluetoothLowEnergyPluginPermission[ΒΆ](#bluetoothlowenergypluginpermission "Permanent link") | Prop | Type | Description | Default | | --------------- | ------------------------------------ | --------------------------- | --------------------------------------------------------------------------------------------------- | | **permissions** | BluetoothLowEnergyPermissionType\[\] | The permissions to request. | \['bluetooth', 'bluetoothAdmin', 'bluetoothConnect', 'bluetoothScan', 'location', 'notifications'\] | #### PluginListenerHandle[ΒΆ](#pluginlistenerhandle "Permanent link") | Prop | Type | | ---------- | ------------------- | | **remove** | () => Promise | #### CharacteristicChangedEvent[ΒΆ](#characteristicchangedevent "Permanent link") | 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[ΒΆ](#characteristicwriterequestevent "Permanent link") | 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[ΒΆ](#deviceconnectedevent "Permanent link") | 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[ΒΆ](#devicedisconnectedevent "Permanent link") | 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[ΒΆ](#devicescannedevent "Permanent link") | Prop | Type | Description | Since | | -------- | ------ | ------------------------------------------------------------ | ----- | | **id** | string | The address of the scanned device. | 6.0.0 | | **name** | string | The name of the scanned device. | 6.0.0 | | **rssi** | number | The RSSI value of the scanned device. Only available on iOS. | 6.0.0 | ### Type Aliases[ΒΆ](#type-aliases "Permanent link") #### PermissionState[ΒΆ](#permissionstate "Permanent link") `'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'` #### BluetoothLowEnergyPermissionType[ΒΆ](#bluetoothlowenergypermissiontype "Permanent link") `'bluetooth' | 'bluetoothAdmin' | 'bluetoothAdvertise' | 'bluetoothConnect' | 'bluetoothScan' | 'location' | 'notifications'` ### Enums[ΒΆ](#enums "Permanent link") #### ConnectionPriority[ΒΆ](#connectionpriority "Permanent link") | 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 | ## Utils[ΒΆ](#utils "Permanent link") 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: `[](#%5F%5Fcodelineno-63-1)import { BluetoothLowEnergyUtils } from '@capacitor-community/bluetooth-low-energy'; [](#%5F%5Fcodelineno-63-2) [](#%5F%5Fcodelineno-63-3)const convertBytesToHex = (bytes: number[]) => { [](#%5F%5Fcodelineno-63-4) return BluetoothLowEnergyUtils.convertBytesToHex({ bytes }); [](#%5F%5Fcodelineno-63-5)}; ` 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. ## FAQ[ΒΆ](#faq "Permanent link") ### Does the plugin work on the Web?[ΒΆ](#does-the-plugin-work-on-the-web "Permanent link") 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?[ΒΆ](#which-permissions-do-i-need-on-android "Permanent link") 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?[ΒΆ](#how-do-i-keep-the-ble-connection-alive-while-the-app-is-in-the-background "Permanent link") 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?[ΒΆ](#can-my-app-act-as-a-ble-peripheral "Permanent link") 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?[ΒΆ](#can-i-connect-to-multiple-devices-at-the-same-time "Permanent link") 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?[ΒΆ](#what-is-a-headless-task-and-when-do-i-need-one "Permanent link") 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[ΒΆ](#related-plugins "Permanent link") * [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. * [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. ## Newsletter[ΒΆ](#newsletter "Permanent link") 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[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/bluetooth-low-energy/CHANGELOG.md). ## Breaking Changes[ΒΆ](#breaking-changes "Permanent link") See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/bluetooth-low-energy/BREAKING.md). ## License[ΒΆ](#license "Permanent link") 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. [↩](#fnref:1 "Jump back to footnote 1 in the text") 2. `Bluetooth` is a registered trademark of Bluetooth SIG, Inc. [↩](#fnref:2 "Jump back to footnote 2 in the text") July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/#article", "headline": "Capacitor Bluetooth Low Energy Plugin for Android & iOS", "name": "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.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/#software", "name": "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.", "url": "https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "Does the plugin work on the Web?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "Which permissions do I need on Android?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "How do I keep the BLE connection alive while the app is in the background?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "Can my app act as a BLE peripheral?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "Can I connect to multiple devices at the same time?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}, {"@type": "Question", "name": "What is a headless task and when do I need one?", "acceptedAnswer": {"@type": "Answer", "text": "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."}}], "url": "https://capawesome.io/docs/sdks/capacitor/bluetooth-low-energy/"} ```