@capgo/capacitor-bluetooth-low-energy

➡️ Get Instant updates for your App with Capgo

Missing a feature? We'll build the plugin for you 💪

Bluetooth Low Energy (BLE) plugin for Capacitor with support for scanning, connecting, reading, writing, and notifications.

Why Capacitor Bluetooth Low Energy?

A comprehensive, free, and powerful BLE plugin:

• Full BLE support - Scan, connect, read, write, and receive notifications
• Peripheral mode - Act as a BLE server and advertise services (Android/iOS)
• Service discovery - Automatically discover services, characteristics, and descriptors
• Background support - Foreground service for Android, background modes for iOS
• Permission handling - Built-in permission management for Android 12+ and iOS
• Modern package management - Supports both Swift Package Manager (SPM) and CocoaPods
• Cross-platform - Works on iOS, Android, and Web (Chrome Web Bluetooth API)

Perfect for IoT applications, wearables, health devices, smart home, and any BLE-connected peripherals.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/bluetooth-low-energy/

Install

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

iOS

Add the following to your Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to communicate with BLE devices.</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to communicate with BLE devices.</string>

For background BLE support, add the following to your Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
    <string>bluetooth-peripheral</string>
</array>

Android

Works out of the box. The plugin automatically adds the required permissions to your AndroidManifest.xml. For Android 12+, you may need to request runtime permissions before using BLE features:

await BluetoothLowEnergy.requestPermissions();

Web

Works in Chrome and Chromium-based browsers using the Web Bluetooth API. Note that Web Bluetooth requires HTTPS and user interaction to scan for devices.

API

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

Capacitor Bluetooth Low Energy Plugin for BLE communication.

initialize(...)

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

Initialize the BLE plugin. Must be called before any other method.

Param	Type	Description
options	InitializeOptions	- Initialization options

Since: 1.0.0

---

isAvailable()

isAvailable() => Promise<IsAvailableResult>

Check if Bluetooth is available on the device.

Returns: Promise<IsAvailableResult>

Since: 1.0.0

---

isEnabled()

isEnabled() => Promise<IsEnabledResult>

Check if Bluetooth is enabled on the device.

Returns: Promise<IsEnabledResult>

Since: 1.0.0

---

isLocationEnabled()

isLocationEnabled() => Promise<IsLocationEnabledResult>

Check if location services are enabled (Android only).

Returns: Promise<IsLocationEnabledResult>

Since: 1.0.0

---

openAppSettings()

openAppSettings() => Promise<void>

Open the app settings page.

Since: 1.0.0

---

openBluetoothSettings()

openBluetoothSettings() => Promise<void>

Open the Bluetooth settings page (Android only).

Since: 1.0.0

---

openLocationSettings()

openLocationSettings() => Promise<void>

Open the location settings page (Android only).

Since: 1.0.0

---

checkPermissions()

checkPermissions() => Promise<PermissionStatus>

Check the current permission status.

Returns: Promise<PermissionStatus>

Since: 1.0.0

---

requestPermissions()

requestPermissions() => Promise<PermissionStatus>

Request Bluetooth permissions.

Returns: Promise<PermissionStatus>

Since: 1.0.0

---

startScan(...)

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

Start scanning for BLE devices.

Param	Type	Description
options	StartScanOptions	- Scan options

Since: 1.0.0

---

stopScan()

stopScan() => Promise<void>

Stop scanning for BLE devices.

Since: 1.0.0

---

connect(...)

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

Connect to a BLE device.

Param	Type	Description
options	ConnectOptions	- Connection options

Since: 1.0.0

---

disconnect(...)

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

Disconnect from a BLE device.

Param	Type	Description
options	DisconnectOptions	- Disconnect options

Since: 1.0.0

---

createBond(...)

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

Create a bond with a BLE device (Android only).

Param	Type	Description
options	CreateBondOptions	- Bond options

Since: 1.0.0

---

isBonded(...)

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

Check if a device is bonded (Android only).

Param	Type	Description
options	IsBondedOptions	- Bond check options

Returns: Promise<IsBondedResult>

Since: 1.0.0

---

discoverServices(...)

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

Discover services on a connected device.

Param	Type	Description
options	DiscoverServicesOptions	- Discover options

Since: 1.0.0

---

getServices(...)

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

Get discovered services for a device.

Param	Type	Description
options	GetServicesOptions	- Get services options

Returns: Promise<GetServicesResult>

