Table of contents

Common (iOS & Android)
Android-only
iOS-only
1. getMaximumWriteValueLengthForWithoutResponse(peripheralId) [iOS only]
2. getMaximumWriteValueLengthForWithResponse(peripheralId) [iOS only]

Methods

Common (iOS & Android)

These APIs are available on both platforms.

start(options)

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

Arguments

options - JSON

The parameter is optional the configuration keys are:

showAlert - Boolean - [iOS only] Show or hide the alert if the bluetooth is turned off during initialization
restoreIdentifierKey - String - [iOS only] Unique key to use for CoreBluetooth state restoration
queueIdentifierKey - String - [iOS only] Unique key to use for a queue identifier on which CoreBluetooth events will be dispatched
forceLegacy - Boolean - [Android only] Force to use the LegacyScanManager

Examples

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

isStarted()

Returns if the module was initialised with start.

Examples

BleManager.isStarted().then((started) => {
  // Success code
  console.log(`Module is ${isStarted ? '' : 'not '}started`);
});

scan(scanningOptions)

Scan for available peripherals. Returns a Promise object.

Arguments

scanningOptions - JSON - user can control specific ble scan behaviors:
- serviceUUIDs - Array of String - the UUIDs of the services to looking for.
- seconds - Integer - the amount of seconds to scan.
- allowDuplicates - Boolean - [iOS only] allow duplicates in device scanning
- numberOfMatches - Number - [Android only] corresponding to setNumOfMatches. Defaults to ScanSettings.MATCH_NUM_MAX_ADVERTISEMENT. /!\ anything other than default may only work when a ScanFilter is active /!\
- matchMode - Number - [Android only] corresponding to setMatchMode. Defaults to ScanSettings.MATCH_MODE_AGGRESSIVE.
- callbackType - Number - [Android only] corresponding to setCallbackType. Defaults ScanSettings.CALLBACK_TYPE_ALL_MATCHES. /!\ anything other than default may only work when a ScanFilter is active /!\
- scanMode - Number - [Android only] corresponding to setScanMode. Defaults to ScanSettings.SCAN_MODE_LOW_POWER.
- reportDelay - Number - [Android only] corresponding to setReportDelay. Defaults to 0ms.
- phy - Number - [Android only] corresponding to setPhy
- legacy - Boolean - [Android only] corresponding to setLegacy
- exactAdvertisingName - string[] - In Android corresponds to the ScanFilter deviceName. In iOS the filter is done manually before sending the peripheral.
- manufacturerData - object - [Android only] corresponding to setManufacturerData. Filter by manufacturer id or data.
  - manufacturerId - number - Manufacturer / company id to filter for.
  - manufacturerData - number[] - Additional manufacturer data filter.
  - manufacturerDataMask - number[] - Mask for manufacturer data, must have the same length as manufacturerData. For any bit in the mask, set it to 1 if it needs to match the one in manufacturer data, otherwise set it to 0.
- useScanIntent - Boolean - [Android only, API 26+] deliver scan results through a PendingIntent instead of the default callback. Any ongoing callback scan is automatically stopped before switching to this mode.

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, options)

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

peripheralId - String - the id/mac address of the peripheral to connect.
options - JSON - The parameter is optional the configuration keys are:
- phy - Number - [Android only] corresponding to the preferred phy channel (Android doc)
- autoconnect - Boolean - [Android only] whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true) (Android doc)

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

peripheralId - String - the id/mac address of the peripheral to disconnect.
force - boolean - [Android only] defaults to true, if true force closes gatt connection and send the BleManagerDisconnectPeripheral event immediately to Javascript, else disconnects the connection and waits for disconnected state to close the gatt connection and then sends the BleManagerDisconnectPeripheral to the Javascript

Examples

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

checkState()

Force the module to check the state of the native BLE manager and trigger a BleManagerDidUpdateState event. Resolves to a promise containing the current BleState.

Examples

BleManager.checkState().then((state) =>
  console.log(`current BLE state = '${state}'.`)
);

startNotification(peripheralId, serviceUUID, characteristicUUID)

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

Arguments

peripheralId - String - the id/mac address of the peripheral.
serviceUUID - String - the UUID of the service.
characteristicUUID - String - the UUID of the characteristic.

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);
  });

stopNotification(peripheralId, serviceUUID, characteristicUUID)

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

Arguments

peripheralId - String - the id/mac address of the peripheral.
serviceUUID - String - the UUID of the service.
characteristicUUID - String - the UUID of the characteristic.

read(peripheralId, serviceUUID, characteristicUUID)

