Skip to content

Latest commit

 

History

History
431 lines (352 loc) · 12.1 KB

README.zh.MD

File metadata and controls

431 lines (352 loc) · 12.1 KB
Raw

npm version

wjx-react-native-ble

兼容

  • iOS 8+
  • Android (API 19+)

安装

Link Libaray

npm install --save wjx-react-native-ble
react-native link

（Android）再进行以下步骤

打开 android/app/build.gradle 确保 minSdkVersion 最小为18，如果不是，请改为18。

例子

参考 example

方法

start(options)

返回：Promise Object. 参数：

  • options - JSON

options的可选参数:

  • showAlert - Boolean - [仅iOS] 当蓝牙被关闭时，是否显示弹窗提示
  • restoreIdentifierKey - String - [仅iOS] 指定 CoreBluetooth 指定的Unique key作为状态恢复
  • forceLegacy - Boolean - [仅Android] 强制使用新式API LegacyScanManager

scan(serviceUUIDs, seconds, allowDuplicates, scanningOptions)

Scan for availables peripherals. Returns a Promise object.

Arguments

  • serviceUUIDs - Array of String - the UUIDs of the services to looking for. On Android the filter works only for 5.0 or newer.
  • seconds - Integer - the amount of seconds to scan.
  • allowDuplicates - Boolean - [iOS only] allow duplicates in device scanning
  • scanningOptions - JSON - [Android only] after Android 5.0, user can control specific ble scan behaviors:

Examples

BleManager.scan([], 5, true)
  .then(() => {
    // Success code
    console.log('Scan started');
  });

stopScan()

Stop the scanning. Returns a Promise object.

Examples

BleManager.stopScan()
  .then(() => {
    // Success code
    console.log('Scan stopped');
  });

connect(peripheralId)

Attempts to connect to a peripheral. In many case if you can't connect you have to scan for the peripheral before. Returns a Promise object.

Arguments

  • peripheralId - String - the id/mac address of the peripheral to connect.

Examples

