@capgo/capacitor-bluetooth-low-energy

June 25, 2026 · View on GitHub

➡️ 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)
Capacitor Web Bluetooth shim - Lets browser-style BLE code keep using navigator.bluetooth inside native Capacitor apps with one manual call

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/

Compatibility

Plugin version	Capacitor compatibility	Maintained
v8..	v8..	✅
v7..	v7..	On demand
v6..	v6..	❌
v5..	v5..	❌

Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

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

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

npm install @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.

In Capacitor native contexts, call BluetoothLowEnergy.shimWebBluetooth() before using navigator.bluetooth. That installs a JS shim so app code can keep using the Web Bluetooth API while the calls are forwarded to the native BLE implementation.

BluetoothLowEnergy.shimWebBluetooth();

const device = await navigator.bluetooth.requestDevice({
  acceptAllDevices: true,
});

const server = await device.gatt.connect();
const service = await server.getPrimaryService('180d');

The shim lives in the plugin JS bundle, auto-initializes the plugin in central mode, and forwards GATT reads, writes, descriptors, and notifications through the Capacitor bridge.

Current native limitation: requestDevice() resolves the first matching scanned device instead of opening the browser chooser UI. If you need a custom picker or peripheral-mode flows, keep using the direct plugin API.

API

initialize(...)
shimWebBluetooth()
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()
addGattService(...)
removeGattService(...)
setGattCharacteristicValue(...)
notifyGattCharacteristicChanged(...)
startForegroundService(...)
stopForegroundService()
getPluginVersion()
addListener('deviceScanned', ...)
addListener('deviceConnected', ...)
addListener('deviceDisconnected', ...)
addListener('characteristicChanged', ...)
addListener('centralConnected', ...)
addListener('centralDisconnected', ...)
addListener('gattCharacteristicReadRequest', ...)
addListener('gattCharacteristicWriteRequest', ...)
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

shimWebBluetooth()

shimWebBluetooth() => void

Install the Capacitor Web Bluetooth shim on navigator.bluetooth. Call this manually before using the Web Bluetooth API from a Capacitor native app.

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

addGattService(...)

addGattService(options: AddGattServiceOptions) => Promise<void>

Add a GATT service with characteristics to the local GATT server. Must be called in peripheral mode before starting advertising.

Param	Type	Description
`options`	`AddGattServiceOptions`	- GATT service definition

Since: 8.2.0

removeGattService(...)

removeGattService(options: RemoveGattServiceOptions) => Promise<void>

Remove a GATT service from the local GATT server.

Param	Type	Description
`options`	`RemoveGattServiceOptions`	- Service removal options

Since: 8.2.0

setGattCharacteristicValue(...)

setGattCharacteristicValue(options: SetGattCharacteristicValueOptions) => Promise<void>

Set the value of a local GATT characteristic.

Param	Type	Description
`options`	`SetGattCharacteristicValueOptions`	- Characteristic value options

Since: 8.2.0

notifyGattCharacteristicChanged(...)

notifyGattCharacteristicChanged(options: NotifyGattCharacteristicChangedOptions) => Promise<void>

Notify connected centrals that a local GATT characteristic value changed.

Param	Type	Description
`options`	`NotifyGattCharacteristicChangedOptions`	- Notification options

Since: 8.2.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

addListener('centralConnected', ...)

addListener(eventName: 'centralConnected', listenerFunc: (event: CentralConnectedEvent) => void) => Promise<PluginListenerHandle>

Add a listener for central connected events (peripheral mode).

Param	Type	Description
`eventName`	`'centralConnected'`	- The event name
`listenerFunc`	`(event: CentralConnectedEvent) => void`	- The listener function

Returns: Promise<PluginListenerHandle>

Since: 8.2.0

addListener('centralDisconnected', ...)

addListener(eventName: 'centralDisconnected', listenerFunc: (event: CentralDisconnectedEvent) => void) => Promise<PluginListenerHandle>

Add a listener for central disconnected events (peripheral mode).

Param	Type	Description
`eventName`	`'centralDisconnected'`	- The event name
`listenerFunc`	`(event: CentralDisconnectedEvent) => void`	- The listener function

Returns: Promise<PluginListenerHandle>

Since: 8.2.0

addListener('gattCharacteristicReadRequest', ...)

addListener(eventName: 'gattCharacteristicReadRequest', listenerFunc: (event: GattCharacteristicReadRequestEvent) => void) => Promise<PluginListenerHandle>

