rnb

react-native-bluetooth-state-manager

Manage the bluetooth state of your device

Showing:

Popularity

Downloads/wk

2.8K

GitHub Stars

28

Maintenance

Last Commit

8mos ago

Contributors

6

Package

Dependencies

0

License

MIT

Type Definitions

Tree-Shakeable

No?

Categories

Readme

react-native-bluetooth-state-manager

npm version code style: prettier

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

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

Click here for instructions how to link it for 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 LibrariesAdd Files to [your project's name]
  2. Go to node_modulesreact-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 PhasesLink 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')
  1. in android/app/build.gradle:
dependencies {
+  compile project(':react-native-bluetooth-state-manager')
  ...
  compile "com.facebook.react:react-native:+"  // From node_modules
}
  1. 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

MethodReturn TypeOSDescription
getState()Promise<String>Android, iOSReturns the current state of the bluetooth service.
onStateChange(listener, emitCurrentState)SubscriptionAndroid, iOSListen for bluetooth state changes.
openSettings()Promise<null>Android, iOSOpens the bluetooth settings. Please see below for more details.
requestToEnable()Promise<Boolean>AndroidShow a dialog that allows the user to turn on Bluetooth.
enable()Promise<null>AndroidEnables Bluetooth without further user interaction.
disable()Promise<null>AndroidDisables 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

NameDescription
EVENT_BLUETOOTH_STATE_CHANGECallback 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

NameValue TypeDefault valueDescription
emitCurrentStateBooleantrueIf true, current state will be emitted.
onChangeFunctionundefinedCallback which emits the current state (first argument) change and the previous state (second argument).
childrenFunction or anyundefined

<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

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
Sudhir YadavNew Delhi5 Ratings0 Reviews
3 months ago