react-native-bluetooth-state-manager

The only purpose of this library is to manage the Bluetooth state. Not more, not less.

If you need further functionality like connecting and communicating to a device, please look at react-native-ble-plx.

Features

• Manage bluetooth state
• Open bluetooth settings page of the OS
• Declarative API

Installation

Using Yarn: (recommended)

yarn add react-native-bluetooth-state-manager

Using npm:

npm install react-native-bluetooth-state-manager --save

Linking

React-Native >= 0.60

Beginning from 0.60 you don't need to link it anymore. For more see here.

iOS

For iOS you just need to install the pods.

cd ios/
pod install
cd ..

React-Native < 0.60

Automatic

Run react-native link react-native-bluetooth-state-manager

Manual

iOS

With cocoapods

Append the following lines to your ios/Podfile:

target '<your-project>' do
  ...
+ pod 'RNBluetoothStateManager', :path => '../node_modules/react-native-bluetooth-state-manager'
end

Without cocoapods

1. In XCode, in the project navigator, right click Libraries ➜ Add Files to [your project's name]
2. Go to node_modules ➜ react-native-bluetooth-state-manager and add RNBluetoothStateManager.xcodeproj
3. In XCode, in the project navigator, select your project. Add libRNBluetoothStateManager.a to your project's Build Phases ➜ Link Binary With Libraries
4. Run your project (Cmd+R)<

Android

Manually

1. in android/settings.gradle:

...
include ':app'
+ include ':react-native-bluetooth-state-manager'
+ project(':react-native-bluetooth-state-manager').projectDir = new File(rootProject.projectDir,   '../node_modules/react-native-bluetooth-state-manager/android')

2. in android/app/build.gradle:

dependencies {
+  compile project(':react-native-bluetooth-state-manager')
  ...
  compile "com.facebook.react:react-native:+"  // From node_modules
}

3. in android/app/src/main/java/[...]/MainApplication.java

+ import de.patwoz.rn.bluetoothstatemanager.RNBluetoothStateManagerPackage;

public class MainApplication extends Application implements ReactApplication {
  // ...

  private final ReactNativeHost mReactNativeHost = new ReactNativeHost(this) {
    @Override
    protected List<ReactPackage> getPackages() {
      return Arrays.<ReactPackage>asList(
          new MainReactPackage(),
+         new RNBluetoothStateManagerPackage()
      );
    }
  };

}

Usage

import BluetoothStateManager from 'react-native-bluetooth-state-manager';

iOS

You must provide a short description why you need access to bluetooth in your app. Otherwise your app will crash when requesting for bluetooth:

This app has crashed because it attempted to access privacy-sensitive data without a usage description.  The app's Info.plist must contain an NSBluetoothAlwaysUsageDescription key with a string value explaining to the user how the app uses this data.

See: https://developer.apple.com/documentation/bundleresources/information_property_list/nsbluetoothalwaysusagedescription

API

An example you will find in example/app/ExampleWithApi.js

| Method | Return Type | OS | Description | | ----------------------------------------------------------- | ------------------ | ------------ | ---------------------------------------------------------------- | | getState() | Promise<String> | Android, iOS | Returns the current state of the bluetooth service. | | onStateChange(listener, emitCurrentState) | Subscription | Android, iOS | Listen for bluetooth state changes. | | openSettings() | Promise<null> | Android, iOS | Opens the bluetooth settings. Please see below for more details. | | requestToEnable() | Promise<Boolean> | Android | Show a dialog that allows the user to turn on Bluetooth. | | enable() | Promise<null> | Android | Enables Bluetooth without further user interaction. | | disable() | Promise<null> | Android | Disables Bluetooth without further user interaction. |

Important: To use enable() and disable() on android, you have to add BLUETOOTH_ADMIN permission to your AndroidManifest.xml:

  <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>
  </manifest>

getState()

Returns the current state of the bluetooth service.

BluetoothStateManager.getState().then((bluetoothState) => {
  switch (bluetoothState) {
    case 'Unknown':
    case 'Resetting':
    case 'Unsupported':
    case 'Unauthorized':
    case 'PoweredOff':
    case 'PoweredOn':
    default:
      break;
  }
});

onStateChange(listener, emitCurrentState)

Listen for bluetooth state changes.

BluetoothStateManager.onStateChange((bluetoothState) => {
  // do something...
}, true /*=emitCurrentState*/);

openSettings()

Android

Opens the bluetooth settings.

Tested:

• Android 6.0.1 (Huawei P8 Lite ALE-L21)
• Android 7.1.1 (Galaxy J5 2016)
• Android 8.0 (Galaxy S8+ SM-G955f)

iOS

Opens the settings page of the app. Please see here.

BluetoothStateManager.openSettings();

requestToEnable()

Show a dialog that allows the user to turn on Bluetooth. More here: Android documentation.

• This function is only on android available.

BluetoothStateManager.requestToEnable().then((result) => {
  // result === true -> user accepted to enable bluetooth
  // result === false -> user denied to enable bluetooth
});

enable()

Enables Bluetooth without further user interaction

• This function is only on android available.
• Needs the BLUETOOTH_ADMIN permission.

BluetoothStateManager.enable().then((result) => {
  // do something...
});

disable()

Disables Bluetooth without further user interaction

• This function is only on android available.

• Needs the BLUETOOTH_ADMIN permission.

BluetoothStateManager.disable().then((result) => {
  // do something...
});

EVENTS

| Name | Description | | ------------------------------------------------------------- | --------------------------------------------- | | EVENT_BLUETOOTH_STATE_CHANGE | Callback for when the bluetooth state changed |

EVENT_BLUETOOTH_STATE_CHANGE

Callback for when the bluetooth state changed

BluetoothStateManager.addEventListener(
  BluetoothStateManager.EVENT_BLUETOOTH_STATE_CHANGE,
  (bluetoothState) => {
    // do something...
  }
);

// recommended: use the `onStateChange` function.

Declarative API

The declarative way uses the new context api of React 16.3.

import { BluetoothState } from 'react-native-bluetooth-state-manager';

<BluetoothState>

props

| Name | Value Type | Default value | Description | | ------------------ | ----------------- | ------------- | -------------------------------------------------------------------------------------------------------- | | emitCurrentState | Boolean | true | If true, current state will be emitted. | | onChange | Function | undefined | Callback which emits the current state (first argument) change and the previous state (second argument). | | children | Function or any | undefined | |

<BluetoothState.PoweredOn>

The children prop of this component will rendered only when bluetooth is turned on.

<BluetoothState.PoweredOff>

The children prop of this component will rendered only when bluetooth is turned off.

<BluetoothState.Resetting>

The children prop of this component will rendered only when bluetooth state is changing.

• "PoweredOff" -> "PoweredOn"
• "PoweredOn" -> "PoweredOff"

<BluetoothState.Unauthorized>

The children prop of this component will rendered only when the app doesn't have the permission to use bluetooth.

<BluetoothState.Unsupported>

The children prop of this component will rendered only when the device doesn't support bluetooth.

<BluetoothState.Unknown>

The children prop of this component will rendered only when the bluetooth state is unknown.

BluetoothState

An example you will find in example/app/ExampleWithDeclarativeApi.js

Context

Each component has access to the same context as shown below.

{
  bluetoothState: String,
  openSettings: Function,
  requestToEnable: Function,
  enable: Function,
  disable: Function,
}

children prop as function:

<BluetoothState>
  {({ bluetoothState, openSettings, requestToEnable, enable, disable }) => {
    // show something ...
    return <View />;
  }}
</BluetoothState>

BluetoothState.<BluetoothStateType>

Example

import { BluetoothState } from 'react-native-bluetooth-state-manager';

<BluetoothState>
  <BluetoothState.PoweredOn>
    <Text>This will rendered only when bluetooth is turned on.</Text>
  </BluetoothState.PoweredOn>
  <BluetoothState.PoweredOff>
    {({ requestToEnable, openSettings }) => (
      <View>
        <Text>This will rendered only when bluetooth is turned off.</Text>
        <Button
          title="This will rendered only when bluetooth is turned off."
          onPress={Platform.OS === 'android' ? requestToEnable : openSettings}
        />
      </View>
    )}
  </BluetoothState.PoweredOff>
  <BluetoothState.Resetting>
    <ActivityIndicator />
  </BluetoothState.Resetting>
  <BluetoothState.Unauthorized>
    <Text>This will rendered only when bluetooth permission is not granted.</Text>
  </BluetoothState.Unauthorized>
  <BluetoothState.Unsupported>
    <Text>This will rendered only when bluetooth is not supported.</Text>
  </BluetoothState.Unsupported>
  <BluetoothState.Unknown>
    <Text>You have a really strange phone.</Text>
  </BluetoothState.Unknown>
</BluetoothState>;

ToDo's

• [ ] Add tests

Why?

Why not just using react-native-ble-plx?

Because it's to over bloated for my purpose. In several of my projects I'm working on, I had to integrate several third-party SDK which communicates with different bluetooth devices (on the native side). So the only functionality I needed there (on the javascript side), was to check if the bluetooth is enabled to start the third-party SDK.

License

MIT