react-native-ble-plx

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

• Compatibility
• Recent Changes
• Documentation & Support
• Configuration & Installation
• 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	:white_check_mark:
0.71.13	:white_check_mark:
0.70.13	:white_check_mark:

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+

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

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

iOS (example setup)

• npm install --save react-native-ble-plx
• Enter ios folder and run pod update
• Add NSBluetoothAlwaysUsageDescription in info.plist file. (it is a requirement since iOS 13)
• 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)

• npm install --save react-native-ble-plx

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

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

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

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

• (Optional) 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"/>
  
      ...
  

Troubleshooting