react-native-ble-manager

npm version npm downloads GitHub issues

This is a porting of https://github.com/don/cordova-plugin-ble-central project to React Native.

Requirements

RN 0.60+

RN 0.40-0.59 supported until 6.7.X RN 0.30-0.39 supported until 2.4.3

Supported Platforms

Install

npm i --save react-native-ble-manager

The library support the autolink feature.

Android - Update Manifest
// file: android/app/src/main/AndroidManifest.xml
...
    <uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
...
iOS - Update Info.plist

In iOS >= 13 you need to add the NSBluetoothAlwaysUsageDescription string key.

Note

Example

The easiest way to test is simple make your AppRegistry point to our example component, like this:

// in your index.ios.js or index.android.js
import React, { Component } from "react";
import { AppRegistry } from "react-native";
import App from "react-native-ble-manager/example/App"; //<-- simply point to the example js!

AppRegistry.registerComponent("MyAwesomeApp", () => App);

Or, you can still look into the whole example folder for a standalone project.

Methods

start(options)

Init the module. Returns a Promise object. Don't call this multiple times.

Arguments

The parameter is optional the configuration keys are:

Examples

BleManager.start({ showAlert: false }).then(() => {
  // Success code
  console.log("Module initialized");
});

scan(serviceUUIDs, seconds, allowDuplicates, scanningOptions)

Scan for availables peripherals. Returns a Promise object.

Arguments

Examples

BleManager.scan([], 5, true).then(() => {
  // Success code
  console.log("Scan started");
});

stopScan()

Stop the scanning. Returns a Promise object.

Examples

BleManager.stopScan().then(() => {
  // Success code
  console.log("Scan stopped");
});

connect(peripheralId)

Attempts to connect to a peripheral. In many case if you can't connect you have to scan for the peripheral before. Returns a Promise object.

