Research
Two Malicious Rust Crates Impersonate Popular Logger to Steal Wallet Keys
Socket uncovers malicious Rust crates impersonating fast_log to steal Solana and Ethereum wallet keys from source code.
By Kirill Boychenko - Sep 24, 2025
@capacitor-community/bluetooth-le
Advanced tools
Bluetooth Low Energy
@capacitor-community/bluetooth-le
Capacitor plugin for Bluetooth Low Energy
Maintainers
| Maintainer | GitHub |
|---|---|
| Patrick Wespi | pwespi |
| Philip Peitsch | peitschie |
Versions
| Plugin | Capacitor | Documentation |
|---|---|---|
| 7.x | 7.x | README |
| 6.x | 6.x | README |
| 3.x | 5.x | README |
| 2.x | 4.x | README |
| 1.x | 3.x | README |
| 0.x | 2.x | README |
Introduction
This is a Capacitor plugin for Bluetooth Low Energy. It supports the web, Android and iOS.
The goal is to support the same features on all platforms. Therefore the Web Bluetooth API is taken as a guidline for what features to implement.
This plugin only supports Bluetooth Low Energy, not Bluetooth serial / classic.
Furthermore the plugin only supports the central role of the Bluetooth Low Energy protocol. If you need the peripheral role, take a look a these plugins:
- https://github.com/randdusing/cordova-plugin-bluetoothle
- https://github.com/don/cordova-plugin-ble-peripheral
For support of Web Bluetooth in various browsers, see implementation status.
Below is an index of all the methods available.
initialize(...)isEnabled()requestEnable()enable()disable()startEnabledNotifications(...)stopEnabledNotifications()isLocationEnabled()openLocationSettings()openBluetoothSettings()openAppSettings()setDisplayStrings(...)requestDevice(...)requestLEScan(...)stopLEScan()getDevices(...)getBondedDevices()getConnectedDevices(...)connect(...)createBond(...)isBonded(...)disconnect(...)getServices(...)discoverServices(...)getMtu(...)requestConnectionPriority(...)readRssi(...)read(...)write(...)writeWithoutResponse(...)readDescriptor(...)writeDescriptor(...)startNotifications(...)stopNotifications(...)- Interfaces
- Type Aliases
- Enums
See Platform Support for an overview of supported methods on Android, iOS and web.
Installation
npm install @capacitor-community/bluetooth-le
npx cap sync
iOS
On iOS, add the NSBluetoothAlwaysUsageDescription to Info.plist, otherwise the app will crash when trying to use Bluetooth (see here).
If the app needs to use Bluetooth while it is in the background, you also have to add bluetooth-central to UIBackgroundModes (for details see here).
./ios/App/App/Info.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleDevelopmentRegion</key>
<string>en</string>
...
+ <key>NSBluetoothAlwaysUsageDescription</key>
+ <string>Uses Bluetooth to connect and interact with peripheral BLE devices.</string>
+ <key>UIBackgroundModes</key>
+ <array>
+ <string>bluetooth-central</string>
+ </array>
</dict>
</plist>
Note: Bluetooth is not available in the iOS simulator. The initialize call will be rejected with an error "BLE unsupported". You have to test your app on a real device.
Android
On Android, no further steps are required to use the plugin.
(Optional) Android 12 Bluetooth permissions
If your app targets Android 12 (API level 31) or higher and your app doesn't use Bluetooth scan results to derive physical location information, you can strongly assert that your app doesn't derive physical location. This allows the app to scan for Bluetooth devices without asking for location permissions. See the Android documentation.
The following steps are required to scan for Bluetooth devices without location permission on Android 12 devices:
- In
android/variables.gradle, make surecompileSdkVersionandtargetSdkVersionare at least 31 (changing those values can have other consequences on your app, so make sure you know what you're doing). - In
android/app/src/main/AndroidManifest.xml, update the permissions:<!-- Permissions --> + <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="30" /> + <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" /> + <uses-permission android:name="android.permission.BLUETOOTH_SCAN" + android:usesPermissionFlags="neverForLocation" + tools:targetApi="s" /> - Set the
androidNeverForLocationflag totruewhen initializing theBleClient.import { BleClient } from '@capacitor-community/bluetooth-le'; await BleClient.initialize({ androidNeverForLocation: true });
Configuration
You can configure the strings that are displayed in the device selection dialog on iOS and Android when using requestDevice():
./capacitor.config.json:
{
"...": "other configuration",
"plugins": {
"BluetoothLe": {
"displayStrings": {
"scanning": "Am Scannen...",
"cancel": "Abbrechen",
"availableDevices": "Verfügbare Geräte",
"noDeviceFound": "Kein Gerät gefunden"
}
}
}
}
The default values are:
{
"plugins": {
"BluetoothLe": {
"displayStrings": {
"scanning": "Scanning...",
"cancel": "Cancel",
"availableDevices": "Available devices",
"noDeviceFound": "No device found"
}
}
}
}
The display strings can also be set at run-time using setDisplayStrings(...).
Usage
There is a plugin wrapper class BleClient which makes events and method arguments easier to work with.
// Import the wrapper class
import { BleClient } from '@capacitor-community/bluetooth-le';
Note: It is not recommended to use the BluetoothLe plugin class directly.
Heart rate monitor
Here is an example of how to use the plugin. It shows how to read the heart rate from a BLE heart rate monitor such as the Polar H10.
import { BleClient, numbersToDataView, numberToUUID } from '@capacitor-community/bluetooth-le';
const HEART_RATE_SERVICE = '0000180d-0000-1000-8000-00805f9b34fb';
const HEART_RATE_MEASUREMENT_CHARACTERISTIC = '00002a37-0000-1000-8000-00805f9b34fb';
const BODY_SENSOR_LOCATION_CHARACTERISTIC = '00002a38-0000-1000-8000-00805f9b34fb';
const BATTERY_SERVICE = numberToUUID(0x180f);
const BATTERY_CHARACTERISTIC = numberToUUID(0x2a19);
const POLAR_PMD_SERVICE = 'fb005c80-02e7-f387-1cad-8acd2d8df0c8';
const POLAR_PMD_CONTROL_POINT = 'fb005c81-02e7-f387-1cad-8acd2d8df0c8';
export async function main(): Promise<void> {
try {
await BleClient.initialize();
const device = await BleClient.requestDevice({
services: [HEART_RATE_SERVICE],
optionalServices: [BATTERY_SERVICE, POLAR_PMD_SERVICE],
});
// connect to device, the onDisconnect callback is optional
await BleClient.connect(device.deviceId, (deviceId) => onDisconnect(deviceId));
console.log('connected to device', device);
const result = await BleClient.read(device.deviceId, HEART_RATE_SERVICE, BODY_SENSOR_LOCATION_CHARACTERISTIC);
console.log('body sensor location', result.getUint8(0));
const battery = await BleClient.read(device.deviceId, BATTERY_SERVICE, BATTERY_CHARACTERISTIC);
console.log('battery level', battery.getUint8(0));
await BleClient.write(device.deviceId, POLAR_PMD_SERVICE, POLAR_PMD_CONTROL_POINT, numbersToDataView([1, 0]));
console.log('written [1, 0] to control point');
await BleClient.startNotifications(
device.deviceId,
HEART_RATE_SERVICE,
HEART_RATE_MEASUREMENT_CHARACTERISTIC,
(value) => {
console.log('current heart rate', parseHeartRate(value));
}
);
// disconnect after 10 sec
setTimeout(async () => {
await BleClient.stopNotifications(device.deviceId, HEART_RATE_SERVICE, HEART_RATE_MEASUREMENT_CHARACTERISTIC);
await BleClient.disconnect(device.deviceId);
console.log('disconnected from device', device);
}, 10000);
} catch (error) {
console.error(error);
}
}
function onDisconnect(deviceId: string): void {
console.log(`device ${deviceId} disconnected`);
}
function parseHeartRate(value: DataView): number {
const flags = value.getUint8(0);
const rate16Bits = flags & 0x1;
let heartRate: number;
if (rate16Bits > 0) {
heartRate = value.getUint16(1, true);
} else {
heartRate = value.getUint8(1);
}
return heartRate;
}
Scanning API
Here is an example of using the scanning API.
import { BleClient, numberToUUID } from '@capacitor-community/bluetooth-le';
const HEART_RATE_SERVICE = numberToUUID(0x180d);
export async function scan(): Promise<void> {
try {
await BleClient.initialize();
await BleClient.requestLEScan(
{
services: [HEART_RATE_SERVICE],
},
(result) => {
console.log('received new scan result', result);
}
);
setTimeout(async () => {
await BleClient.stopLEScan();
console.log('stopped scanning');
}, 5000);
} catch (error) {
console.error(error);
}
}
Example Applications
- BLE Tester (Ionic/React)
- OpenGoPro (Ionic/Angular)
- Quasar BLE (Quasar/Vue)
Platform Support
Note: web support depends on the browser, see implementation status.
Legend
- ✅ supported
- ❌ not supported (throws an
unavailableerror) - 🚩 behind a flag in Chrome (see implementation status)
- -- not supported, but does not throw an error
API
initialize(...)
initialize(options?: InitializeOptions | undefined) => Promise<void>
Initialize Bluetooth Low Energy (BLE). If it fails, BLE might be unavailable on this device. On Android it will ask for the location permission. On iOS it will ask for the Bluetooth permission. For an example, see usage.
| Param | Type |
|---|---|
options | InitializeOptions |
isEnabled()
isEnabled() => Promise<boolean>
Reports whether Bluetooth is enabled on this device.
Always returns true on web.
Returns: Promise<boolean>
requestEnable()
requestEnable() => Promise<void>
Request enabling Bluetooth. Show a system activity that allows the user to turn on Bluetooth. See https://developer.android.com/reference/android/bluetooth/BluetoothAdapter#ACTION_REQUEST_ENABLE Only available on Android.
enable()
enable() => Promise<void>
Enable Bluetooth.
Only available on Android.
Deprecated Will fail on Android SDK >= 33. Use requestEnable instead. See https://developer.android.com/reference/android/bluetooth/BluetoothAdapter#enable()
disable()
disable() => Promise<void>
Disable Bluetooth. Only available on Android. Deprecated Will fail on Android SDK >= 33. See https://developer.android.com/reference/android/bluetooth/BluetoothAdapter#disable()
startEnabledNotifications(...)
startEnabledNotifications(callback: (value: boolean) => void) => Promise<void>
Register a callback function that will be invoked when Bluetooth is enabled (true) or disabled (false) on this device. Not available on web (the callback will never be invoked).
| Param | Type | Description |
|---|---|---|
callback | (value: boolean) => void | Callback function to use when the Bluetooth state changes. |
stopEnabledNotifications()
stopEnabledNotifications() => Promise<void>
Stop the enabled notifications registered with startEnabledNotifications.
isLocationEnabled()
isLocationEnabled() => Promise<boolean>
Reports whether Location Services are enabled on this device. Only available on Android.
Returns: Promise<boolean>
openLocationSettings()
openLocationSettings() => Promise<void>
Open Location settings. Only available on Android.
openBluetoothSettings()
openBluetoothSettings() => Promise<void>
Open Bluetooth settings. Only available on Android.
openAppSettings()
openAppSettings() => Promise<void>
Open App settings.
Not available on web.
On iOS when a user declines the request to use Bluetooth on the first call of initialize, it is not possible
to request for Bluetooth again from within the app. In this case Bluetooth has to be enabled in the app settings
for the app to be able use it.
setDisplayStrings(...)
setDisplayStrings(displayStrings: DisplayStrings) => Promise<void>
Set the strings that are displayed in the requestDevice dialog.
| Param | Type |
|---|---|
displayStrings | DisplayStrings |
requestDevice(...)
requestDevice(options?: RequestBleDeviceOptions | undefined) => Promise<BleDevice>
Request a peripheral BLE device to interact with. This will scan for available devices according to the filters in the options and show a dialog to pick a device. For an example, see usage.
| Param | Type | Description |
|---|---|---|
options | RequestBleDeviceOptions | Device filters, see RequestBleDeviceOptions |
Returns: Promise<BleDevice>
requestLEScan(...)
requestLEScan(options: RequestBleDeviceOptions, callback: (result: ScanResult) => void) => Promise<void>
Start scanning for BLE devices to interact with according to the filters in the options. The callback will be invoked on each device that is found.
Scanning will continue until stopLEScan is called. For an example, see usage.
Note: Use with care on web platform, the required API is still behind a flag in most browsers.
| Param | Type |
|---|---|
options | RequestBleDeviceOptions |
callback | (result: ScanResult) => void |
stopLEScan()
stopLEScan() => Promise<void>
Stop scanning for BLE devices. For an example, see usage.
getDevices(...)
getDevices(deviceIds: string[]) => Promise<BleDevice[]>
On iOS and web, if you want to connect to a previously connected device without scanning first, you can use getDevice.
Uses retrievePeripherals on iOS and
getDevices on web.
On Android, you can directly connect to the device with the deviceId.
| Param | Type | Description |
|---|---|---|
deviceIds | string[] | List of device IDs, e.g. saved from a previous app run. |
Returns: Promise<BleDevice[]>
getBondedDevices()
getBondedDevices() => Promise<BleDevice[]>
Get a list of currently bonded devices. Only available on Android. Uses getBondedDevices on Android
Returns: Promise<BleDevice[]>
getConnectedDevices(...)
getConnectedDevices(services: string[]) => Promise<BleDevice[]>
Get a list of currently connected devices. Uses retrieveConnectedPeripherals on iOS, getConnectedDevices on Android and getDevices on web.
| Param | Type | Description |
|---|---|---|
services | string[] | List of services to filter the devices by. If no service is specified, no devices will be returned. Only applies to iOS. |
Returns: Promise<BleDevice[]>
connect(...)
connect(deviceId: string, onDisconnect?: ((deviceId: string) => void) | undefined, options?: TimeoutOptions | undefined) => Promise<void>
Connect to a peripheral BLE device. For an example, see usage.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
onDisconnect | ((deviceId: string) => void) | Optional disconnect callback function that will be used when the device disconnects |
options | TimeoutOptions | Options for plugin call |
createBond(...)
createBond(deviceId: string, options?: TimeoutOptions | undefined) => Promise<void>
Create a bond with a peripheral BLE device. Only available on Android. On iOS bonding is handled by the OS.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
options | TimeoutOptions | Options for plugin call |
isBonded(...)
isBonded(deviceId: string) => Promise<boolean>
Report whether a peripheral BLE device is bonded. Only available on Android. On iOS bonding is handled by the OS.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
Returns: Promise<boolean>
disconnect(...)
disconnect(deviceId: string) => Promise<void>
Disconnect from a peripheral BLE device. For an example, see usage.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
getServices(...)
getServices(deviceId: string) => Promise<BleService[]>
Get services, characteristics and descriptors of a device.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
Returns: Promise<BleService[]>
discoverServices(...)
discoverServices(deviceId: string) => Promise<void>
Discover services, characteristics and descriptors of a device. You only need this method if your peripheral device changes its services and characteristics at runtime. If the discovery was successful, the remote services can be retrieved using the getServices function. Not available on web.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
getMtu(...)
getMtu(deviceId: string) => Promise<number>
Get the MTU of a connected device. Note that the maximum write value length is 3 bytes less than the MTU. Not available on web.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
Returns: Promise<number>
requestConnectionPriority(...)
requestConnectionPriority(deviceId: string, connectionPriority: ConnectionPriority) => Promise<void>
Request a connection parameter update. Only available on Android. https://developer.android.com/reference/android/bluetooth/BluetoothGatt#requestConnectionPriority(int)
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
connectionPriority | ConnectionPriority | Request a specific connection priority. See ConnectionPriority |
readRssi(...)
readRssi(deviceId: string) => Promise<number>
Read the RSSI value of a connected device. Not available on web.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
Returns: Promise<number>
read(...)
read(deviceId: string, service: string, characteristic: string, options?: TimeoutOptions | undefined) => Promise<DataView>
Read the value of a characteristic. For an example, see usage.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
service | string | UUID of the service (see UUID format) |
characteristic | string | UUID of the characteristic (see UUID format) |
options | TimeoutOptions | Options for plugin call |
Returns: Promise<DataView>
write(...)
write(deviceId: string, service: string, characteristic: string, value: DataView, options?: TimeoutOptions | undefined) => Promise<void>
Write a value to a characteristic. For an example, see usage.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
service | string | UUID of the service (see UUID format) |
characteristic | string | UUID of the characteristic (see UUID format) |
value | DataView | The value to write as a DataView. To create a DataView from an array of numbers, there is a helper function, e.g. numbersToDataView([1, 0]) |
options | TimeoutOptions | Options for plugin call |
writeWithoutResponse(...)
writeWithoutResponse(deviceId: string, service: string, characteristic: string, value: DataView, options?: TimeoutOptions | undefined) => Promise<void>
Write a value to a characteristic without waiting for a response.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
service | string | UUID of the service (see UUID format) |
characteristic | string | UUID of the characteristic (see UUID format) |
value | DataView | The value to write as a DataView. To create a DataView from an array of numbers, there is a helper function, e.g. numbersToDataView([1, 0]) |
options | TimeoutOptions | Options for plugin call |
readDescriptor(...)
readDescriptor(deviceId: string, service: string, characteristic: string, descriptor: string, options?: TimeoutOptions | undefined) => Promise<DataView>
Read the value of a descriptor.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
service | string | UUID of the service (see UUID format) |
characteristic | string | UUID of the characteristic (see UUID format) |
descriptor | string | UUID of the descriptor (see UUID format) |
options | TimeoutOptions | Options for plugin call |
Returns: Promise<DataView>
writeDescriptor(...)
writeDescriptor(deviceId: string, service: string, characteristic: string, descriptor: string, value: DataView, options?: TimeoutOptions | undefined) => Promise<void>
Write a value to a descriptor.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
service | string | UUID of the service (see UUID format) |
characteristic | string | UUID of the characteristic (see UUID format) |
descriptor | string | UUID of the descriptor (see UUID format) |
value | DataView | The value to write as a DataView. To create a DataView from an array of numbers, there is a helper function, e.g. numbersToDataView([1, 0]) |
options | TimeoutOptions | Options for plugin call |
startNotifications(...)
startNotifications(deviceId: string, service: string, characteristic: string, callback: (value: DataView) => void) => Promise<void>
Start listening to changes of the value of a characteristic.
Note that you should only start the notifications once per characteristic in your app and share the data and
not call startNotifications in every component that needs the data.
For an example, see usage.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
service | string | UUID of the service (see UUID format) |
characteristic | string | UUID of the characteristic (see UUID format) |
callback | (value: DataView) => void | Callback function to use when the value of the characteristic changes |
stopNotifications(...)
stopNotifications(deviceId: string, service: string, characteristic: string) => Promise<void>
Stop listening to the changes of the value of a characteristic. For an example, see usage.
| Param | Type | Description |
|---|---|---|
deviceId | string | The ID of the device to use (obtained from requestDevice or requestLEScan) |
service | string | UUID of the service (see UUID format) |
characteristic | string | UUID of the characteristic (see UUID format) |
Interfaces
InitializeOptions
| Prop | Type | Description | Default |
|---|---|---|---|
androidNeverForLocation | boolean | If your app doesn't use Bluetooth scan results to derive physical location information, you can strongly assert that your app doesn't derive physical location. (Android only) Requires adding 'neverForLocation' to AndroidManifest.xml https://developer.android.com/guide/topics/connectivity/bluetooth/permissions#assert-never-for-location | false |
DisplayStrings
| Prop | Type | Default | Since |
|---|---|---|---|
scanning | string | "Scanning..." | 0.0.1 |
cancel | string | "Cancel" | 0.0.1 |
availableDevices | string | "Available devices" | 0.0.1 |
noDeviceFound | string | "No device found" | 0.0.1 |
BleDevice
| Prop | Type | Description |
|---|---|---|
deviceId | string | ID of the device, which will be needed for further calls. On Android this is the BLE MAC address. On iOS and web it is an identifier. |
name | string | Name of the peripheral device. |
uuids | string[] |
RequestBleDeviceOptions
| Prop | Type | Description |
|---|---|---|
services | string[] | Filter devices by service UUIDs. UUIDs have to be specified as 128 bit UUID strings, e.g. ['0000180d-0000-1000-8000-00805f9b34fb'] There is a helper function to convert numbers to UUIDs. e.g. [numberToUUID(0x180f)]. (see UUID format) |
name | string | Filter devices by name |
namePrefix | string | Filter devices by name prefix |
optionalServices | string[] | For web, all services that will be used have to be listed under services or optionalServices, e.g. [numberToUUID(0x180f)] (see UUID format) |
allowDuplicates | boolean | Normally scans will discard the second and subsequent advertisements from a single device. If you need to receive them, set allowDuplicates to true (only applicable in requestLEScan). (default: false) |
scanMode | ScanMode | Android scan mode (default: ScanMode.SCAN_MODE_BALANCED) |
manufacturerData | { companyIdentifier: number; dataPrefix?: Uint8Array; mask?: Uint8Array; }[] | Allow scanning for devices with a specific manufacturer data https://developer.mozilla.org/en-US/docs/Web/API/Bluetooth/requestDevice#manufacturerdata |
Uint8Array
A typed array of 8-bit unsigned integer values. The contents are initialized to 0. If the requested number of bytes could not be allocated an exception is raised.
| Prop | Type | Description |
|---|---|---|
BYTES_PER_ELEMENT | number | The size in bytes of each element in the array. |
buffer | ArrayBufferLike | The ArrayBuffer instance referenced by the array. |
byteLength | number | The length in bytes of the array. |
byteOffset | number | The offset in bytes of the array. |
length | number | The length of the array. |
| Method | Signature | Description |
|---|---|---|
| copyWithin | (target: number, start: number, end?: number | undefined) => this | Returns the this object after copying a section of the array identified by start and end to the same array starting at position target |
| every | (predicate: (value: number, index: number, array: Uint8Array) => unknown, thisArg?: any) => boolean | Determines whether all the members of an array satisfy the specified test. |
| fill | (value: number, start?: number | undefined, end?: number | undefined) => this | Returns the this object after filling the section identified by start and end with value |
| filter | (predicate: (value: number, index: number, array: Uint8Array) => any, thisArg?: any) => Uint8Array | Returns the elements of an array that meet the condition specified in a callback function. |
| find | (predicate: (value: number, index: number, obj: Uint8Array) => boolean, thisArg?: any) => number | undefined | Returns the value of the first element in the array where predicate is true, and undefined otherwise. |
| findIndex | (predicate: (value: number, index: number, obj: Uint8Array) => boolean, thisArg?: any) => number | Returns the index of the first element in the array where predicate is true, and -1 otherwise. |
| forEach | (callbackfn: (value: number, index: number, array: Uint8Array) => void, thisArg?: any) => void | Performs the specified action for each element in an array. |
| indexOf | (searchElement: number, fromIndex?: number | undefined) => number | Returns the index of the first occurrence of a value in an array. |
| join | (separator?: string | undefined) => string | Adds all the elements of an array separated by the specified separator string. |
| lastIndexOf | (searchElement: number, fromIndex?: number | undefined) => number | Returns the index of the last occurrence of a value in an array. |
| map | (callbackfn: (value: number, index: number, array: Uint8Array) => number, thisArg?: any) => Uint8Array | Calls a defined callback function on each element of an array, and returns an array that contains the results. |
| reduce | (callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: Uint8Array) => number) => number | Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function. |
| reduce | (callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: Uint8Array) => number, initialValue: number) => number | |
| reduce | <U>(callbackfn: (previousValue: U, currentValue: number, currentIndex: number, array: Uint8Array) => U, initialValue: U) => U | Calls the specified callback function for all the elements in an array. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function. |
| reduceRight | (callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: Uint8Array) => number) => number | Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function. |
| reduceRight | (callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: Uint8Array) => number, initialValue: number) => number | |
| reduceRight | <U>(callbackfn: (previousValue: U, currentValue: number, currentIndex: number, array: Uint8Array) => U, initialValue: U) => U | Calls the specified callback function for all the elements in an array, in descending order. The return value of the callback function is the accumulated result, and is provided as an argument in the next call to the callback function. |
| reverse | () => Uint8Array | Reverses the elements in an Array. |
| set | (array: ArrayLike<number>, offset?: number | undefined) => void | Sets a value or an array of values. |
| slice | (start?: number | undefined, end?: number | undefined) => Uint8Array | Returns a section of an array. |
| some | (predicate: (value: number, index: number, array: Uint8Array) => unknown, thisArg?: any) => boolean | Determines whether the specified callback function returns true for any element of an array. |
| sort | (compareFn?: ((a: number, b: number) => number) | undefined) => this | Sorts an array. |
| subarray | (begin?: number | undefined, end?: number | undefined) => Uint8Array | Gets a new Uint8Array view of the ArrayBuffer store for this array, referencing the elements at begin, inclusive, up to end, exclusive. |
| toLocaleString | () => string | Converts a number to a string by using the current locale. |
| toString | () => string | Returns a string representation of an array. |
| valueOf | () => Uint8Array | Returns the primitive value of the specified object. |
ArrayLike
| Prop | Type |
|---|---|
length | number |
ArrayBufferTypes
Allowed ArrayBuffer types for the buffer of an ArrayBufferView and related Typed Arrays.
| Prop | Type |
|---|---|
ArrayBuffer | ArrayBuffer |
ArrayBuffer
Represents a raw buffer of binary data, which is used to store data for the different typed arrays. ArrayBuffers cannot be read from or written to directly, but can be passed to a typed array or DataView Object to interpret the raw buffer as needed.
| Prop | Type | Description |
|---|---|---|
byteLength | number | Read-only. The length of the ArrayBuffer (in bytes). |
| Method | Signature | Description |
|---|---|---|
| slice | (begin: number, end?: number | undefined) => ArrayBuffer | Returns a section of an ArrayBuffer. |
ScanResult
| Prop | Type | Description |
|---|---|---|
device | BleDevice | The peripheral device that was found in the scan. Android and web: device.name is always identical to localName. iOS: device.name is identical to localName the first time a device is discovered, but after connecting device.name is the cached GAP name in subsequent scans. |
localName | string | The name of the peripheral device from the advertisement data. |
rssi | number | Received Signal Strength Indication. |
txPower | number | Transmit power in dBm. A value of 127 indicates that it is not available. |
manufacturerData | { [key: string]: DataView; } | Manufacturer data, key is a company identifier and value is the data. |
serviceData | { [key: string]: DataView; } | Service data, key is a service UUID and value is the data. |
uuids | string[] | Advertised services. |
rawAdvertisement | DataView | Raw advertisement data (Android only). |
DataView
| Prop | Type |
|---|---|
buffer | ArrayBuffer |
byteLength | number |
byteOffset | number |
| Method | Signature | Description |
|---|---|---|
| getFloat32 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Float32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. |
| getFloat64 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Float64 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. |
| getInt8 | (byteOffset: number) => number | Gets the Int8 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. |
| getInt16 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Int16 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. |
| getInt32 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Int32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. |
| getUint8 | (byteOffset: number) => number | Gets the Uint8 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. |
| getUint16 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Uint16 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. |
| getUint32 | (byteOffset: number, littleEndian?: boolean | undefined) => number | Gets the Uint32 value at the specified byte offset from the start of the view. There is no alignment constraint; multi-byte values may be fetched from any offset. |
| setFloat32 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Float32 value at the specified byte offset from the start of the view. |
| setFloat64 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Float64 value at the specified byte offset from the start of the view. |
| setInt8 | (byteOffset: number, value: number) => void | Stores an Int8 value at the specified byte offset from the start of the view. |
| setInt16 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Int16 value at the specified byte offset from the start of the view. |
| setInt32 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Int32 value at the specified byte offset from the start of the view. |
| setUint8 | (byteOffset: number, value: number) => void | Stores an Uint8 value at the specified byte offset from the start of the view. |
| setUint16 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Uint16 value at the specified byte offset from the start of the view. |
| setUint32 | (byteOffset: number, value: number, littleEndian?: boolean | undefined) => void | Stores an Uint32 value at the specified byte offset from the start of the view. |
TimeoutOptions
| Prop | Type | Description |
|---|---|---|
timeout | number | Timeout in milliseconds for plugin call. Default is 10000 for connect and 5000 for other plugin methods. |
BleService
| Prop | Type |
|---|---|
uuid | string |
characteristics | BleCharacteristic[] |
BleCharacteristic
| Prop | Type |
|---|---|
uuid | string |
properties | BleCharacteristicProperties |
descriptors | BleDescriptor[] |
BleCharacteristicProperties
| Prop | Type |
|---|---|
broadcast | boolean |
read | boolean |
writeWithoutResponse | boolean |
write | boolean |
notify | boolean |
indicate | boolean |
authenticatedSignedWrites | boolean |
reliableWrite | boolean |
writableAuxiliaries | boolean |
extendedProperties | boolean |
notifyEncryptionRequired | boolean |
indicateEncryptionRequired | boolean |
BleDescriptor
| Prop | Type |
|---|---|
uuid | string |
Type Aliases
ArrayBufferLike
ArrayBufferTypes[keyof ArrayBufferTypes]
Enums
ScanMode
| Members | Value | Description |
|---|---|---|
SCAN_MODE_LOW_POWER | 0 | Perform Bluetooth LE scan in low power mode. This mode is enforced if the scanning application is not in foreground. https://developer.android.com/reference/android/bluetooth/le/ScanSettings#SCAN_MODE_LOW_POWER |
SCAN_MODE_BALANCED | 1 | Perform Bluetooth LE scan in balanced power mode. (default) Scan results are returned at a rate that provides a good trade-off between scan frequency and power consumption. https://developer.android.com/reference/android/bluetooth/le/ScanSettings#SCAN_MODE_BALANCED |
SCAN_MODE_LOW_LATENCY | 2 | Scan using highest duty cycle. It's recommended to only use this mode when the application is running in the foreground. https://developer.android.com/reference/android/bluetooth/le/ScanSettings#SCAN_MODE_LOW_LATENCY |
ConnectionPriority
| Members | Value | Description |
|---|---|---|
CONNECTION_PRIORITY_BALANCED | 0 | Use the connection parameters recommended by the Bluetooth SIG. This is the default value if no connection parameter update is requested. https://developer.android.com/reference/android/bluetooth/BluetoothGatt#CONNECTION_PRIORITY_BALANCED |
CONNECTION_PRIORITY_HIGH | 1 | Request a high priority, low latency connection. An application should only request high priority connection parameters to transfer large amounts of data over LE quickly. Once the transfer is complete, the application should request CONNECTION_PRIORITY_BALANCED connection parameters to reduce energy use. https://developer.android.com/reference/android/bluetooth/BluetoothGatt#CONNECTION_PRIORITY_HIGH |
CONNECTION_PRIORITY_LOW_POWER | 2 | Request low power, reduced data rate connection parameters. https://developer.android.com/reference/android/bluetooth/BluetoothGatt#CONNECTION_PRIORITY_LOW_POWER |
UUID format
All UUIDs have to be provided in 128 bit format as string, e.g. '0000180d-0000-1000-8000-00805f9b34fb'. There is a helper function to convert 16 bit UUID numbers to string:
import { numberToUUID } from '@capacitor-community/bluetooth-le';
const HEART_RATE_SERVICE = numberToUUID(0x180d);
// '0000180d-0000-1000-8000-00805f9b34fb'
Troubleshooting
Connection fails on Android
On some Android devices connect() may fail when the device was connected before, even if the device is not actually connected.
In that case you should first call disconnect(), e.g.:
const device = await BleClient.requestDevice({
// ...
});
// ...
await BleClient.disconnect(device.deviceId);
await BleClient.connect(device.deviceId);
No devices found on Android
On Android, the initialize call requests the location permission. However, if location services are disable on the OS level, the app will not find any devices. You can check if the location is enabled and open the settings when not.
async function initialize() {
// Check if location is enabled
if (Capacitor.getPlatform() === 'android') {
const isLocationEnabled = await BleClient.isLocationEnabled();
if (!isLocationEnabled) {
await BleClient.openLocationSettings();
}
}
await BleClient.initialize();
}
Contributors ✨
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
FAQs
Capacitor plugin for Bluetooth Low Energy
The npm package @capacitor-community/bluetooth-le receives a total of 11,329 weekly downloads. As such, @capacitor-community/bluetooth-le popularity was classified as popular.
We found that @capacitor-community/bluetooth-le demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 47 open source maintainers collaborating on the project.
Package last updated on 07 May 2025
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Related posts
Research
Malicious fezbox npm Package Steals Browser Passwords from Cookies via Innovative QR Code Steganographic Technique
A malicious package uses a QR code as steganography in an innovative technique.
By Olivia Brown - Sep 22, 2025
Research
/Security News
Identifying and Preventing Fraudulent Engineering Candidates: An Investigation into 80 Confirmed Cases
Socket identified 80 fake candidates targeting engineering roles, including suspected North Korean operators, exposing the new reality of hiring as a security function.
By Lauren Valencia, Kirill Boychenko - Sep 17, 2025