Capacitor Community Bluetooth Low Energy

Instead of using the BluetoothLe plugin class directly, it is highly recommended to use the BleClient wrapper class. BleClient provides a more developer-friendly API by making events and method arguments easier to work with.

import { BleClient } from '@capacitor-community/bluetooth-le';

// Import the wrapper class
import { BleClient } from '@capacitor-community/bluetooth-le';

To install the Bluetooth Low Energy plugin in your Capacitor project, use npm to add the package and then sync your project files.

npm install @capacitor-community/bluetooth-le
npx cap sync

The @capacitor-community/bluetooth-le plugin provides a unified API for interacting with Bluetooth Low Energy devices on iOS, Android, and Web. To use the plugin, import the core functionality from the package. The main entry point exports all necessary definitions, the BLE client implementation, conversion utilities, and configuration options.

import { BleClient } from '@capacitor-community/bluetooth-le';

// The plugin is typically used via the BleClient class

When initializing the plugin on Android, if your application does not use Bluetooth scan results to derive physical location information, you can set androidNeverForLocation to true.

Note: This requires adding neverForLocation to your AndroidManifest.xml to comply with Android's permission model.

// Example initialization option
await BleClient.initialize({
  androidNeverForLocation: true
});

A ScanResult contains detailed information about a device found during a scan.

• device: The BleDevice object.
• localName: The name from the advertisement data.
• rssi: Received Signal Strength Indication.
• txPower: Transmit power in dBm (127 if unavailable).
• manufacturerData: A map where keys are company identifiers and values are DataView objects.
• serviceData: A map where keys are service UUIDs and values are DataView objects.
• uuids: Advertised service UUIDs.
• rawAdvertisement: (Android only) The raw DataView of the advertisement.

You can customize the text shown in the device selection dialog on iOS and Android (used during requestDevice()) via capacitor.config.json or at runtime using setDisplayStrings(...).

Available keys in the displayStrings object:

• scanning: Text shown while scanning.
• cancel: Text for the cancel button.
• availableDevices: Header text for the list of devices.
• noDeviceFound: Text shown when no devices are detected.

{
  "plugins": {
    "BluetoothLe": {
      "displayStrings": {
        "scanning": "Am Scannen...",
        "cancel": "Abbrechen",
        "availableDevices": "Verfügbare Geräte",
        "noDeviceFound": "Kein Gerät gefunden"
      }
    }
  }
}

To interact with characteristics or descriptors, use the read and write methods.

Note on Data Types:

• For write and writeDescriptor, the value type depends on the platform:
  • Android/iOS: string
  • Web: DataView
• For read and readDescriptor, the returned value follows the same platform pattern.

Common Options: Both operations accept TimeoutOptions to specify a timeout in milliseconds (defaults to 5000ms for these methods).

// Example Write
await BluetoothLePlugin.write({
  deviceId: 'MY_DEVICE_ID',
  service: '0000180d-0000-1000-8000-00805f9b34fb',
  characteristic: '00002a37-0000-1000-8000-00805f9b34fb',
  value: 'some_value_or_data_view',
  timeout: 2000
});

On Android, BleClient.initialize() requests location permissions. However, if location services are disabled at the OS level, the app will not find any devices. You should check if location is enabled using BleClient.isLocationEnabled() and, if not, prompt the user to enable it using BleClient.openLocationSettings().

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();
}

On some Android devices, BleClient.connect() may fail if the device was previously connected, even if it is not currently active. To resolve this, explicitly call BleClient.disconnect() using the deviceId before attempting to connect.

const device = await BleClient.requestDevice({
   // ...
});
// ...
await BleClient.disconnect(device.deviceId);
await BleClient.connect(device.deviceId);