BluetoothZ

Bluetooth Low Energy (BLE) is a wireless communication technology designed for low-power devices. It is a variant of the Bluetooth standard that was introduced in 2010 as part of the Bluetooth 4.0 specification. BLE is now widely used in various IoT applications, such as wearable devices, sensors, and other low-power devices.

The purpose of this project is to make the native Bluetooth LE(not classic Bluetooth) functionalities available on Android/iOS platforms accessible via Javascript.

---

Features

With this library, you can perform the following operations:

• Scan for nearby Bluetooth LE devices
• Observe the Bluetooth's adapter state changes
• Connect and discover the characteristics and services of Bluetooth LE peripherals
• Multiple peripheral connection
• Automatic reconnection with custom numbers of attempts
• Read and write Bluetooth LE characteristics
• Observe the values of characteristics that support notification/indication mode

---

Installation

To install the package, simply:

npm install react-native-bluetoothz

iOS

For the iOS platform, the following steps are required:

• Update pods

  cd ios && pod install

• Add NSBluetoothAlwaysUsageDescription(mandatory since iOS 13) key in Info.plist file.

Android

For Android platform, the following steps are required:

• Minimum SDK version, in top level build.gradle file, needs to be at least 21.

  ...
  buildscript {
   ext {
       ...
       minSdkVersion = 21
   }
   ...

---

Import

Import all the library

import * as bleLibrary from 'react-native-bluetoothz';

Import single funcionality

import { adapterStatus } from 'react-native-bluetoothz';

---

API

Get adapter status

Returns the current state of the Bluetooth adapter.

async function adapterStatus();

Returned value can be one of the following defines:

• BLE_ADAPTER_STATUS_POWERED_ON
• BLE_ADAPTER_STATUS_POWERED_OFF
• BLE_ADAPTER_STATUS_INVALID
• BLE_ADAPTER_STATUS_UNKNOW

Scan devices

Start the scan procedure for discover nearby Bluetooth LE devices

/**
* @param services - Array of strings. Represents the UUIDs of the services you want to discover.
* @param filter   - String. The parameter is used to filter devices by name using regular expression passed.
* @param timeout  - Number. It represents the number of seconds after which the scan is stopped. Passing 0(or a negative number) means the scan will never stops. Default value is Defines.SCAN_TIMEOUT_MSEC = 10s
*/

function startScan({ services : Array<string>, filter : string, timeout : number = Defines.SCAN_TIMEOUT_MSEC })

discovered devices can be observed with BLE_PERIPHERAL_FOUND event.

Manually stop scan

Stop the scan procedure

function stopScan()

Connect to device

Initiate the connection with the device

/**
* @param uuid             - String. Represents the UUIDs of the device.
* @param maxRetryCount    - Number. Represents the maximum number of attempts to establish a connection. Default value is Defines.DEFAULT_MAX_RETRY_COUNT = 5
*/

function connect({ uuid, maxRetryCount = Defines.DEFAULT_MAX_RETRY_COUNT })

This events can be observed:

• BLE_PERIPHERAL_CONNECTED if the connection succedeed.
• BLE_PERIPHERAL_DISCONNECTED if device disconnect right after connection.
• BLE_PERIPHERAL_CONNECT_FAILED if the connection fails.

Disconnect to device

Disconnect from a connected device

/**
* @param uuid - String. Represents the UUIDs of the connected device.
*/

function disconnect({ uuid })

This events can be observed:

• BLE_PERIPHERAL_DISCONNECTED when device is disconnected.

Cancel a pending connection

Cancel the connection previously started to a device

/**
* @param uuid - String. Represents the UUIDs of the device.
*/

function cancel({ uuid })

This events can be observed:

• BLE_PERIPHERAL_DISCONNECTED when device is disconnected.

Reading characteristic's value

Cancel the connection previously started to a device

/**
* @param uuid     - String. Represents the UUIDs of the device.
* @param charUUID - String. Represents the UUIDs of the characteristic.
*/

function readCharacteristic({ uuid, charUUID })

This events can be observed:

• BLE_PERIPHERAL_CHARACTERISTIC_READ_OK if the read from characteristic was successfull.
• BLE_PERIPHERAL_CHARACTERISTIC_READ_FAILED if the read from characteristic failed.

Change characteristc's notification/indication mode

Cancel the connection previously started to a device

/**
* @param uuid     - String. Represents the UUIDs of the device.
* @param charUUID - String. Represents the UUIDs of the characteristic.
* @param enable   - Bool. Represents the status of notification. true - enable notification, false - disable notification
*/

function changeCharacteristicNotification = ({ uuid, charUUID, enable })

This events can be observed:

• BLE_PERIPHERAL_NOTIFICATION_CHANGED if notification have been enabled or disabled.
• BLE_PERIPHERAL_ENABLE_NOTIFICATION_FAILED if enabling/disabling notification failed.

---

Listen to the events

The library exposes the following signals that can be observed via an EventListener.

BLE_ADAPTER_STATUS_DID_UPDATE

This event notifies the change in state of the Bluetooth adapter

addListener(BLE_ADAPTER_STATUS_DID_UPDATE, (status : string) => {}

where status is one of the following:

BLE_ADAPTER_STATUS_POWERED_ON;
BLE_ADAPTER_STATUS_POWERED_OFF;
BLE_ADAPTER_STATUS_INVALID;
BLE_ADAPTER_STATUS_UNKNOW;

BLE_PERIPHERAL_FOUND

This event notifies the discovery of a new device

...addListener(BLE_PERIPHERAL_FOUND, device => ...

where device is composed like:

/**
 * @param uuid - String. Identifier of the device
 * @param name - String. Local name of the device
 * @param rssi - Number. Received signal strength of the device
 */
const { uuid: string, name: string, rssi: number } = device;

BLE_PERIPHERAL_READY

This event notifies that services and characteristics have been discovered for a certain device

...addListener(BLE_PERIPHERAL_READY, device => ...

where device is composed like:

/**
 * @param uuid - String. Identifier of the device
 */
const { uuid: string } = device;

BLE_PERIPHERAL_CONNECTED

This event notifies that the device is connected

...addListener(BLE_PERIPHERAL_CONNECTED, device => ...

where device is composed like:

/**
 * @param uuid - String. Identifier of the device
 */
const { uuid: string } = device;

BLE_PERIPHERAL_DISCONNECTED

This event notifies that the device is disconnected

...addListener(BLE_PERIPHERAL_DISCONNECTED, device => ...

where device is composed like:

/**
 * @param uuid - String. Identifier of the device
 */
const { uuid: string } = device;

BLE_PERIPHERAL_CONNECT_FAILED

This event notifies that the connection failed

...addListener(BLE_PERIPHERAL_CONNECT_FAILED,  => info ...

where info is composed like:

/**
 * @param uuid  - String. Identifier of the device
 * @param error - String. Reason of the failure.
 */
const { uuid: string, error: string } = info;

BLE_PERIPHERAL_DISCOVER_SERVICES_FAILED

This event notifies that the service's discovering failed

...addListener(BLE_PERIPHERAL_DISCOVER_SERVICES_FAILED,  => info ...

where info is composed like:

/**
 * @param uuid  - String. Identifier of the device
 * @param error - String. Reason of the failure.
 */
const { uuid: string, error: string } = info;

BLE_PERIPHERAL_CHARACTERISTIC_DISCOVERED

This event notifies that a new characteristic have been found.

...addListener(BLE_PERIPHERAL_CHARACTERISTIC_DISCOVERED,  => data ...

where data is composed like:

/**
 * @param uuid      - String. Identifier of the device
 * @param charUUID  - String. Identifier of the characteristic.
 */
const { uuid: string, charUUID: string } = data;

BLE_PERIPHERAL_CHARACTERISTIC_READ_OK

This event notifies that the characteristic's value has been read.

...addListener(BLE_PERIPHERAL_CHARACTERISTIC_READ_OK,  => info ...

where info is composed like:

/**
 * @param uuid      - String. Identifier of the device
 * @param charUUID  - String. Identifier of the characteristic.
 * @param value     - Hex string. An hex string represent the characteristic's value.
 */
const { uuid: string, error: string } = device;

BLE_PERIPHERAL_CHARACTERISTIC_READ_FAILED

This event notifies that the connection failed

...addListener(BLE_PERIPHERAL_CONNECT_FAILED,  => info ...

where info is composed like:

/**
 * @param uuid  - String. Identifier of the device
 * @param error - String. Reason of the failure.
 */
const { uuid: string, error: string } = device;

BLE_PERIPHERAL_CHARACTERISTIC_WRITE_OK

This event notifies that the connection failed

...addListener(BLE_PERIPHERAL_CONNECT_FAILED,  => info ...

where info is composed like:

/**
 * @param uuid  - String. Identifier of the device
 * @param error - String. Reason of the failure.
 */
const { uuid: string, error: string } = device;

BLE_PERIPHERAL_CHARACTERISTIC_WRITE_FAILED

This event notifies that the connection failed

...addListener(BLE_PERIPHERAL_CONNECT_FAILED,  => info ...

where info is composed like:

/**
 * @param uuid  - String. Identifier of the device
 * @param error - String. Reason of the failure.
 */
const { uuid: string, error: string } = device;

BLE_PERIPHERAL_NOTIFICATION_UPDATES

This event notifies that the connection failed

...addListener(BLE_PERIPHERAL_CONNECT_FAILED,  => info ...

where info is composed like:

/**
 * @param uuid  - String. Identifier of the device
 * @param error - String. Reason of the failure.
 */
const { uuid: string, error: string } = device;

BLE_PERIPHERAL_ENABLE_NOTIFICATION_FAILED

This event notifies that the connection failed

...addListener(BLE_PERIPHERAL_CONNECT_FAILED,  => info ...

where info is composed like:

/**
 * @param uuid  - String. Identifier of the device
 * @param error - String. Reason of the failure.
 */
const { uuid: string, error: string } = device;

BLE_PERIPHERAL_NOTIFICATION_CHANGED

This event notifies that the connection failed

...addListener(BLE_PERIPHERAL_CONNECT_FAILED,  => info ...

where info is composed like:

/**
 * @param uuid  - String. Identifier of the device
 * @param error - String. Reason of the failure.
 */
const { uuid: string, error: string } = device;

---

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

---

License

MIT

---

Attribution

All icons used on this page are provided by Icon8.

---