---
title: Announcing the Capacitor Bluetooth Low Energy Plugin
description: The Capacitor Bluetooth Low Energy plugin enables interaction with Bluetooth Low Energy (BLE) devices in the central and peripheral role.
date:
  created: 2024-05-20
  updated: 2026-07-10
authors:
  - robingenz
categories:
  - Announcements
  - Capacitor
  - SDKs
links:
  - Capacitor Bluetooth Low Energy: sdks/capacitor/bluetooth-low-energy.md
faq: true
---

# Capacitor BLE Plugin: Bluetooth Low Energy

Building an app that talks to a smart device — a wearable, a sensor, a beacon, or your own hardware? The [Capacitor Bluetooth Low Energy plugin](../../sdks/capacitor/bluetooth-low-energy.md) lets your app act as both a BLE central (connecting to devices) and a BLE peripheral (advertising to others), with cross-platform support for Android and iOS. It's available to all Capawesome [Insiders](../../insiders/index.md).

<!-- more -->

Let's take a quick look at the [API](../../sdks/capacitor/bluetooth-low-energy.md#api) and how you can use the plugin to communicate with BLE devices.

## Installation

To install the Capacitor Bluetooth Low Energy plugin, please refer to the [Installation](../../sdks/capacitor/bluetooth-low-energy.md/#installation) section in the plugin documentation.

## Usage

Let's take a look at the basic usage of the plugin. The plugin supports two roles:

- **Central role**: The app acts as a central device that can connect to and communicate with peripheral devices.
- **Peripheral role**: The app acts as a peripheral device that can advertise its services and accept connections from central devices.

The plugin supports both roles on Android and iOS.
The following sections will show you how to use the plugin in both roles.

### Central role

The central role allows you to connect to and communicate with BLE devices.

#### Initialize the plugin

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

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

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

In this context, there are differences between Android and iOS.
On **iOS**, you need to call the [`initialize`](../../sdks/capacitor/bluetooth-low-energy.md#initialize) method to initialize the plugin every time the app starts.
On **Android**, you need to call the [`requestPermissions`](../../sdks/capacitor/bluetooth-low-energy.md#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`](../../sdks/capacitor/bluetooth-low-energy.md#startscan):

```typescript
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`](../../sdks/capacitor/bluetooth-low-energy.md#stopscan).

#### Connect to a device

To connect to a device, you can use the [`connect`](../../sdks/capacitor/bluetooth-low-energy.md#connect) method:

```typescript
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.

???+ tip "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`](../../sdks/capacitor/bluetooth-low-energy.md#discoverservices) method:

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

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

Use the [`getServices`](../../sdks/capacitor/bluetooth-low-energy.md#getservices) method to get a list of all services, characteristics, and descriptors of the device:

```typescript
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:

- [`readCharacteristic`](../../sdks/capacitor/bluetooth-low-energy.md#readcharacteristic)
- [`writeCharacteristic`](../../sdks/capacitor/bluetooth-low-energy.md#writecharacteristic)
- [`startCharacteristicNotifications`](../../sdks/capacitor/bluetooth-low-energy.md#startcharacteristicnotifications)
- [`stopCharacteristicNotifications`](../../sdks/capacitor/bluetooth-low-energy.md#stopcharacteristicnotifications)
- [`readDescriptor`](../../sdks/capacitor/bluetooth-low-energy.md#readdescriptor)
- [`writeDescriptor`](../../sdks/capacitor/bluetooth-low-energy.md#writedescriptor)

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

```typescript
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`](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/bluetooth-low-energy/docs/utils/README.md){:target="_blank"} method:

```typescript
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`](../../sdks/capacitor/bluetooth-low-energy.md#disconnect) method:

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

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

### Peripheral role

The peripheral role allows you to advertise your app as a BLE device and accept connections from central devices.

#### Initialize the plugin

The initialization process is the same as in the central role.
You need to call the [`initialize`](../../sdks/capacitor/bluetooth-low-energy.md#initialize) method on iOS and the [`requestPermissions`](../../sdks/capacitor/bluetooth-low-energy.md#requestpermissions) method on Android.

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

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

#### Start advertising

To start advertising your app as a BLE device, you can use the [`startAdvertising`](../../sdks/capacitor/bluetooth-low-energy.md#startadvertising) method:

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

const startAdvertising = async () => {
  await BluetoothLowEnergy.startAdvertising({
    name: "CapBLE",
    services: [
      {
        id: "12345678-1234-1234-1234-1234567890AB",
        characteristics: [
          {
            id: "87654321-4321-4321-4321-BA0987654321",
            descriptors: [],
            permissions: {
              read: true,
              write: true,
            },
            properties: {
              indicate: true,
              notify: true,
              read: true,
              write: true,
            },
          },
        ],
      },
    ],
  });
};
```

The `startAdvertising` method allows you to specify the name of the peripheral and the services it provides.
The services can include characteristics with various properties and permissions.

#### Communicate with a device

After starting advertising, devices can connect to your app.
You can listen to the `deviceConnected` event to get notified when a device connects to your app:

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

const addListener = async () => {
  await BluetoothLowEnergy.addListener("deviceConnected", (event) => {
    console.log("Device connected", event.deviceId);
  });
};
```

You can also listen to the `deviceDisconnected` event to get notified when a device disconnects from your app:

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

const addListener = async () => {
  await BluetoothLowEnergy.addListener("deviceDisconnected", (event) => {
    console.log("Device disconnected", event.deviceId);
  });
};
```

Read requests from devices are handled automatically by the plugin.
You can use the [`setCharacteristicValue`](../../sdks/capacitor/bluetooth-low-energy.md#setcharacteristicvalue) method to set or update the value of a characteristic:

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

const setCharacteristicValue = async () => {
  await BluetoothLowEnergy.setCharacteristicValue({
    characteristicId: "87654321-4321-4321-4321-BA0987654321",
    serviceId: "12345678-1234-1234-1234-1234567890AB",
    value: [1, 2, 3, 4], // Value byte array
  });
};
```

If a device wants to write a value to a characteristic, the plugin will emit the `characteristicWriteRequest` event.
You can listen to this event and respond to the write request using the [`setCharacteristicValue`](../../sdks/capacitor/bluetooth-low-energy.md#setcharacteristicvalue) method:

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

const addListener = async () => {
  await BluetoothLowEnergy.addListener(
    "characteristicWriteRequest",
    (event) => {
      console.log("Characteristic write request", event);
      // Respond to the write request
      void BluetoothLowEnergy.setCharacteristicValue({
        characteristicId: event.characteristicId,
        serviceId: event.serviceId,
        value: event.value,
      });
    }
  );
};
```

## FAQ

### Which platforms does the Capacitor Bluetooth Low Energy plugin support?

The plugin supports Android and iOS in both the central and peripheral role.

### Can my app act as a BLE peripheral, not just a central?

Yes. In the **central** role your app scans for and connects to other BLE devices; in the **peripheral** role your app advertises its own services and accepts connections from central devices. Both roles are supported on Android and iOS.

### How do I read and write characteristic values?

After connecting to a device and calling `discoverServices()`, use `readCharacteristic` and `writeCharacteristic`, and subscribe to updates with `startCharacteristicNotifications`. Values are exchanged as byte arrays, which you can convert to a hex string with `convertBytesToHex`.

### Do I need to scan for a device every time I connect?

No. Once you know a device's `deviceId`, you can save it and reconnect later with `connect({ deviceId })` without scanning again.

## Closing Thoughts

The [Capacitor Bluetooth Low Energy plugin](../../sdks/capacitor/bluetooth-low-energy.md) supports the full BLE workflow in both roles — scanning, connecting, discovering services, and reading, writing, and subscribing to characteristics — across Android and iOS.

**Related reading:**

- [API Reference](../../sdks/capacitor/bluetooth-low-energy.md#api) — the full method and event reference
- [Capacitor NFC plugin: read and write NFC tags](./announcing-the-capacitor-nfc-plugin.md) — another Capawesome plugin for device communication

**Missing a feature?** [Create a feature request](https://github.com/capawesome-team/capacitor-plugins/issues/new/choose){:target="_blank"} in our [GitHub repository](https://github.com/capawesome-team/capacitor-plugins){:target="_blank"}.

Join the Capawesome [Discord](https://discord.gg/VCXxSVjefW){:target="_blank"} server for questions and subscribe to the Capawesome [newsletter](https://capawesome.io/newsletter/){:target="_blank"} to stay updated.