Since: 1.0.0

---

getConnectedDevices()

getConnectedDevices() => Promise<GetConnectedDevicesResult>

Get a list of connected devices.

Returns: Promise<GetConnectedDevicesResult>

Since: 1.0.0

---

readCharacteristic(...)

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

Read a characteristic value.

Param	Type	Description
options	ReadCharacteristicOptions	- Read options

Returns: Promise<ReadCharacteristicResult>

Since: 1.0.0

---

writeCharacteristic(...)

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

Write a value to a characteristic.

Param	Type	Description
options	WriteCharacteristicOptions	- Write options

Since: 1.0.0

---

startCharacteristicNotifications(...)

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

Start notifications for a characteristic.

Param	Type	Description
options	StartCharacteristicNotificationsOptions	- Notification options

Since: 1.0.0

---

stopCharacteristicNotifications(...)

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

Stop notifications for a characteristic.

Param	Type	Description
options	StopCharacteristicNotificationsOptions	- Stop notification options

Since: 1.0.0

---

readDescriptor(...)

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

Read a descriptor value.

Param	Type	Description
options	ReadDescriptorOptions	- Read descriptor options

Returns: Promise<ReadDescriptorResult>

Since: 1.0.0

---

writeDescriptor(...)

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

Write a value to a descriptor.

Param	Type	Description
options	WriteDescriptorOptions	- Write descriptor options

Since: 1.0.0

---

readRssi(...)

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

Read the RSSI (signal strength) of a connected device.

Param	Type	Description
options	ReadRssiOptions	- Read RSSI options

Returns: Promise<ReadRssiResult>

Since: 1.0.0

---

requestMtu(...)

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

Request MTU size change (Android only).

Param	Type	Description
options	RequestMtuOptions	- Request MTU options

Returns: Promise<RequestMtuResult>

Since: 1.0.0

---

requestConnectionPriority(...)

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

Request connection priority (Android only).

Param	Type	Description
options	RequestConnectionPriorityOptions	- Request priority options

Since: 1.0.0

---

startAdvertising(...)

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

Start advertising as a peripheral (BLE server).

Param	Type	Description
options	StartAdvertisingOptions	- Advertising options

Since: 1.0.0

---

stopAdvertising()

stopAdvertising() => Promise<void>

Stop advertising.

Since: 1.0.0

---

startForegroundService(...)

startForegroundService(options: StartForegroundServiceOptions) => Promise<void>

Start a foreground service to maintain BLE connections in background (Android only).

Param	Type	Description
options	StartForegroundServiceOptions	- Foreground service options

Since: 1.0.0

---

stopForegroundService()

stopForegroundService() => Promise<void>

Stop the foreground service (Android only).

Since: 1.0.0

---

getPluginVersion()

getPluginVersion() => Promise<GetPluginVersionResult>

Get the native Capacitor plugin version.

Returns: Promise<GetPluginVersionResult>

Since: 1.0.0

---

addListener('deviceScanned', ...)

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

Add a listener for device scanned events.

Param	Type	Description
eventName	'deviceScanned'	- The event name
listenerFunc	(event: DeviceScannedEvent) => void	- The listener function

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

---

addListener('deviceConnected', ...)

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

Add a listener for device connected events.

Param	Type	Description
eventName	'deviceConnected'	- The event name
listenerFunc	(event: DeviceConnectedEvent) => void	- The listener function

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

---

addListener('deviceDisconnected', ...)

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

Add a listener for device disconnected events.

Param	Type	Description
eventName	'deviceDisconnected'	- The event name
listenerFunc	(event: DeviceDisconnectedEvent) => void	- The listener function

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

---

addListener('characteristicChanged', ...)

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

Add a listener for characteristic changed events.

Param	Type	Description
eventName	'characteristicChanged'	- The event name
listenerFunc	(event: CharacteristicChangedEvent) => void	- The listener function

Returns: Promise<PluginListenerHandle>

Since: 1.0.0

---

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 1.0.0

---

Interfaces

InitializeOptions

Initialization options for the plugin.

Prop	Type	Description	Default	Since
mode	'central' | 'peripheral'	The mode to initialize the plugin in. - 'central': Act as a BLE central (client) - 'peripheral': Act as a BLE peripheral (server)	'central'	1.0.0

IsAvailableResult

Result of the isAvailable method.

