The react-native-ble-plx from eaembree

React Native Bluetooth Low Energy library using RxBluetoothKit and RxAndroidBle as it's backend libraries.

Example apps are available in Google Play and App Store!

Configuration & installation for new project

iOS:

Add react-native-ble-plx to a project as a dependency in package.json file. For example "react-native-ble-plx": "Polidea/react-native-ble-plx" will install latest version from Polidea's Github repository.
Make sure that you have Carthage installed on your system.
Execute npm install to fetch and install a library.
Open iOS project located in ./ios folder.
Move BleClient.xcodeproj located in .node_modules/react-native-ble-plx/ios using drag & drop to Libraries folder in your project.
In general settings of a target add libBleClient.a to Linked Frameworks and Libraries.
In Build Settings/Search Paths/Framework search paths add path: $(SRCROOT)/../node_modules/react-native-ble-plx/ios/BleClientManager/Carthage/Build/iOS.
In Build Settings/Build Options/Always Embed Swift Standard Libraries set to Yes.
In Build Phases click on top left button and add New Run Script Phase.
- Shell command: /usr/local/bin/carthage copy-frameworks
- Input Files:
  - $(SRCROOT)/../node_modules/react-native-ble-plx/ios/BleClientManager/Carthage/Build/iOS/BleClientManager.framework
  - $(SRCROOT)/../node_modules/react-native-ble-plx/ios/BleClientManager/Carthage/Build/iOS/RxSwift.framework
  - $(SRCROOT)/../node_modules/react-native-ble-plx/ios/BleClientManager/Carthage/Build/iOS/RxBluetoothKit.framework
Minimal supported version of iOS is 8.0

Android:

Add react-native-ble-plx to a project as a dependency in package.json file. For example "react-native-ble-plx": "Polidea/react-native-ble-plx" will install latest version from Polidea's Github repository.
Execute npm install to fetch and install a library.
Open Android project located in ./android folder.
In settings.gradle add following lines:

include ':react-native-ble-plx'
project(':react-native-ble-plx').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-ble-plx/android')

In build.gradle of app module add following dependency:

