About this library

This is React Native Bluetooth Low Energy library wrapping Multiplatform Ble Adapter.

It supports:

• observing device's Bluetooth adapter state
• scanning BLE devices
• making connections to peripherals
• discovering services/characteristics
• reading/writing characteristics
• observing characteristic notifications/indications
• reading RSSI
• negotiating MTU
• background mode on iOS
• turning the device's Bluetooth adapter on

It does NOT support:

• bluetooth classic devices.
• communicating between phones using BLE (Peripheral support)
• bonding peripherals

Table of Contents

1. Compatibility
2. Recent Changes
3. Documentation & Support
4. Configuration & Installation
5. Troubleshooting

Compatibility

For old RN versions (<0.60) please check old README (1.x) for the old instructions or migration guide.

React Native	3.0.0
0.72.4	✅
0.71.13	✅
0.70.13	✅

Recent Changes

3.0.0

• Added Example project
• Updated MultiplatformBleAdapter to version 0.2.0.
• Updated RN bridge config
• Changed CI flow
• Updated CI to RN 0.72.x
• Updated docs
• Updated dependencies
• Fixed iOS 16 bugs

Current version changes All previous changes

Documentation & Support

Interested in React Native project involving Bluetooth Low Energy? We can help you!

Documentation can be found here.

Quick introduction can be found here

Contact us at intent.

Configuration & Installation

Expo SDK 43+

1. A custom expo-dev-client can now be built along with config plugins to avoid the need to eject from Expo. Learn how to integrate react-native-ble-plx with Expo here. (only for expo SDK 43+)

Legacy Expo (SDK < 43)

1. Make sure your Expo project is ejected (formerly: detached). You can read how to do it here. (only for Expo SDK < 43)
2. Follow steps for iOS/Android.

iOS (example setup)

1. npm install --save react-native-ble-plx
2. Enter ios folder and run pod update
3. Add NSBluetoothAlwaysUsageDescription in info.plist file. (it is a requirement since iOS 13)
4. If you want to support background mode:
   • In your application target go to Capabilities tab and enable Uses Bluetooth LE Accessories in Background Modes section.
   • Pass restoreStateIdentifier and restoreStateFunction to BleManager constructor.

Android (example setup)

1. npm install --save react-native-ble-plx

2. In top level build.gradle make sure that min SDK version is at least 23:

   buildscript {
       ext {
           ...
           minSdkVersion = 23
           ...

3. In build.gradle make sure to add jitpack repository to known repositories:

   allprojects {
       repositories {
         ...
         maven { url 'https://www.jitpack.io' }
       }
   }

4. In AndroidManifest.xml, add Bluetooth permissions and update <uses-sdk/>:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android">
   
      ...
   
      <!-- Android >= 12 -->
      <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
      <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
      <!-- Android < 12 -->
      <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
      <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
      <!-- common -->
      <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   
      <!-- Add this line if your application always requires BLE. More info can be found on:
          https://developer.android.com/guide/topics/connectivity/bluetooth-le.html#permissions
        -->
      <uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>
   
       ...

5. (Optional) In SDK 31+ You can remove ACCESS_FINE_LOCATION (or mark it as android:maxSdkVersion="30" ) from AndroidManifest.xml and add neverForLocation flag into BLUETOOTH_SCAN permissions which says that you will not use location based on scanning eg:

    <uses-permission android:name="android.permission.INTERNET" />
    <!-- Android >= 12 -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    <!-- Android < 12 -->
    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
   
       ...

   With neverForLocation flag active, you no longer need to ask for ACCESS_FINE_LOCATION in your app

Troubleshooting