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, andble.stopScanble.connect,ble.autoConnect, andble.disconnectble.read,ble.write, andble.writeWithoutResponseble.startNotificationandble.stopNotificationble.isEnabled,ble.isConnected,ble.requestMtu, andble.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 |
Links and next steps
- Plugin docs: https://capgo.app/docs/plugins/bluetooth-low-energy/
- Marketing page: /plugins/capacitor-bluetooth-low-energy/
- npm: https://www.npmjs.com/package/@capgo/capacitor-bluetooth-low-energy
- GitHub: https://github.com/Cap-go/capacitor-bluetooth-low-energy/
- Cordova upstream: https://github.com/don/cordova-plugin-ble-central
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.