Prop	Type	Description	Since
available	boolean	Whether Bluetooth is available on the device.	1.0.0

IsEnabledResult

Result of the isEnabled method.

Prop	Type	Description	Since
enabled	boolean	Whether Bluetooth is enabled on the device.	1.0.0

IsLocationEnabledResult

Result of the isLocationEnabled method.

Prop	Type	Description	Since
enabled	boolean	Whether location services are enabled on the device.	1.0.0

PermissionStatus

Permission status for Bluetooth and location.

Prop	Type	Description	Since
bluetooth	PermissionState	Bluetooth permission status.	1.0.0
location	PermissionState	Location permission status (Android only).	1.0.0

StartScanOptions

Options for starting a scan.

Prop	Type	Description	Default	Since
services	string[]	List of service UUIDs to filter by. Only devices advertising these services will be returned.		1.0.0
timeout	number	Scan timeout in milliseconds. Set to 0 for no timeout.	0	1.0.0
allowDuplicates	boolean	Whether to allow duplicate scan results.	false	1.0.0

ConnectOptions

Options for connecting to a device.

Prop	Type	Description	Default	Since
deviceId	string	The device ID (MAC address on Android, UUID on iOS).		1.0.0
autoConnect	boolean	Whether to automatically connect when the device becomes available.	false	1.0.0

DisconnectOptions

Options for disconnecting from a device.

Prop	Type	Description	Since
deviceId	string	The device ID to disconnect from.	1.0.0

CreateBondOptions

Options for creating a bond.

Prop	Type	Description	Since
deviceId	string	The device ID to bond with.	1.0.0

IsBondedResult

Result of the isBonded method.

Prop	Type	Description	Since
bonded	boolean	Whether the device is bonded.	1.0.0

IsBondedOptions

Options for checking bond status.

Prop	Type	Description	Since
deviceId	string	The device ID to check.	1.0.0

DiscoverServicesOptions

Options for discovering services.

Prop	Type	Description	Since
deviceId	string	The device ID to discover services on.	1.0.0

GetServicesResult

Result of the getServices method.

Prop	Type	Description	Since
services	BleService[]	List of discovered services.	1.0.0

BleService

A BLE service.

Prop	Type	Description	Since
uuid	string	The service UUID.	1.0.0
characteristics	BleCharacteristic[]	List of characteristics in this service.	1.0.0

BleCharacteristic

A BLE characteristic.

Prop	Type	Description	Since
uuid	string	The characteristic UUID.	1.0.0
properties	CharacteristicProperties	Properties of this characteristic.	1.0.0
descriptors	BleDescriptor[]	List of descriptors in this characteristic.	1.0.0

CharacteristicProperties

Properties of a BLE characteristic.

Prop	Type	Description	Since
broadcast	boolean	Whether the characteristic supports broadcast.	1.0.0
read	boolean	Whether the characteristic supports read.	1.0.0
writeWithoutResponse	boolean	Whether the characteristic supports write without response.	1.0.0
write	boolean	Whether the characteristic supports write.	1.0.0
notify	boolean	Whether the characteristic supports notify.	1.0.0
indicate	boolean	Whether the characteristic supports indicate.	1.0.0
authenticatedSignedWrites	boolean	Whether the characteristic supports authenticated signed writes.	1.0.0
extendedProperties	boolean	Whether the characteristic has extended properties.	1.0.0

BleDescriptor

A BLE descriptor.

Prop	Type	Description	Since
uuid	string	The descriptor UUID.	1.0.0

GetServicesOptions

Options for getting services.

Prop	Type	Description	Since
deviceId	string	The device ID to get services for.	1.0.0

GetConnectedDevicesResult

Result of the getConnectedDevices method.

Prop	Type	Description	Since
devices	BleDevice[]	List of connected devices.	1.0.0

BleDevice

A BLE device.

Prop	Type	Description	Since
deviceId	string	The device ID (MAC address on Android, UUID on iOS).	1.0.0
name	string | null	The device name (may be null if not available).	1.0.0
rssi	number	The RSSI (signal strength) at time of discovery.	1.0.0
manufacturerData	string	Manufacturer data from advertisement (as hex string).	1.0.0
serviceUuids	string[]	Service UUIDs advertised by the device.	1.0.0

ReadCharacteristicResult

Result of reading a characteristic.

Prop	Type	Description	Since
value	number[]	The characteristic value as an array of bytes.	1.0.0