Read the current value of the specified characteristic, you need to call retrieveServices method before. Returns a Promise object that will resolves to an array of plain integers (number[]) representing a ByteArray structure. That array can then be converted to a JS ArrayBuffer for example using Buffer.from() thanks to this buffer module.

Arguments

peripheralId - String - the id/mac address of the peripheral.
serviceUUID - String - the UUID of the service.
characteristicUUID - String - the UUID of the characteristic.

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);

    // https://github.com/feross/buffer
    // https://nodejs.org/api/buffer.html#static-method-bufferfromarray
    const buffer = Buffer.from(readData);
    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

peripheralId - String - the id/mac address of the peripheral.
serviceUUID - String - the UUID of the service.
characteristicUUID - String - the UUID of the characteristic.
data - number[] - the data to write as a plain integer array representing a ByteArray structure.
maxByteSize - Integer - specify the max byte size before splitting message, defaults to 20 bytes if not specified

Data preparation

To convert your data to a number[], you should probably be manipulating a Buffer or anything representing a JS ArrayBuffer. This will make sure you are converting from valid byte representations of your data first and not with an integer outside the expected range.

You can create a buffer from files, numbers or strings easily (see examples bellow).

// https://github.com/feross/buffer
import { Buffer } from 'buffer';

 * // Creates a Buffer containing the bytes [0x01, 0x02, 0x03].
 * const buffer = Buffer.from([1, 2, 3]);
 *
 * // Creates a Buffer containing the bytes [0x01, 0x01, 0x01, 0x01] – the entries
 * // are all truncated using `(value & 255)` to fit into the range 0–255.
 * const buffer = Buffer.from([257, 257.5, -255, '1']);
 *
 * // Creates a Buffer containing the UTF-8-encoded bytes for the string 'tést':
 * // [0x74, 0xc3, 0xa9, 0x73, 0x74] (in hexadecimal notation)
 * // [116, 195, 169, 115, 116] (in decimal notation)
 * const buffer = Buffer.from('tést');

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",
  // encode & extract raw `number[]`.
  // Each number should be in the 0-255 range as it is converted from a valid byte.
  buffer.toJSON().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

peripheralId - String - the id/mac address of the peripheral.
serviceUUID - String - the UUID of the service.
characteristicUUID - String - the UUID of the characteristic.
data - number[] - the data to write as a plain integer array representing a ByteArray structure. (see write()).
maxByteSize - Integer - (Optional) specify the max byte size
queueSleepTime - Integer - (Optional) specify the wait time before each write if the data is greater than maxByteSize

Data preparation

If your data is not in number[] format check info fom the write() function example 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("Wrote: " + data);
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

readRSSI(peripheralId)

Read the current value of the RSSI. Returns a Promise object resolving with the updated RSSI value (number) if it succeeds.

Arguments

peripheralId - String - the id/mac address of the peripheral.

Examples

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

readDescriptor(peripheralId, serviceId, characteristicId, descriptorId)

Read the current value of the specified descriptor, you need to call retrieveServices method before. Returns a Promise object that will resolves to an array of plain integers (number[]) representing a ByteArray structure. That array can then be converted to a JS ArrayBuffer for example using Buffer.from() thanks to this buffer module.

Arguments

peripheralId - String - the id/mac address of the peripheral.
serviceUUID - String - the UUID of the service.
characteristicUUID - String - the UUID of the characteristic.
descriptorUUID - String - the UUID of the descriptor.

Examples

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

    // https://github.com/feross/buffer
    // https://nodejs.org/api/buffer.html#static-method-bufferfromarray
    const buffer = Buffer.from(readData);
    const sensorData = buffer.readUInt8(1, true);
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

writeDescriptor(peripheralId, serviceId, characteristicId, descriptorId, data)

Write a value to the specified descriptor, you need to call retrieveServices method before. Returns a Promise object.

Arguments

peripheralId - String - the id/mac address of the peripheral.
serviceUUID - String - the UUID of the service.
characteristicUUID - String - the UUID of the characteristic.
descriptorUUID - String - the UUID of the descriptor.
data - number[] - the data to write as a plain integer array representing a ByteArray structure.

Examples

BleManager.writeDescriptor(
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "XXXX",
  [1, 2]
)
  .then(() => {
    // Success code
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

retrieveServices(peripheralId[, serviceUUIDs])

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

Arguments

peripheralId - String - the id/mac address of the peripheral.
serviceUUIDs - String[] - [iOS only] only retrieve these services.

Examples

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

getConnectedPeripherals(serviceUUIDs)

Return the connected peripherals. Returns a Promise object.

In Android, Peripherals “advertising” property can be not set! Will be available if peripheral was found through scan before connect. This matches to current Android Bluetooth design specification.

Arguments

serviceUUIDs - Array of String - the UUIDs of the services to look for.

Examples

BleManager.getConnectedPeripherals([]).then((peripheralsArray) => {
  // Success code
  console.log("Connected peripherals: " + peripheralsArray.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);
});

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!");
  }
});