BleManager.connect('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX')
  .then(() => {
    // Success code
    console.log('Connected');
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

disconnect(peripheralId)

Disconnect from a peripheral. Returns a Promise object.

Arguments

  • peripheralId - String - the id/mac address of the peripheral to disconnect.

Examples

BleManager.disconnect('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX')
  .then(() => {
    // Success code
    console.log('Disconnected');
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

enableBluetooth() [Android only]

Create the request to the user to activate the bluetooth. Returns a Promise object.

Examples

BleManager.enableBluetooth()
  .then(() => {
    // Success code
    console.log('The bluetooh is already enabled or the user confirm');
  })
  .catch((error) => {
    // Failure code
    console.log('The user refuse to enable bluetooth');
  });

checkState()

Force the module to check the state of BLE and trigger a BleManagerDidUpdateState event.

Examples

BleManager.checkState();

startNotification(peripheralId, serviceUUID, characteristicUUID)

Start the notification on the specified characteristic, you need to call retrieveServices method before. Returns a Promise object.

Arguments

  • peripheralId - String - the id/mac address of the peripheral.
  • serviceUUID - String - the UUID of the service.
  • characteristicUUID - String - the UUID of the characteristic.

Examples

BleManager.startNotification('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX')
  .then(() => {
    // Success code
    console.log('Notification started');
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

stopNotification(peripheralId, serviceUUID, characteristicUUID)

Stop the notification on the specified characteristic. Returns a Promise object.

Arguments

  • peripheralId - String - the id/mac address of the peripheral.
  • serviceUUID - String - the UUID of the service.
  • characteristicUUID - String - the UUID of the characteristic.

read(peripheralId, serviceUUID, characteristicUUID)

Read the current value of the specified characteristic, you need to call retrieveServices method before. Returns a Promise object.

Arguments

  • peripheralId - String - the id/mac address of the peripheral.
  • serviceUUID - String - the UUID of the service.
  • characteristicUUID - String - the UUID of the characteristic.

Examples

BleManager.read('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX')
  .then((readData) => {
    // Success code
    console.log('Read: ' + readData);
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

write(peripheralId, serviceUUID, characteristicUUID, data, maxByteSize)

Write with response to the specified characteristic, you need to call retrieveServices method before. Returns a Promise object.

Arguments

  • peripheralId - String - the id/mac address of the peripheral.
  • serviceUUID - String - the UUID of the service.
  • characteristicUUID - String - the UUID of the characteristic.
  • data - Byte array - the data to write.
  • maxByteSize - Integer - specify the max byte size before splitting message

Data preparation

If your data is not in byte array format you should convert it first. For strings you can use convert-string or other npm package in order to achieve that. Install the package first:

npm install convert-string

Then use it in your application:

// Import/require in the beginning of the file
import { stringToBytes } from 'convert-string';
// Convert data to byte array before write/writeWithoutResponse
const data = stringToBytes(yourStringData);

Feel free to use other packages or google how to convert into byte array if your data has other format.

Examples

BleManager.write('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', data)
  .then(() => {
    // Success code
    console.log('Write: ' + data);
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

writeWithoutResponse(peripheralId, serviceUUID, characteristicUUID, data, maxByteSize, queueSleepTime)

Write without response to the specified characteristic, you need to call retrieveServices method before. Returns a Promise object.

Arguments

  • peripheralId - String - the id/mac address of the peripheral.
  • serviceUUID - String - the UUID of the service.
  • characteristicUUID - String - the UUID of the characteristic.
  • data - Byte array - the data to write.
  • maxByteSize - Integer - (Optional) specify the max byte size
  • queueSleepTime - Integer - (Optional) specify the wait time before each write if the data is greater than maxByteSize

Data preparation

If your data is not in byte array format check info for the write function above.

Example

BleManager.writeWithoutResponse('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', data)
  .then(() => {
    // Success code
    console.log('Writed: ' + data);
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

readRSSI(peripheralId)

Read the current value of the RSSI. Returns a Promise object.

Arguments

  • peripheralId - String - the id/mac address of the peripheral.

Examples

BleManager.readRSSI('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX')
  .then((rssi) => {
    // Success code
    console.log('Current RSSI: ' + rssi);
  })
  .catch((error) => {
    // Failure code
    console.log(error);
  });

retrieveServices(peripheralId)

Retrieve the peripheral's services and characteristics. Returns a Promise object.

Arguments

  • peripheralId - String - the id/mac address of the peripheral.

Examples

BleManager.retrieveServices('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX')
  .then((peripheralInfo) => {
    // Success code
    console.log('Peripheral info:', peripheralInfo);
  });

getConnectedPeripherals(serviceUUIDs)

Return the connected peripherals. Returns a Promise object.

Arguments

  • serviceUUIDs - Array of String - the UUIDs of the services to looking for.

Examples

BleManager.getConnectedPeripherals([])
  .then((peripheralsArray) => {
    // Success code
    console.log('Connected peripherals: ' + peripheralsArray.length);
  });

getDiscoveredPeripherals()

Return the discovered peripherals after a scan. Returns a Promise object.

Examples

BleManager.getDiscoveredPeripherals([])
  .then((peripheralsArray) => {
    // Success code
    console.log('Discovered peripherals: ' + peripheralsArray.length);
  });

removePeripheral(peripheralId)

Removes a disconnected peripheral from the cached list. It is useful if the device is turned off, because it will be re-discovered upon turning on again. Returns a Promise object.

Arguments

  • peripheralId - String - the id/mac address of the peripheral.

isPeripheralConnected(peripheralId, serviceUUIDs)

Check whether a specific peripheral is connected and return true or false. Returns a Promise object.

Examples

BleManager.isPeripheralConnected('XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX', [])
  .then((isConnected) => {
    if (isConnected) {
      console.log('Peripheral is connected!');
    } else {
      console.log('Peripheral is NOT connected!');
    }
  });

Events

BleManagerStopScan

The scanning for peripherals is ended.

Arguments

  • none

Examples

bleManagerEmitter.addListener(
    'BleManagerStopScan',
    () => {
        // Scanning is stopped
    }
);

BleManagerDidUpdateState

The BLE change state.

Arguments

  • state - String - the new BLE state ('on'/'off').

Examples

bleManagerEmitter.addListener(
    'BleManagerDidUpdateState',
    (args) => {
        // The new state: args.state
    }
);

BleManagerDiscoverPeripheral

The scanning find a new peripheral.

Arguments

  • id - String - the id of the peripheral
  • name - String - the name of the peripheral
  • rssi - Number - the RSSI value
  • advertising - JSON - the advertising payload, according to platforms:
    • [Android] contains the raw bytes and data (Base64 encoded string)
    • [iOS] contains a JSON object with different keys according to Apple's doc, here are some examples:
      • kCBAdvDataChannel - Number
      • kCBAdvDataIsConnectable - Number
      • kCBAdvDataLocalName - String
      • kCBAdvDataManufacturerData - JSON - contains the raw bytes and data (Base64 encoded string)

Examples

bleManagerEmitter.addListener(
    'BleManagerDiscoverPeripheral',
    (args) => {
        // The id: args.id
        // The name: args.name
    }
);

BleManagerDidUpdateValueForCharacteristic

A characteristic notify a new value.

Arguments

  • peripheral - String - the id of the peripheral
  • characteristic - String - the UUID of the characteristic
  • value - String - the read value in Hex format

BleManagerConnectPeripheral

A peripheral was connected.

Arguments

  • peripheral - String - the id of the peripheral

BleManagerDisconnectPeripheral

A peripheral was disconnected.

Arguments

  • peripheral - String - the id of the peripheral