ReadCharacteristicOptions

Options for reading a characteristic.

Prop	Type	Description	Since
deviceId	string	The device ID.	1.0.0
service	string	The service UUID.	1.0.0
characteristic	string	The characteristic UUID.	1.0.0

WriteCharacteristicOptions

Options for writing to a characteristic.

Prop	Type	Description	Default	Since
deviceId	string	The device ID.		1.0.0
service	string	The service UUID.		1.0.0
characteristic	string	The characteristic UUID.		1.0.0
value	number[]	The value to write as an array of bytes.		1.0.0
type	'withResponse' | 'withoutResponse'	Write type.	'withResponse'	1.0.0

StartCharacteristicNotificationsOptions

Options for starting characteristic notifications.

Prop	Type	Description	Since
deviceId	string	The device ID.	1.0.0
service	string	The service UUID.	1.0.0
characteristic	string	The characteristic UUID.	1.0.0

StopCharacteristicNotificationsOptions

Options for stopping characteristic notifications.

Prop	Type	Description	Since
deviceId	string	The device ID.	1.0.0
service	string	The service UUID.	1.0.0
characteristic	string	The characteristic UUID.	1.0.0

ReadDescriptorResult

Result of reading a descriptor.

Prop	Type	Description	Since
value	number[]	The descriptor value as an array of bytes.	1.0.0

ReadDescriptorOptions

Options for reading a descriptor.

Prop	Type	Description	Since
deviceId	string	The device ID.	1.0.0
service	string	The service UUID.	1.0.0
characteristic	string	The characteristic UUID.	1.0.0
descriptor	string	The descriptor UUID.	1.0.0

WriteDescriptorOptions

Options for writing to a descriptor.

Prop	Type	Description	Since
deviceId	string	The device ID.	1.0.0
service	string	The service UUID.	1.0.0
characteristic	string	The characteristic UUID.	1.0.0
descriptor	string	The descriptor UUID.	1.0.0
value	number[]	The value to write as an array of bytes.	1.0.0

ReadRssiResult

Result of reading RSSI.

Prop	Type	Description	Since
rssi	number	The RSSI value in dBm.	1.0.0

ReadRssiOptions

Options for reading RSSI.

Prop	Type	Description	Since
deviceId	string	The device ID.	1.0.0

RequestMtuResult

Result of requesting MTU.

Prop	Type	Description	Since
mtu	number	The negotiated MTU size.	1.0.0

RequestMtuOptions

Options for requesting MTU.

Prop	Type	Description	Since
deviceId	string	The device ID.	1.0.0
mtu	number	The requested MTU size.	1.0.0

RequestConnectionPriorityOptions

Options for requesting connection priority.

Prop	Type	Description	Since
deviceId	string	The device ID.	1.0.0
priority	'low' | 'balanced' | 'high'	The requested connection priority.	1.0.0

StartAdvertisingOptions

Options for starting advertising.

Prop	Type	Description	Default	Since
name	string	The device name to advertise.		1.0.0
services	string[]	Service UUIDs to advertise.		1.0.0
includeName	boolean	Whether to include the device name in the advertisement.	true	1.0.0
includeTxPowerLevel	boolean	Whether to include TX power level in the advertisement.	false	1.0.0

StartForegroundServiceOptions

Options for starting the foreground service.

Prop	Type	Description	Since
title	string	The notification title.	1.0.0
body	string	The notification body.	1.0.0
smallIcon	string	The notification small icon resource name.	1.0.0

GetPluginVersionResult

Result of getPluginVersion.

Prop	Type	Description	Since
version	string	The plugin version.	1.0.0

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

DeviceScannedEvent

Event emitted when a device is scanned.

Prop	Type	Description	Since
device	BleDevice	The scanned device.	1.0.0

DeviceConnectedEvent

Event emitted when a device is connected.

Prop	Type	Description	Since
deviceId	string	The device ID.	1.0.0

DeviceDisconnectedEvent

Event emitted when a device is disconnected.

Prop	Type	Description	Since
deviceId	string	The device ID.	1.0.0

CharacteristicChangedEvent

Event emitted when a characteristic value changes.

Prop	Type	Description	Since
deviceId	string	The device ID.	1.0.0
service	string	The service UUID.	1.0.0
characteristic	string	The characteristic UUID.	1.0.0
value	number[]	The new value as an array of bytes.	1.0.0

Type Aliases

PermissionState

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