Skip to content

Latest commit

 

History

History
561 lines (391 loc) · 17.7 KB

README.md

File metadata and controls

561 lines (391 loc) · 17.7 KB
Raw

React Native Bluetooth Serial Next :)

npm NpmLicense Dependency Status NPM Downloads

React Native version of BluetoothSerial plugin for both Android and iOS. Pulled from React Native Bluetooth Serial.

For iOS, this module currently supports preconfigured services which are Read Bear Lab, Adafruit BLE, Bluegiga, Laird Virtual Serial Port, and Rongta.

Table of Contents

Getting started

npm install react-native-bluetooth-serial-next --save
react-native link react-native-bluetooth-serial-next

For Android, you need to put the following code to AndroidManifest.xml in android/app/src/main at your project root folder.

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

Manual Installation

iOS

  1. npm install react-native-bluetooth-serial-next --save
  2. In XCode, in the project navigator, right click Libraries ➜ Add Files to [your project's name]
  3. Go to node_modules ➜ react-native-bluetooth-serial-next and add RCTBluetoothSerial.xcodeproj
  4. In XCode, in the project navigator, select your project. Add libRCTBluetoothSerial.a to your project's Build Phases ➜ Link Binary With Libraries
  5. Click RCTBluetoothSerial.xcodeproj in the project navigator and go the Build Settings tab. Make sure 'All' is toggled on (instead of 'Basic'). In the Search Paths section, look for Header Search Paths and make sure it contains both $(SRCROOT)/../../react-native/React and $(SRCROOT)/../../../React - mark both as recursive.
  6. Run your project (Cmd+R)

Android

  1. npm install react-native-bluetooth-serial-next --save
  2. Open up android/app/src/main/java/[...]/MainActivity.java or MainApplication.java for React Native >= 0.29
    • Add import com.nuttawutmalee.RCTBluetoothSerial.*; to the imports at the top of the file
    • Add new RCTBluetoothSerialPackage() to the list returned by the getPackages() method
  3. Append the following lines to android/settings.gradle 
    include ':react-native-bluetooth-serial-next'
project(':react-native-bluetooth-serial-next').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-bluetooth-serial-next/android')
  4. Insert the following lines inside the dependencies block in android/app/build.gradle 
    compile project(':react-native-bluetooth-serial-next')

Example

  1. git clone https://github.com/nuttawutmalee/react-native-bluetooth-serial-next.git
  2. cd react-native-bluetooth-serial-next/example
  3. npm install && npm link ../
  4. npm start
  5. react-native run-ios or react-native run-android

API References

Device object

This is basically the result object from API methods depending on operation system.

iOS

{
    id: '111-111-111-111',
    uuid: '111-111-111-111',
    name: 'Bluetooth Printer',
    rssi: 'This field might not be present in the object',
}

Android

{
    id: '111-111-111-111',
    address: '111-111-111-111',
    name: 'Bluetooth Printer',
    class: 'This field might not be present in the object',
}

High order component

withSubscription( options : Object ) : React.Component

This method will create an event listener and send it though as a component prop and it will remove all event listeners on componentWillUnmount as well.

  • options : Object
    • subscriptionName : String = 'subscription' The event listener prop name.
    • destroyOnWillUnmount : Boolean = true Should event listeners remove all listeners and subscription
class MyComponent extends React.Component {
    ...
}

export default withSubscription({
    subscriptionName: 'events',
    destroyOnWillUnmount: true,
})(MyComponent);

Methods

Bluetooth adapter

requestEnable() : Promise<Boolean>

Prompts the application device to enable bluetooth adapter.

  • For iOS, this method will throw an error.
  • For Android, if the user does not enable bluetooth upon request, it will throw an error.
await BluetoothSerial.requestEnable();
enable() : Promise<Boolean>

Enable bluetooth adapter service.

  • For iOS, this method will throw an error.
await BluetoothSerial.enable();
disable() : Promise<Boolean>

Disable bluetooth adapter service.

  • For iOS, this method will throw an error.
await BluetoothSerial.disable();
isEnabled() : Promise<Boolean>

Indicates bluetooth adapter service status.

const isEnabled = await BluetoothSerial.isEnabled();
list() : Promise<Device[]>

List all paired (Android) or connected (iOS) bluetooth devices.

const devices = await BluetoothSerial.list();
listUnpaired() : Promise<Device[]> | discoverUnpairedDevices() : Promise<Device[]>

List all unpaired bluetooth devices.

const devices = await BluetoothSerial.listUnpaired();
const devices = await BluetoothSerial.discoverUnpairedDevices();
cancelDiscovery() : Promise<Boolean> | stopScanning() : Promise<Boolean>

Cancel bluetooth device discovery process.

await BluetoothSerial.cancelDiscovery();
await BluetoothSerial.stopScanning();
setAdapterName( name : String ) : Promise<String>

Give bluetooth adapter a new name.

  • name : String Bluetooth adapter new name.
  • For iOS, this method will throw an error.
const newName = await BluetoothSerial.setAdapterName("New Adapter Name");

Device pairing

pairDevice( id : String ) : Promise<Device | null>

Pair with a bluetooth device.

  • id : String Device id or uuid.
  • For iOS, this method will throw an error.
const device = await BluetoothSerial.pairDevice(id);
unpairDevice( id : String ) : Promise<Device | null>

Unpair from a bluetooth device.

  • id : String Device id or uuid.
  • For iOS, this method will throw an error.
const device = await BluetoothSerial.unpairDevice(id);

Device connection

connect( id : String ): Promise<Device>

Connect to a specific bluetooth device.

  • id : String Device id or uuid.
const device = await BluetoothSerial.connect(id);
disconnect( id? : String ) : Promise<Boolean>

Disconnect from the specific connected bluetooth device. If id is omitted, the first connected device will be disconnected.

  • id? : String Optional device id or uuid.
await BluetoothSerial.disconnect();
isConnected( id? : String ) : Promise<Boolean>

Indicates the specific connected bluetooth device connection status. If id is omitted, it will return the connection status of the first connected device.

  • id? : String Optional device id or uuid.
const isConnected = await BluetoothSerial.isConnected();

Device IO

read( callback : Function, delimiter? : String, id? : String ) : void

Listen and read data from the selected or first connected device.

  • callback : Function
    • data : String
    • subscription : EmitterSubscription
  • delimiter? : String = ''
  • id? : String Optional device id or uuid.
BluetoothSerial.read((data, subscription) => {
  console.log(data);

  if (this.imBoredNow && subscription) {
    BluetoothSerial.removeSubscription(subscription);
  }
}, "\r\n");
readOnce( delimiter? : String, id? : String ) : Promise<String>

Read data from the selected or first connected device once.

  • delimiter? : String = ''
  • id? : String Optional device id or uuid.
const data = await BluetoothSerial.readOnce("\r\n");
readEvery( callback : Function, ms? : Number, delimiter? : String, id? : String ) : void

Read data from the selected or first connected device every n ms.

  • callback : Function
    • data : String
    • intervalId : Number
  • ms?: Number = 1000
  • delimiter? : String = ''
  • id? : String Optional device id or uuid.
BluetoothSerial.readEvery(
  (data, intervalId) => {
    console.log(data);

    if (this.imBoredNow && intervalId) {
      clearInterval(intervalId);
    }
  },
  5000,
  "\r\n"
);
readFromDevice( id? : String ) : Promise<String>

Read all buffer data from the selected or first connected device.

  • id? : String Optional device id or uuid.
const data = await BluetoothSerial.readFromDevice();
readUntilDelimiter( delimiter : String, id? : String ) : Promise<String>

Read all buffer data up to certain delimiter from the selected or first connected device.

  • delimiter : String
  • id? : String Optional device id or uuid.
const data = await BluetoothSerial.readUntilDelimiter("\r\n");
write( data : Buffer | String, id? : String ) : Promise<Boolean>

Write buffer or string to the selected or first connected device.

  • data : Buffer | String
  • id? : String Optional device id or uuid.
await BluetoothSerial.write("This is the test message");
writeToDevice( data : String, id? : String ) : Promise<Boolean>

Write string to the selected or first connected device.

  • data : String
  • id? : String Optional device id or uuid.
await BluetoothSerial.writeToDevice("This is the test message");

Device buffer

clear( id? : String ) : Promise<Boolean>

Clear all buffer data of the selected or first connected device.

  • id? : String Optional device id or uuid.
await BluetoothSerial.clear();
available( id? : String ) : Promise<Number>

Get length of current buffer data of the selected or first connected device.

  • id? : String Optional device id or uuid.
const bufferLength = await BluetoothSerial.available();
withDelimiter( delimiter : String, id? : String ) : Promise<String | null>

Set delimiter that will split the buffer data when you are reading from device.

  • delimiter : String
  • id? : String Optional device id or uuid.
const deviceId = await BluetoothSerial.withDelimiter("\r\n");

Multiple devices connection

This module supports multiple devices connection, as you can see in API Methods, most of the connection, IO, and buffer methods have id parameter that you can pass and specify which bluetooth device that you want to control.

However, to keep it clean and simple, you can use the following method to simplify them.

device( id? : String ) : Object

This method gives the ability to call group of API methods instead of pass id parameter at the end of each methods.

  • id? : String Optional device id or uuid.

The followings are group of methods that you can use with this method.

  • connect
  • disconnect
  • isConnected
  • clear
  • available
  • withDelimiter
  • read
  • readOnce
  • readEvery
  • readUntilDelimiter
  • readFromDevice
  • write
  • writeToDevice
const myDevice = BluetoothSerial.device(myId);
const yourDevice = BluetoothSerial.device(yourId);

await myDevice.connect();
await myDevice.write('This is a message for my device.');


let yourReadSubscription;

await yourDevice.connect();
await yourDevice.read((data, subscription) => {
    yourReadSubscription = subscription;

    console.log('Your data:', data);

    if (/** */) {
        BluetoothSerial.removeSubscription(subscription);
        yourReadSubscription = null;
    }
});

await myDevice.disconnect();

if (yourReadSubscription) {
    BluetoothSerial.removeSubscription(yourReadSubscription);
}

await yourDevice.disconnect();

Events

Types

  • bluetoothEnabled : When bluetooth adapter is turned on.

  • bluetoothDisabled : When bluetooth adapter is turned off.

  • connectionSuccess : When device is connected. You get object of message and device.

    {
    message: ...,
    device: {
        ...
    }
}

  • connectionFailed : When you failed to connect to the device. You get object of message and device.

    {
    message: ...,
    device: {
        ...
    }
}

  • connectionLost : When the device connection is lost. You get object of message and device.

    {
    message: ...,
    device: {
        ...
    }
}

  • read or data : String of data from device. You get object of device id and data.

    {
    id: ...,
    data: ...
}

  • error : Error message from native code.

    {
    message: ...
}

Methods

once( eventName : String, handler : Function ) : EmitterSubscription
on( eventName : String, handler : Function ) : EmitterSubscription
addListener( eventName : String, handler : Function ) : EmitterSubscription
off( eventName : String, handler : Function ) : void
removeListener( eventName : String, handler : Function ) : void
removeAllListeners( eventName? : String ) : void
removeSubscription( subscription : EmitterSubscription) : void

Todos

  • iOS Service declaration. We should be able to define array of service UUID, read characteristic UUID, write characteristic UUID ourselves.
  • Write base64 image.