Announcing the Capacitor Bluetooth Low Energy Plugin¶

Today we are excited to announce our brand new Capacitor Bluetooth Low Energy plugin. This plugin enables interaction with Bluetooth Low Energy (BLE) devices in the central role and provides cross-platform support for Android and iOS. The project is now available for all Capawesome Insiders.

Let's take a quick look at the API and how you can use the pugin to communicate with BLE devices.

Installation¶

See Getting started with Insiders and follow the instructions to install the plugin.

After that, follow the platform-specific instructions in the sections Android and iOS.

Android¶

On Android, the plugin usually requires at least the following permissions be added to your AndroidManifest.xml before the application tag:

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

You can read more about Bluetooth permissions in the Android documentation.

You also need to add the following service inside the application tag in your AndroidManifest.xml (usually android/app/src/main/AndroidManifest.xml):

<service android:name="io.capawesome.capacitorjs.plugins.bluetoothle.BluetoothLowEnergyService" android:foregroundServiceType="connectedDevice" />

iOS¶

On iOS, add the NSBluetoothPeripheralUsageDescription and NSBluetoothAlwaysUsageDescription keys to the Info.plist file (usually ios/App/App/Info.plist), which tells the user why the app needs access to Bluetooth peripherals:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>The app needs access to Bluetooth peripherals to communicate with Bluetooth devices.</string>

If the app wants to use Bluetooth in the background, add the UIBackgroundModes key with the bluetooth-central value:

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

Usage¶

Let's take a look at the basic usage of the plugin.

Initialize the plugin¶

First, you need to initialize the plugin and request the necessary permissions:

import { BluetoothLowEnergy } from "@capawesome-team/capacitor-bluetooth-low-energy";
import { Capacitor } from "@capacitor/core";

const initialize = async () => {
  if (Capacitor.getPlatform() === "ios") {
    await BluetoothLowEnergy.initialize();
  } else {
    await BluetoothLowEnergy.requestPermissions();
  }
};

In this context, there are differences between Android and iOS. On iOS, you need to call the initialize method to initialize the plugin every time the app starts. On Android, you need to call the requestPermissions method to request the necessary permissions.

Scan for devices¶

Before you can connect to a device for the first time, you need to scan for devices. For this, you can use the startScan:

import { BluetoothLowEnergy } from "@capawesome-team/capacitor-bluetooth-low-energy";

const startScan = async () => {
  await BluetoothLowEnergy.addListener("deviceScanned", (event) => {
    console.log("Device scanned", event.device);
  });
  await BluetoothLowEnergy.startScan();
};

const stopScan = async () => {
  await BluetoothLowEnergy.stopScan();
};

Every time a device is found, the deviceScanned event is emitted. You can now display the found devices to your users and let them select the device they want to connect to. As soon as the user has selected a device, you should stop the scan with stopScan.

Connect to a device¶

To connect to a device, you can use the connect method:

import { BluetoothLowEnergy } from "@capawesome-team/capacitor-bluetooth-low-energy";

const connect = async (deviceId: string) => {
  await BluetoothLowEnergy.connect({ deviceId });
};

You just need to pass the deviceId of the device you want to connect to. The deviceId is the address of the device (e.g. 00:11:22:33:AA:BB) and is usually provided by the deviceScanned event.

Reconnect to a device

You don't need to scan for devices every time you want to connect to a device. You can simply save the deviceId of the device and use it to reconnect to the device later.

Communicate with a device¶

Before you can communicate with a device, you need to discover the services and characteristics of the device. For this, you can use the discoverServices method:

import { BluetoothLowEnergy } from "@capawesome-team/capacitor-bluetooth-low-energy";

const discoverServices = async () => {
  await BluetoothLowEnergy.discoverServices();
};

Use the getServices method to get a list of all services, characteristics, and descriptors of the device:

import { BluetoothLowEnergy } from "@capawesome-team/capacitor-bluetooth-low-energy";

const getServices = async () => {
  const { services } = await BluetoothLowEnergy.getServices();
  console.log("Services: ", services);
};

Now you can read, write, and subscribe to characteristics and descriptors using the following methods:

This is an example of how to read a characteristic value:

import { BluetoothLowEnergy } from "@capawesome-team/capacitor-bluetooth-low-energy";

const readCharacteristic = async (characteristicId: string) => {
  const { value } = await BluetoothLowEnergy.readCharacteristic({ characteristicId });
  console.log("Value: ", value); // e.g. [1, 2, 3, 4]
};

Values are exchanged as byte arrays. You can convert them to a hex string using the convertBytesToHex method:

import { BluetoothLowEnergyUtils } from "@capawesome-team/capacitor-bluetooth-low-energy";

const convertBytesToHex = async (bytes: number[]) => {
  const { hex } = await BluetoothLowEnergyUtils.convertBytesToHex({ bytes });
  console.log("Hex: ", hex); // e.g. "01020304"
};

Disconnect from a device¶

To disconnect from a device, you simply need to call the disconnect method:

import { BluetoothLowEnergy } from "@capawesome-team/capacitor-bluetooth-low-energy";

const disconnect = async () => {
  await BluetoothLowEnergy.disconnect();
};

Closing Thoughts¶

We hope you are as excited as we are about the new Capacitor Bluetooth Low Energy plugin. Be sure to check out the API Reference to see what else you can do with this plugin. If you are missing any features, just create a feature request in the GitHub repository. Make sure you follow us on X so you don't miss any future updates.