Add a listener for GATT characteristic read requests (peripheral mode).

Param	Type	Description
`eventName`	`'gattCharacteristicReadRequest'`	- The event name
`listenerFunc`	`(event: GattCharacteristicReadRequestEvent) => void`	- The listener function

Returns: Promise<PluginListenerHandle>

Since: 8.2.0

addListener('gattCharacteristicWriteRequest', ...)

addListener(eventName: 'gattCharacteristicWriteRequest', listenerFunc: (event: GattCharacteristicWriteRequestEvent) => void) => Promise<PluginListenerHandle>

Add a listener for GATT characteristic write requests (peripheral mode).

Param	Type	Description
`eventName`	`'gattCharacteristicWriteRequest'`	- The event name
`listenerFunc`	`(event: GattCharacteristicWriteRequestEvent) => void`	- The listener function

Returns: Promise<PluginListenerHandle>

Since: 8.2.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
`showPowerAlert`	`boolean`	Whether iOS should show the system Bluetooth power alert when Bluetooth is off (iOS only).	`true`	8.0.7

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. On Android, advertising the local name is implemented by temporarily setting the Bluetooth adapter name while advertising, then restoring the previous adapter name when advertising is stopped.		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

AddGattServiceOptions

Options for adding a GATT service.

Prop	Type	Description	Since
`service`	`string`	The service UUID.	8.2.0
`characteristics`	`GattCharacteristicDefinition[]`	Characteristics to expose in this service.	8.2.0

GattCharacteristicDefinition

A GATT characteristic definition for the local GATT server.

Prop	Type	Description	Since
`uuid`	`string`	The characteristic UUID.	8.2.0
`properties`	`CharacteristicProperties`	Properties of this characteristic.	8.2.0
`value`	`number[]`	Initial value as an array of bytes.	8.2.0
`descriptors`	`GattDescriptorDefinition[]`	Optional descriptors for this characteristic.	8.2.0

GattDescriptorDefinition

A GATT descriptor definition for the local GATT server.

Prop	Type	Description	Since
`uuid`	`string`	The descriptor UUID.	8.2.0
`value`	`number[]`	Initial value as an array of bytes.	8.2.0

RemoveGattServiceOptions

Options for removing a GATT service.

Prop	Type	Description	Since
`service`	`string`	The service UUID.	8.2.0

SetGattCharacteristicValueOptions

Options for setting a local GATT characteristic value.

Prop	Type	Description	Since
`service`	`string`	The service UUID.	8.2.0
`characteristic`	`string`	The characteristic UUID.	8.2.0
`value`	`number[]`	The value as an array of bytes.	8.2.0

NotifyGattCharacteristicChangedOptions

Options for notifying connected centrals of a characteristic change.

Prop	Type	Description	Since
`service`	`string`	The service UUID.	8.2.0
`characteristic`	`string`	The characteristic UUID.	8.2.0
`value`	`number[]`	The value as an array of bytes.	8.2.0
`deviceId`	`string`	Optional central device ID. When omitted, all subscribed centrals are notified.	8.2.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

CentralConnectedEvent

Event emitted when a central connects to the local GATT server.

Prop	Type	Description	Since
`deviceId`	`string`	The central device ID.	8.2.0

CentralDisconnectedEvent

Event emitted when a central disconnects from the local GATT server.

Prop	Type	Description	Since
`deviceId`	`string`	The central device ID.	8.2.0

GattCharacteristicReadRequestEvent

Event emitted when a central reads a local GATT characteristic.

Prop	Type	Description	Since
`deviceId`	`string`	The central device ID.	8.2.0
`service`	`string`	The service UUID.	8.2.0
`characteristic`	`string`	The characteristic UUID.	8.2.0

GattCharacteristicWriteRequestEvent

Event emitted when a central writes to a local GATT characteristic.

Prop	Type	Description	Since
`deviceId`	`string`	The central device ID.	8.2.0
`service`	`string`	The service UUID.	8.2.0
`characteristic`	`string`	The characteristic UUID.	8.2.0
`value`	`number[]`	The written value as an array of bytes.	8.2.0

Type Aliases

PermissionState

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

Plugin version	Capacitor compatibility	Maintained
v8..	v8..	✅
v7..	v7..	On demand
v6..	v6..	❌
v5..	v5..	❌