In iOS, attempts to connect to a peripheral do not time out (please see Apple's doc), so you might need to set a timer explicitly if you don't want this behavior.

Arguments

Examples

BleManager.connect("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
  .then(() => {
    // Success code
    console.log("Connected");
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

disconnect(peripheralId, force)

Disconnect from a peripheral. Returns a Promise object.

Arguments

Examples

BleManager.disconnect("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
  .then(() => {
    // Success code
    console.log("Disconnected");
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

enableBluetooth() [Android only]

Create the request to the user to activate the bluetooth. Returns a Promise object.

Examples

BleManager.enableBluetooth()
  .then(() => {
    // Success code
    console.log("The bluetooth is already enabled or the user confirm");
  })
  .catch((error) => {
    // Failure code
    console.log("The user refuse to enable bluetooth");
  });

checkState()

Force the module to check the state of BLE and trigger a BleManagerDidUpdateState event.

Examples

BleManager.checkState();

startNotification(peripheralId, serviceUUID, characteristicUUID)

Start the notification on the specified characteristic, you need to call retrieveServices method before. Returns a Promise object.

Arguments

Examples

BleManager.startNotification(
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
)
  .then(() => {
    // Success code
    console.log("Notification started");
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

startNotificationUseBuffer(peripheralId, serviceUUID, characteristicUUID, buffer) [Android only]

Start the notification on the specified characteristic, you need to call retrieveServices method before. The buffer will collect a number or messages from the server and then emit once the buffer count it reached. Helpful to reducing the number or js bridge crossings when a characteristic is sending a lot of messages. Returns a Promise object.

Arguments

Examples

BleManager.startNotification(
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  1234
)
  .then(() => {
    // Success code
    console.log("Notification started");
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

stopNotification(peripheralId, serviceUUID, characteristicUUID)

Stop the notification on the specified characteristic. Returns a Promise object.

Arguments

read(peripheralId, serviceUUID, characteristicUUID)

Read the current value of the specified characteristic, you need to call retrieveServices method before. Returns a Promise object.

Arguments

Examples

BleManager.read(
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
)
  .then((readData) => {
    // Success code
    console.log("Read: " + readData);

    const buffer = Buffer.Buffer.from(readData); //https://github.com/feross/buffer#convert-arraybuffer-to-buffer
    const sensorData = buffer.readUInt8(1, true);
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

write(peripheralId, serviceUUID, characteristicUUID, data, maxByteSize)

Write with response to the specified characteristic, you need to call retrieveServices method before. Returns a Promise object.

Arguments

Data preparation

If your data is not in byte array format you should convert it first. For strings you can use convert-string or other npm package in order to achieve that. Install the package first:

npm install convert-string

Then use it in your application:

// Import/require in the beginning of the file
import { stringToBytes } from "convert-string";
// Convert data to byte array before write/writeWithoutResponse
const data = stringToBytes(yourStringData);

Feel free to use other packages or google how to convert into byte array if your data has other format.

Examples

BleManager.write(
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  data
)
  .then(() => {
    // Success code
    console.log("Write: " + data);
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

writeWithoutResponse(peripheralId, serviceUUID, characteristicUUID, data, maxByteSize, queueSleepTime)

Write without response to the specified characteristic, you need to call retrieveServices method before. Returns a Promise object.

Arguments

Data preparation

If your data is not in byte array format check info for the write function above.

Example

BleManager.writeWithoutResponse(
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  data
)
  .then(() => {
    // Success code
    console.log("Writed: " + data);
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

readRSSI(peripheralId)

Read the current value of the RSSI. Returns a Promise object.

Arguments

Examples

BleManager.readRSSI("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
  .then((rssi) => {
    // Success code
    console.log("Current RSSI: " + rssi);
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

requestConnectionPriority(peripheralId, connectionPriority) [Android only API 21+]

Request a connection parameter update. Returns a Promise object.

Arguments

Examples

BleManager.requestConnectionPriority("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", 1)
  .then((status) => {
    // Success code
    console.log("Requested connection priority");
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

requestMTU(peripheralId, mtu) [Android only API 21+]

Request an MTU size used for a given connection. Returns a Promise object.

Arguments

Examples

BleManager.requestMTU("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", 512)
  .then((mtu) => {
    // Success code
    console.log("MTU size changed to " + mtu + " bytes");
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

retrieveServices(peripheralId[, serviceUUIDs])

Retrieve the peripheral's services and characteristics. Returns a Promise object.

Arguments

Examples

BleManager.retrieveServices("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX").then(
  (peripheralInfo) => {
    // Success code
    console.log("Peripheral info:", peripheralInfo);
  }
);

refreshCache(peripheralId) [Android only]

refreshes the peripheral's services and characteristics cache Returns a Promise object.

Arguments

Examples

BleManager.refreshCache("XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
  .then((peripheralInfo) => {
    // Success code
    console.log("cache refreshed!");
  })
  .catch((error) => {
    console.error(error);
  });

getConnectedPeripherals(serviceUUIDs)

Return the connected peripherals. Returns a Promise object.

Arguments

Examples

BleManager.getConnectedPeripherals([]).then((peripheralsArray) => {
  // Success code
  console.log("Connected peripherals: " + peripheralsArray.length);
});

createBond(peripheralId) [Android only]

Start the bonding (pairing) process with the remote device. Returns a Promise object. The promise is resolved when either new bond successfully created or bond already existed, otherwise it will be rejected.

Examples

BleManager.createBond(peripheralId)
  .then(() => {
    console.log("createBond success or there is already an existing one");
  })
  .catch(() => {
    console.log("fail to bond");
  });

removeBond(peripheralId) [Android only]

Remove a paired device. Returns a Promise object.

Examples

BleManager.removeBond(peripheralId)
  .then(() => {
    console.log("removeBond success");
  })
  .catch(() => {
    console.log("fail to remove the bond");
  });

getBondedPeripherals() [Android only]

Return the bonded peripherals. Returns a Promise object.

Examples

BleManager.getBondedPeripherals([]).then((bondedPeripheralsArray) => {
  // Each peripheral in returned array will have id and name properties
  console.log("Bonded peripherals: " + bondedPeripheralsArray.length);
});

getDiscoveredPeripherals()

Return the discovered peripherals after a scan. Returns a Promise object.

Examples

BleManager.getDiscoveredPeripherals([]).then((peripheralsArray) => {
  // Success code
  console.log("Discovered peripherals: " + peripheralsArray.length);
});

removePeripheral(peripheralId) [Android only]

Removes a disconnected peripheral from the cached list. It is useful if the device is turned off, because it will be re-discovered upon turning on again. Returns a Promise object.

Arguments

isPeripheralConnected(peripheralId, serviceUUIDs)

Check whether a specific peripheral is connected and return true or false. Returns a Promise object.

Examples

BleManager.isPeripheralConnected(
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  []
).then((isConnected) => {
  if (isConnected) {
    console.log("Peripheral is connected!");
  } else {
    console.log("Peripheral is NOT connected!");
  }
});

Events

BleManagerStopScan

The scanning for peripherals is ended.

Arguments

Examples

bleManagerEmitter.addListener("BleManagerStopScan", () => {
  // Scanning is stopped
});

BleManagerDidUpdateState

The BLE change state.

Arguments

Examples

bleManagerEmitter.addListener("BleManagerDidUpdateState", (args) => {
  // The new state: args.state
});

BleManagerDiscoverPeripheral

The scanning find a new peripheral.

Arguments

Examples

bleManagerEmitter.addListener("BleManagerDiscoverPeripheral", (args) => {
  // The id: args.id
  // The name: args.name
});

BleManagerDidUpdateValueForCharacteristic

A characteristic notify a new value.

Arguments

Event will only be emitted after successful startNotification.

Example

import { bytesToString } from "convert-string";
import { NativeModules, NativeEventEmitter } from "react-native";

const BleManagerModule = NativeModules.BleManager;
const bleManagerEmitter = new NativeEventEmitter(BleManagerModule);

async function connectAndPrepare(peripheral, service, characteristic) {
  // Connect to device
  await BleManager.connect(peripheral);
  // Before startNotification you need to call retrieveServices
  await BleManager.retrieveServices(peripheral);
  // To enable BleManagerDidUpdateValueForCharacteristic listener
  await BleManager.startNotification(peripheral, service, characteristic);
  // Add event listener
  bleManagerEmitter.addListener(
    "BleManagerDidUpdateValueForCharacteristic",
    ({ value, peripheral, characteristic, service }) => {
      // Convert bytes array to string
      const data = bytesToString(value);
      console.log(`Recieved ${data} for characteristic ${characteristic}`);
    }
  );
  // Actions triggereng BleManagerDidUpdateValueForCharacteristic event
}

BleManagerConnectPeripheral

A peripheral was connected.

Arguments

BleManagerDisconnectPeripheral

A peripheral was disconnected.

Arguments

BleManagerCentralManagerWillRestoreState [iOS only]

This is fired when centralManager:WillRestoreState: is called (app relaunched in the background to handle a bluetooth event).

Arguments

For more on performing long-term bluetooth actions in the background:

iOS Bluetooth State Preservation and Restoration

iOS Relaunch Conditions