dependencies {
   ...
   compile project(':react-native-ble-plx')
   ...

Additionaly make sure that min SDK version is at least 18:

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

In MainApplication.getPackages import and add BleModule package:

import com.polidea.reactnativeble.BlePackage;
...

public class MainApplication extends Application implements ReactApplication {
    ...

    @Override
    protected List<ReactPackage> getPackages() {
      return Arrays.<ReactPackage>asList(
        new MainReactPackage(),
        new BlePackage()
      );
}

In AndroidManifest.xml add Bluetooth permission and update or remove <uses-sdk/>:

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

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

Installing and running example app

Go to example project folder cd examples/ReactBLEScanner.
Make sure that you have Carthage installed on your system.
Install required packages executing: npm install.
iOS: Open Xcode example project in ./examples/ReactBLEScanner/ios/ReactBLEScanner.xcodeproj.
Android: Open Android example project in ./examples/ReactBLEScanner/android.
Build and run.

Developing modules and example app

You can use included scripts to sync files between this repository root and node_module/react-native-ble-plx if want to work on local copy of library:

./install-ble-lib.sh - move files from root to node_module/react-native-ble-plx.
./sync-ble-lib.sh - move files from node_module/react-native-ble-plx to root.

Scripts are located in ./examples/ReactBLEScanner folder.

Warning: This operation may delete files on destination directory.

Additional configuration for iOS

TODO

JavaScript API

First of all include BleModule in react native project:

import { BleManager } from 'react-native-ble-plx';

BleManager should be initialized with new keyword and method destroy() should be called on it's instance when we are done with it:

const manager = new BleManager()
// Work with BLE manager
manager.destroy()

Cancelling operations

Few operations such as monitoring characteristic's value changes can be cancelled by a user. Basically every API entry which accepts transactionId allows to call cancelTransaction function. When cancelled operation is a promise or a callback which registers errors, "Cancelled" error will be emitted in that case.

`cancelTransaction(transactionId)`

Cancels specified transaction if in progress. Otherwise does nothing.

Parameters:

transactionId - Unique ID of a transaction to cancel.

UUIDs format

Currently React Native allows to transfer only basic types between React Native modules and JS. Therefore user needs to pass UUIDs in a form of a string. To make behavior more platform independent all UUIDs returned from API calls are lowercase and in full 128bit, like for example: 00002a00-0000-1000-8000-00805f9b34fb. Only exception are device UUIDs which are MAC addresses on Android and UUIDs on iOS. There is also a convenience function fullUUID implemented in a library which converts any 16bit or 128bit UUID string to above form. However all function arguments of API functions defined below can receive UUIDs in any valid string form.

Manager state

`async state` [for now iOS only]

Current state of a manager.

Returns: Current state of a manager as a string:

'Unknown' - the current state of the manager is unknown; an update is imminent.
'Resetting' - the connection with the system service was momentarily lost; an update is imminent.
'Unsupported' - the platform does not support Bluetooth low energy.
'Unauthorized' - the app is not authorized to use Bluetooth low energy.
'PoweredOff' - Bluetooth is currently powered off.
'PoweredOn' - Bluetooth is currently powered on and available to use.

`onStateChange(listener)` [for now iOS only]

Notifies about state changes of a manager.

Parameters:

listener(newState) - callback which emits state changes of BLE Manager. Look above for possible values.

Returns: Subscription on which remove() function can be called to unsubscribe.

Scanning devices

`startDeviceScan(uuids, options, listener)`

Starts device scanning. When previous scan is in progress it will be stopped before executing this command.

Parameters:

uuids - array of strings containing UUIDs of services which we would like have in scanned devices. If null it will scan all available devices.
options - object containing platform specific options, which can be enabled for scanning (can be null):

{
    "allowDuplicates": bool, // iOS: Devices will be scanned more frequently if true, by default false
    "autoConnect": bool,     // Android: allows to connect to devices which are not in range.
}

listener(error, scannedDevice) - function which will be called for every scanned device (devices may be scanned multiple times). It's first argument is potential error which is set to non null value when scanning failed. You have to start scanning process again if that happens. Second argument is a scanned device passed as an object with following fields:

{
    "uuid": string,            // UUID of scanned device (for iOS it's local identifier)
    "name": ?string,           // device name if present or null otherwise
    "rssi": ?number,           // RSSI value during scanning

    "manufacturerData": ?string,                 // Manufacturer specific data
    "serviceData": ?{[service: string]: string}, // Data related to service
    "serviceUUIDs": ?string[],                   // UUIDs of advertised services
    "txPowerLevel": ?number,                     // Transmitted power level
    "solicitedServiceUUIDs": ?string[],          // Solicited service UUIDs

    "isConnectable": ?boolean,                   // Is device connectable (iOS only)
    "overflowServiceUUIDs": ?string[]            // Overflow service UUIDs (iOS only)

    // Utility functions
}

`stopDeviceScan()`

Stops scanning if in progress. Does nothing otherwise.

Connection management

`async connectToDevice(identifier, [options])`

Connects to device with provided UUID.

Parameters:

identifier - device UUID
options - platform specific options for connection establishment (may be null or ignored):

{
    // Not used yet
}

Returns: promise which will return connected device object if successful.

`async device.connect([options])`

Utility function which can be used on device object directly without need to pass device UUID.

Parameters and return value:

Look above.

`async cancelDeviceConnection(identifier)`

Disconnects from device if it's connected or cancels pending connection.

Parameters:

identifier - device UUID.

Returns: a promise with device object as a result or an error.

`async device.cancelConnection()`

Utility function which disconnects from device if it's connected.

Parameters and return value:

Look above.

`async isDeviceConnected(identifier)`

Check connection state of a device.

Parameters:

identifier - device UUID.

Returns: a promise which emits true if device is connected, otherwise false.

`async device.isConnected()`

Utility function which checks connection state of a device.

Parameters and return value:

Look above.

`onDeviceDisconnected(identifier, listener)`

Monitors if device was disconnected due to any errors or connection problems.

Parameters:

identifier - device UUID.
listener(error, device) - callback returning error as a reason of disconnection if available and device object.

Returns: Subscription on which remove() function can be called to unsubscribe.

`device.onDisconnected(listener)`

Utility function which monitors if device was disconnected due to any errors or connection problems.

Parameters and return value:

Look above.

Discovery

`async discoverAllServicesAndCharacteristicsForDevice(identifier)`

Discovers all services and characteristics for device.

Parameters:

identifier - device UUID.

Returns: promise which emits device object if all available services and characteristics have been discovered.

`async device.discoverAllServicesAndCharacteristics()`

Discovers all services and characteristics for device.

Parameters and return value:

Look above.

Services

`async servicesForDevice(identifier)`

Get list of discovered services for device.

Parameters:

identifier - device UUID.

Returns: Promise which emits array of service objects which are discovered for a device:

{
    "uuid": string,       // Service UUID
    "deviceUUID": string, // Device identifier which owns this service
    "isPrimary": boolean, // Is service primary

    // Utility functions
}

`async device.services()`

Utility function to get list of discovered services for device.

Parameters and return value:

Look above.

Characteristics

`async characteristicsForDevice(identifier, serviceUUID)`

Get list of discovered characteristics.

Parameters:

identifier - device UUID.
serviceUUID - service UUID.

Returns: Promise which emits array of characteristic objects which are discovered for a device in specified service:

{
    "uuid": string,                         // Characteristic UUID
    "serviceUUID": string,                  // Service UUID which owns this characteristic
    "deviceUUID": string,                   // Device identifier which owns this characteristic
    "isReadable": boolean,                  // Is characteristic readable
    "isWriteableWithResponse": boolean,     // Is characteristic writeable when writing with response
    "isWriteableWithoutResponse": boolean,  // Is characteristic writeable when writing without response
    "isNotifiable": boolean,                // Is characteristic notifiable
    "isNotifying": boolean,                 // Current status of notification for this characteristic
    "isIndictable": boolean,                // Is characteristic indictable
    "value": string,                        // Base64 value, may be null

    // Utility functions
}

`async device.characteristicsForService(serviceUUID)`

Utility function to get list of discovered characteristics in specified service for device.

Parameters and return value:

Look above.

`async service.characteristics()`

Utility function to get list of discovered characteristics for a service.

Parameters and return value:

Look above.

`async readCharacteristicForDevice(identifier, serviceUUID, characteristicUUID, [transactionId])`

Read characteristic value.

Parameters:

identifier - device UUID.
serviceUUID - service UUID.
characteristicUUID - characteristic UUID.
transactionId - optional transactionId which can be used in cancelTransaction function.

Returns: Promise which emits first characteristic object matching specified UUID paths. Latest value of characteristic will be stored.

`async device.readCharacteristicForService(serviceUUID, characteristicUUID)`

Read characteristic value.

Parameters and return value:

Look above.

`async service.readCharacteristic(characteristicUUID)`

Read characteristic value.

Parameters and return value:

Look above.

`async characteristic.read()`

Read characteristic value.

Parameters and return value:

Look above.

`async writeCharacteristicWithResponseForDevice(identifier, serviceUUID, characteristicUUID, valueBase64, [transactionId])`

Write characteristic value with response.

Parameters:

identifier - device UUID.
serviceUUID - service UUID.
characteristicUUID - characteristic UUID.
valueBase64 - value in Base64 format.
transactionId - optional transactionId which can be used in cancelTransaction function.

Returns: Promise which emits first characteristic object matching specified UUID paths. Latest value of characteristic may not be stored.

`async device.writeCharacteristicWithResponseForService(serviceUUID, characteristicUUID, valueBase64)`

Write characteristic value with response.

Parameters and return value:

Look above.

`async service.writeCharacteristicWithResponse(characteristicUUID, valueBase64)`

Write characteristic value with response.

Parameters and return value:

Look above.

`async characteristic.writeWithResponse(valueBase64)`

Write characteristic value with response.

Parameters and return value:

Look above.

`async writeCharacteristicWithoutResponseForDevice(identifier, serviceUUID, characteristicUUID, valueBase64, [transactionId])`

Write characteristic value without response.

Parameters:

identifier - device UUID.
serviceUUID - service UUID.
characteristicUUID - characteristic UUID.
valueBase64 - value in Base64 format.
transactionId - optional transactionId which can be used in cancelTransaction function.

Returns: Promise which emits first characteristic object matching specified UUID paths. Latest value of characteristic may not be stored.

`async device.writeCharacteristicWithoutResponseForService(serviceUUID, characteristicUUID, valueBase64)`

Write characteristic value without response.

Parameters and return value:

Look above.

`async service.writeCharacteristicWithoutResponse(characteristicUUID, valueBase64)`

Write characteristic value without response.

Parameters and return value:

Look above.

`async characteristic.writeWithoutResponse(valueBase64)`

Write characteristic value without response.

Parameters and return value:

Look above.

`monitorCharacteristicForDevice(identifier, serviceUUID, characteristicUUID, listener, [transactionId])`

Monitor value changes of a characteristic.

Parameters:

identifier - device identifier.
serviceUUID - service UUID.
characteristicUUID - characteristic UUID.
listener(error, characteristic) - listener which emits characteristic objects which modified value for each notification.
transactionId - optional transactionId which can be used in cancelTransaction function.

Returns:: Subscription on which remove() function can be called to unsubscribe.

`device.monitorCharacteristicForService(serviceUUID, characteristicUUID, listener, [transactionId])`

Monitor value changes of a characteristic.

Parameters and return value:

Look above.

`service.monitorCharacteristic(characteristicUUID, listener, [transactionId])`

Monitor value changes of a characteristic.

Parameters and return value:

Look above.

`characteristic.monitor(listener, [transactionId])`

Monitor value changes of a characteristic.

Parameters and return value:

Look above.

eaembree / react-native-ble-plx Goto Github PK

react-native-ble-plx's Introduction

Configuration & installation for new project

Installing and running example app

Developing modules and example app

Additional configuration for iOS

JavaScript API

Cancelling operations

cancelTransaction(transactionId)

UUIDs format

Manager state

async state [for now iOS only]

onStateChange(listener) [for now iOS only]

Scanning devices

startDeviceScan(uuids, options, listener)

stopDeviceScan()

Connection management

async connectToDevice(identifier, [options])

async device.connect([options])

async cancelDeviceConnection(identifier)

async device.cancelConnection()

async isDeviceConnected(identifier)

async device.isConnected()

onDeviceDisconnected(identifier, listener)

device.onDisconnected(listener)

Discovery

async discoverAllServicesAndCharacteristicsForDevice(identifier)

async device.discoverAllServicesAndCharacteristics()

Services

async servicesForDevice(identifier)

async device.services()

Characteristics

async characteristicsForDevice(identifier, serviceUUID)

async device.characteristicsForService(serviceUUID)

async service.characteristics()

async readCharacteristicForDevice(identifier, serviceUUID, characteristicUUID, [transactionId])

async device.readCharacteristicForService(serviceUUID, characteristicUUID)

async service.readCharacteristic(characteristicUUID)

async characteristic.read()

async writeCharacteristicWithResponseForDevice(identifier, serviceUUID, characteristicUUID, valueBase64, [transactionId])

async device.writeCharacteristicWithResponseForService(serviceUUID, characteristicUUID, valueBase64)

async service.writeCharacteristicWithResponse(characteristicUUID, valueBase64)

async characteristic.writeWithResponse(valueBase64)

async writeCharacteristicWithoutResponseForDevice(identifier, serviceUUID, characteristicUUID, valueBase64, [transactionId])

async device.writeCharacteristicWithoutResponseForService(serviceUUID, characteristicUUID, valueBase64)

async service.writeCharacteristicWithoutResponse(characteristicUUID, valueBase64)

async characteristic.writeWithoutResponse(valueBase64)

monitorCharacteristicForDevice(identifier, serviceUUID, characteristicUUID, listener, [transactionId])

device.monitorCharacteristicForService(serviceUUID, characteristicUUID, listener, [transactionId])

service.monitorCharacteristic(characteristicUUID, listener, [transactionId])

characteristic.monitor(listener, [transactionId])

react-native-ble-plx's People

Contributors

Recommend Projects

Recommend Topics

Recommend Org

`cancelTransaction(transactionId)`

`async state` [for now iOS only]

`onStateChange(listener)` [for now iOS only]

`startDeviceScan(uuids, options, listener)`

`stopDeviceScan()`

`async connectToDevice(identifier, [options])`

`async device.connect([options])`

`async cancelDeviceConnection(identifier)`

`async device.cancelConnection()`

`async isDeviceConnected(identifier)`

`async device.isConnected()`

`onDeviceDisconnected(identifier, listener)`

`device.onDisconnected(listener)`

`async discoverAllServicesAndCharacteristicsForDevice(identifier)`

`async device.discoverAllServicesAndCharacteristics()`

`async servicesForDevice(identifier)`

`async device.services()`

`async characteristicsForDevice(identifier, serviceUUID)`

`async device.characteristicsForService(serviceUUID)`

`async service.characteristics()`

`async readCharacteristicForDevice(identifier, serviceUUID, characteristicUUID, [transactionId])`

`async device.readCharacteristicForService(serviceUUID, characteristicUUID)`

`async service.readCharacteristic(characteristicUUID)`

`async characteristic.read()`

`async writeCharacteristicWithResponseForDevice(identifier, serviceUUID, characteristicUUID, valueBase64, [transactionId])`

`async device.writeCharacteristicWithResponseForService(serviceUUID, characteristicUUID, valueBase64)`

`async service.writeCharacteristicWithResponse(characteristicUUID, valueBase64)`

`async characteristic.writeWithResponse(valueBase64)`

`async writeCharacteristicWithoutResponseForDevice(identifier, serviceUUID, characteristicUUID, valueBase64, [transactionId])`

`async device.writeCharacteristicWithoutResponseForService(serviceUUID, characteristicUUID, valueBase64)`

`async service.writeCharacteristicWithoutResponse(characteristicUUID, valueBase64)`

`async characteristic.writeWithoutResponse(valueBase64)`

`monitorCharacteristicForDevice(identifier, serviceUUID, characteristicUUID, listener, [transactionId])`

`device.monitorCharacteristicForService(serviceUUID, characteristicUUID, listener, [transactionId])`

`service.monitorCharacteristic(characteristicUUID, listener, [transactionId])`

`characteristic.monitor(listener, [transactionId])`