Skip to main content

cordova-plugin-ble-central Alternative for Capacitor

cordova-plugin-ble-central alternative for Capacitor: @capgo/capacitor-bluetooth-low-energy with scan, connect, read/write, notifications, and permission helpers instead of ble.* callbacks.

Illustration of migrating a Cordova app to Capacitor, used for a Bluetooth Low Energy plugin guide

The practical cordova-plugin-ble-central alternative for a Capacitor app is @capgo/capacitor-bluetooth-low-energy. It replaces the global ble callback API with promises, permission helpers, and listeners for scans, connections, and characteristic changes. This guide lists npm facts, install steps, usage, and an API map for your Cordova to Capacitor move.

Why move off cordova-plugin-ble-central in Capacitor

cordova-plugin-ble-central on npm is version 2.1.0. The registry modified timestamp is 18 November 2026. The npm repository URL points to don/cordova-plugin-ble-central.

The README documents a global ble object with callback style methods such as:

  • ble.scan, ble.startScan, ble.startScanWithOptions, and ble.stopScan
  • ble.connect, ble.autoConnect, and ble.disconnect
  • ble.read, ble.write, and ble.writeWithoutResponse
  • ble.startNotification and ble.stopNotification
  • ble.isEnabled, ble.isConnected, ble.requestMtu, and ble.readRSSI

Those calls assume Cordova deviceready wiring and per-call success and failure functions.

@capgo/capacitor-bluetooth-low-energy latest on npm is 8.2.9 with a modified date of 12 November 2026. src/definitions.ts documents initialize, startScan, stopScan, connect, disconnect, readCharacteristic, writeCharacteristic with optional type: 'withoutResponse', startCharacteristicNotifications, requestMtu, readRssi, and listeners such as deviceScanned and characteristicChanged. Capgo ships fixes on an open source cadence where a human still reviews, tests and merges 50+ pull requests daily.

After you migrate BLE flows, regression-test OTA builds with the checklist for validating Capacitor app updates so scan and reconnect behavior survives each live update channel.

Install

bun add @capgo/capacitor-bluetooth-low-energy
bunx cap sync

Add the Bluetooth usage strings from the plugin README to Info.plist and declare Android BLUETOOTH_SCAN, BLUETOOTH_CONNECT, and location permissions as required for your scan mode.

Usage example

import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

export async function subscribeHeartRate(deviceId: string) {
  await BluetoothLowEnergy.initialize({ mode: 'central' });
  await BluetoothLowEnergy.requestPermissions();

  await BluetoothLowEnergy.connect({ deviceId });

  await BluetoothLowEnergy.startCharacteristicNotifications({
    deviceId,
    service: '180D',
    characteristic: '2A37',
  });

  const handle = await BluetoothLowEnergy.addListener('characteristicChanged', (event) => {
    if (event.deviceId === deviceId && event.characteristic === '2A37') {
      return event.value;
    }
  });

  return handle;
}

Migrating from Cordova to Capacitor

// Before (Cordova)
ble.scan([], 5, function (device) {
  console.log(device.id, device.name);
}, function (err) {
  console.error(err);
});
// After (Capacitor)
import { BluetoothLowEnergy } from '@capgo/capacitor-bluetooth-low-energy';

await BluetoothLowEnergy.initialize({ mode: 'central' });

const listener = await BluetoothLowEnergy.addListener('deviceScanned', ({ device }) => {
  console.log(device.deviceId, device.name);
});

await BluetoothLowEnergy.startScan({ timeout: 5000 });

await new Promise((resolve) => setTimeout(resolve, 5000));

await BluetoothLowEnergy.stopScan();
await listener.remove();
// Before (Cordova)
ble.startNotification(
  deviceId,
  service,
  characteristic,
  function (data) {
    console.log(data);
  },
  function (err) {
    console.error(err);
  },
);
// After (Capacitor)
await BluetoothLowEnergy.startCharacteristicNotifications({
  deviceId,
  service,
  characteristic,
});

await BluetoothLowEnergy.addListener('characteristicChanged', (event) => {
  if (event.deviceId === deviceId) console.log(event.value);
});

API mapping table

cordova-plugin-ble-central (ble) @capgo/capacitor-bluetooth-low-energy
ble.startScan(services, success, failure) startScan({ services, timeout, ... }) plus addListener('deviceScanned', ...)
ble.scan(services, seconds, success, failure) startScan({ timeout: seconds * 1000 })
ble.stopScan(success, failure) stopScan()
ble.connect(deviceId, success, failure) connect({ deviceId })
ble.autoConnect(deviceId, success, failure) connect({ deviceId, autoConnect: true })
ble.disconnect(deviceId, success, failure) disconnect({ deviceId })
ble.isConnected(deviceId, success, failure) Use addListener('deviceConnected') and addListener('deviceDisconnected') plus connect promise results
ble.read(deviceId, service, characteristic, success, failure) readCharacteristic({ deviceId, service, characteristic }) returns { value } as byte array
ble.write(deviceId, service, characteristic, data, success, failure) writeCharacteristic({ deviceId, service, characteristic, value, type: 'withResponse' })
ble.writeWithoutResponse(...) writeCharacteristic({ ..., type: 'withoutResponse' })
ble.startNotification(...) startCharacteristicNotifications({ deviceId, service, characteristic }) plus addListener('characteristicChanged', ...)
ble.stopNotification(...) stopCharacteristicNotifications({ deviceId, service, characteristic })
ble.isEnabled(success, failure) isEnabled() returns { enabled }
ble.requestMtu(deviceId, mtu, success, failure) requestMtu({ deviceId, mtu })
ble.readRSSI(deviceId, success, failure) readRssi({ deviceId })
ble.bond / ble.setPin (Android) createBond({ deviceId }) and related bond helpers
device.id in scan callback device.deviceId in deviceScanned events
Cordova plugin install bun add @capgo/capacitor-bluetooth-low-energy plus bunx cap sync

Pair firmware-tested native builds from Capgo Build with staged BLE UI rollouts through Capgo live updates. For the full platform move, read the Cordova to Capacitor migration guide.

Live updates for Capacitor apps

When a web-layer bug is live, ship the fix through Capgo instead of waiting days for app store approval. Users get the update in the background while native changes stay in the normal review path.

Latest from our Blog

Capgo gives you the best insights you need to create a truly professional mobile app.