isScanning()

Checks whether the scan is in progress and return true or false. Returns a Promise object.

Examples

BleManager.isScanning().then((isScanning) => {
  if (isScanning) {
    console.log("Is scanning!");
  } else {
    console.log("Is NOT scanning!");
  }
});

Android-only

APIs that require Android; many expose platform concepts like ScanSettings, bonding, or adapter state.

companionScan() [Android only, API 26+]

Scan for companion devices.

If companion device manager is not supported on this (android) device rejects.

The promise it will eventually resolve with either:

peripheral if user selects one
null if user “cancels” (i.e. doesn’t select anything)

See BleManager.supportsCompanion.

See: https://developer.android.com/develop/connectivity/bluetooth/companion-device-pairing

Arguments

serviceUUIDs - String[] - List of service UUIDs to use as a filter
options - JSON - Additional options
- single - String? - Scan only for single peripheral. See Android’s AssocationRequest.Builder.setSingleDevice.

Examples

BleManager.compationScan([]).then(peripheral => {
  console.log('Associated peripheral', peripheral);
});

enableBluetooth() [Android only]

Create the ACTION_REQUEST_ENABLE to ask 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");
  });

supportsCompanion() [Android only]

Check if current device supports companion device manager.

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

Start the notification on the specified characteristic, you need to call retrieveServices method before. The buffer collect messages until the buffer of messages bytes reaches the limit defined with the buffer argument and then emit all the collected data. Useful to reduce the number of calls between the native and the react-native part in case of many messages. Returns a Promise object.

Arguments

peripheralId - String - the id/mac address of the peripheral.
serviceUUID - String - the UUID of the service.
characteristicUUID - String - the UUID of the characteristic.
buffer - Integer - the capacity of the buffer (bytes) stored before emitting the data for the characteristic.

Examples

BleManager.startNotificationWithBuffer(
  "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);
  });

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

Request a connection parameter update. Returns a Promise object which fulfills with the status of the request.

Arguments

peripheralId - String - the id/mac address of the peripheral.
connectionPriority - Integer - the connection priority to be requested, as follows:
- 0 - balanced priority connection
- 1 - high priority connection
- 2 - low power priority connection

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

peripheralId - String - the id/mac address of the peripheral.
mtu - Integer - the MTU size to be requested in bytes.

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);
  });

refreshCache(peripheralId) [Android only]

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

Arguments

peripheralId - String - the id/mac address of the peripheral.

Examples

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

getAssociatedPeripherals() [Android only, API 26+]

Retrieve associated peripherals (from companion manager).

removeAssociatedPeripheral(peripheralId) [Android only, API 26+]

Remove an associated peripheral.

Rejects if no association is found.

Arguments

peripheralId - String - Peripheral to remove

createBond(peripheralId,peripheralPin) [Android only]

Start the bonding (pairing) process with the remote device. If you pass peripheralPin (optional), bonding will be auto (without manually entering the pin). Returns a Promise object that will resolve if the bond is successfully created, otherwise it will be rejected with the appropriate error message.

In Android, Ensure to make one bond request at a time. 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);
});

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

peripheralId - String - the id/mac address of the peripheral.

setName(name) [Android only]

Create the request to set the name of the bluetooth adapter. (https://developer.android.com/reference/android/bluetooth/BluetoothAdapter#setName(java.lang.String)) Returns a Promise object.

Examples

BleManager.setName("INNOVEIT_CENTRAL")
  .then(() => {
    // Success code
    console.log("Name set successfully");
  })
  .catch((error) => {
    // Failure code
    console.log("Name could not be set");
  });

iOS-only

APIs that surface CoreBluetooth limitations or platform-specific helpers.

getMaximumWriteValueLengthForWithoutResponse(peripheralId) [iOS only]

Return the maximum value length for WriteWithoutResponse. Returns a Promise object.

Examples

BleManager.getMaximumWriteValueLengthForWithoutResponse(
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
).then((maxValue) => {
  console.log("Maximum length for WriteWithoutResponse: " + maxValue);
});

getMaximumWriteValueLengthForWithResponse(peripheralId) [iOS only]

Return the maximum value length for WriteWithResponse. Returns a Promise object.

Examples

BleManager.getMaximumWriteValueLengthForWithResponse(
  "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
).then((maxValue) => {
  console.log("Maximum length for WriteWithResponse: " + maxValue);
});