react-native-bluetoothz v0.1.16
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
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.
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.