react-native-ble-plx: A Swift repository from softwareonair

About this library

This is React Native Bluetooth Low Energy library using RxBluetoothKit and RxAndroidBle under the hood.

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
turning the device's Bluetooth adapter on

What this library does NOT support:

communicating between phones using BLE (Peripheral support)
bonding peripherals

Compatibility

React Native	1.0.3	1.1.0
0.60.5	✅²	✅²
0.59.10	✅	✅
0.58.6	✅	✅
0.57.8	✅	✅
0.56.1	💥¹	💥¹
0.55.4	💥¹	💥¹

¹ fails on Android, although might work after updating gradle

² may require usage of jetifier on Android and migration to CocoaPods on iOS.

Recent Changes

1.1.0

Add support for descriptors.
Fix XCode 11 compilation error.

All previous changes

Documentation & Support

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

Learn more about Polidea's BLE services here.

Documentation can be found here.

Configuration & Installation

iOS (expo/Podfile and RN 0.60+, example setup)

Make sure your Expo project is ejected (formerly: detached). You can read how to do it here and here. (only for expo)
npm install --save react-native-ble-plx
react-native link react-native-ble-plx
Open Xcode workspace located inside ios folder and add empty Swift file if you don't have at least one:
- Select File/New/File...
- Choose Swift file and click Next.
- Name it however you want, select your application target and create it.
- Accept to create Objective-C bridging header.

Update your ios/Podfile to contain:

pod 'react-native-ble-plx', :path => '../node_modules/react-native-ble-plx'
pod 'react-native-ble-plx-swift', :path => '../node_modules/react-native-ble-plx'

Enter ios folder and run pod update
Minimal supported version of iOS is 8.0
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.
Starting from iOS 13 add NSBluetoothAlwaysUsageDescription in info.plist file.

iOS (react-native < 0.60, example setup)

npm install --save react-native-ble-plx
react-native link react-native-ble-plx
Open Xcode project located inside ios folder and add empty Swift file if you don't have at least one:
- Select File/New/File...
- Choose Swift file and click Next.
- Name it however you want, select your targets and create it.
- Accept to create Objective-C bridging header.
Minimal supported version of iOS is 8.0
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.
Starting from iOS 13 add NSBluetoothAlwaysUsageDescription in info.plist file.

Android (example setup)

npm install --save react-native-ble-plx
react-native link react-native-ble-plx
In build.gradle of app module make sure that min SDK version is at least 18:

android {
    ...
    defaultConfig {
        minSdkVersion 18
        ...

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

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    ...
    <uses-permission android:name="android.permission.BLUETOOTH"/>
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
    <uses-permission-sdk-23 android:name="android.permission.ACCESS_COARSE_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"/>

    <uses-sdk
        android:minSdkVersion="18"
        ...

If you are using AndroidX, then for the time being you need to convert import statements in the Android library with jetifier. These steps apply for all react-native packages, which are during the transition period:

npm install --save-dev jetifier
Run jetify script after npm install. You can do it by adding "postinstall" script to the package.json file:
```
 ...
 "postinstall": "npx jetify",
 ...
```

Troubleshooting

Problems with Proguard

Add this to your app/proguard-rules.pro

-dontwarn com.polidea.reactnativeble.**

softwareonair/react-native-ble-plx