react-native-ble-manager
Version:
A BLE module for react native.
371 lines (370 loc) • 17.2 kB
TypeScript
import { EventSubscription } from 'react-native';
import { BleState, ConnectOptions, ConnectionPriority, CompanionScanOptions, Peripheral, PeripheralInfo, ScanOptions, StartOptions, EventCallback, BleConnectPeripheralEvent, BleDiscoverPeripheralEvent, BleStopScanEvent, BleManagerDidUpdateStateEvent, BleDisconnectPeripheralEvent, BleManagerDidUpdateValueForCharacteristicEvent, BleBondedPeripheralEvent, BleManagerCentralManagerWillRestoreState, BleManagerDidUpdateNotificationStateForEvent, BleManagerCompanionPeripheral } from './types';
export * from './types';
declare class BleManager {
constructor();
/**
* Read the current value of the specified characteristic, you need to call `retrieveServices` method before.
*
* @param peripheralId The id/mac address of the peripheral.
* @param serviceUUID The UUID of the service.
* @param characteristicUUID The UUID of the characteristic.
* @returns Data as an array of numbers (which can be converted back to a Uint8Array (ByteArray) using something like [Buffer.from()](https://github.com/feross/buffer))
*/
read(peripheralId: string, serviceUUID: string, characteristicUUID: string): Promise<number[]>;
/**
* Read the current value of the specified descriptor, you need to call `retrieveServices` method before.
*
* @param peripheralId The id/mac address of the peripheral.
* @param serviceUUID The UUID of the service.
* @param characteristicUUID The UUID of the characteristic.
* @param descriptorUUID The UUID of the descriptor.
* @returns data as an array of numbers (which can be converted back to a Uint8Array (ByteArray) using something like [Buffer.from()](https://github.com/feross/buffer))
*/
readDescriptor(peripheralId: string, serviceUUID: string, characteristicUUID: string, descriptorUUID: string): Promise<number[]>;
/**
* Write a value to the specified descriptor, you need to call `retrieveServices` method before.
*
* @param peripheralId The id/mac address of the peripheral.
* @param serviceUUID The UUID of the service.
* @param characteristicUUID The UUID of the characteristic.
* @param descriptorUUID The UUID of the descriptor.
* @param data Data to write as an array of numbers (which can be converted from a Uint8Array (ByteArray) using something like [Buffer.toJSON().data](https://github.com/feross/buffer))
* @returns
*/
writeDescriptor(peripheralId: string, serviceUUID: string, characteristicUUID: string, descriptorUUID: string, data: number[]): Promise<void>;
/**
* Read the current value of the RSSI.
*
* @param peripheralId The id/mac address of the peripheral.
* @returns A promise resolving with the updated RSSI (`number`) if it succeeds.
*/
readRSSI(peripheralId: string): Promise<number>;
/**
* [Android only]
*
* Refreshes the peripheral's services and characteristics cache.
*
* @param peripheralId The id/mac address of the peripheral.
* @returns A promise that resolves to a boolean indicating if gatt was successfully refreshed or not.
*/
refreshCache(peripheralId: string): Promise<boolean>;
/**
* Retrieve the peripheral's services and characteristics.
*
* @param peripheralId The id/mac address of the peripheral.
* @param serviceUUIDs [iOS only] Optional filter of services to retrieve.
* @returns
*/
retrieveServices(peripheralId: string, serviceUUIDs?: string[]): Promise<PeripheralInfo>;
/**
* Write with response to the specified characteristic, you need to call `retrieveServices` method before.
*
* @param peripheralId The id/mac address of the peripheral.
* @param serviceUUID The UUID of the service.
* @param characteristicUUID The UUID of the characteristic.
* @param data Data to write as an array of numbers (which can be converted from a Uint8Array (ByteArray) using something like [Buffer.toJSON().data](https://github.com/feross/buffer))
* @param maxByteSize Optional, defaults to 20
* @returns
*/
write(peripheralId: string, serviceUUID: string, characteristicUUID: string, data: number[], maxByteSize?: number): Promise<void>;
/**
* Write without response to the specified characteristic, you need to call `retrieveServices` method before.
*
* @param peripheralId The id/mac address of the peripheral.
* @param serviceUUID The UUID of the service.
* @param characteristicUUID The UUID of the characteristic.
* @param data Data to write as an array of numbers (which can be converted from a Uint8Array (ByteArray) using something like [Buffer.toJSON().data](https://github.com/feross/buffer))
* @param maxByteSize Optional, defaults to 20
* @param queueSleepTime Optional, defaults to 10. Only useful if data length is greater than maxByteSize.
* @returns
*/
writeWithoutResponse(peripheralId: string, serviceUUID: string, characteristicUUID: string, data: number[], maxByteSize?: number, queueSleepTime?: number): Promise<void>;
/**
* Attempts to connect to a peripheral. In many case if you can't connect you have to scan for the peripheral before.
*
* > In iOS, attempts to connect to a peripheral do not time out (please see [Apple's doc](https://developer.apple.com/documentation/corebluetooth/cbcentralmanager/1518766-connect)), so you might need to set a timer explicitly if you don't want this behavior.
*/
connect(peripheralId: string, options?: ConnectOptions): Promise<void>;
/**
* [Android only]
*
* Start the bonding (pairing) process with the remote device.
* If you pass peripheralPin (optional), bonding will be auto (without manually entering the pin).
* > Ensure to make one bond request at a time.
*
* @param peripheralId The id/mac address of the peripheral.
* @param peripheralPin Optional. will be used to auto-bond if possible.
* @returns
*/
createBond(peripheralId: string, peripheralPin?: string | null): Promise<void>;
/**
* [Android only]
*
* Remove a paired device.
*
* @param peripheralId The id/mac address of the peripheral
* @returns
*/
removeBond(peripheralId: string): Promise<void>;
/**
* Disconnect from a peripheral.
*
* @param peripheralId The id/mac address of the peripheral to disconnect.
* @param force [Android only] Defaults to true. Don't wait for the disconnect state to close the Gatt client.
* @returns
*/
disconnect(peripheralId: string, force?: boolean): Promise<void>;
/**
* Start the notification on the specified characteristic, you need to call `retrieveServices` method before.
*
* Events will be send to `onDidUpdateValueForCharacteristic` when the peripheral notifies a new value for the characteristic.
*
* @param peripheralId The id/mac address of the peripheral.
* @param serviceUUID The UUID of the service.
* @param characteristicUUID The UUID of the characteristic.
* @returns
*/
startNotification(peripheralId: string, serviceUUID: string, characteristicUUID: string): Promise<void>;
/**
* [Android only]
*
* Start the notification on the specified characteristic, you need to call `retrieveServices` method before.
* The buffer collect messages until the buffer of messages bytes reaches the limit defined with the `buffer` argument and then emit all the collected data.
* Useful to reduce the number of calls between the native and the react-native part in case of many messages.
*
* @param peripheralId The id/mac address of the peripheral.
* @param serviceUUID The UUID of the service.
* @param characteristicUUID The UUID of the characteristic.
* @param buffer The capacity of the buffer (bytes) stored before emitting the data for the characteristic.
* @returns
*/
startNotificationWithBuffer(peripheralId: string, serviceUUID: string, characteristicUUID: string, buffer: number): Promise<void>;
/**
* Stop the notification on the specified characteristic.
*
* @param peripheralId The id/mac address of the peripheral.
* @param serviceUUID The UUID of the service.
* @param characteristicUUID The UUID of the characteristic.
* @returns
*/
stopNotification(peripheralId: string, serviceUUID: string, characteristicUUID: string): Promise<void>;
/**
* Force the module to check the state of the native BLE manager and trigger an event for `onDidUpdateState`.
* @returns A promise containing the current BleState
*/
checkState(): Promise<BleState>;
/**
* Init the module. Don't call this multiple times.
*/
start(options?: StartOptions): Promise<void>;
/**
* Check if the BLE manager has been started.
* @returns boolean promise indicating if the manager is started.
*/
isStarted(): Promise<boolean>;
/**
* Scan for available peripherals.
*
* See `onDiscoverPeripheral` to get live updates of devices being discovered.
*
* See `getDiscoveredPeripherals` to get a list of discovered devices after a scan is completed.
*
* @param scanningOptions Optional map of properties to fine-tune scan behavior, see DOCS.
* @returns
*/
scan(scanningOptions?: ScanOptions): Promise<void>;
/**
* Stop the scanning.
*/
stopScan(): Promise<void>;
/**
* [Android only] triggers an ENABLE_REQUEST intent to the end-user to enable bluetooth.
* @returns
*/
enableBluetooth(): Promise<void>;
/**
* Return the connected peripherals.
*
* > In Android, Peripherals "advertising" property can be not set!
* > Will be available if peripheral was found through scan before connect.
* > This matches to current Android Bluetooth design specification.
*
* @param serviceUUIDs [iOS only] Optional, only retrieve peripherals with these services. Ignored in Android.
* @returns
*/
getConnectedPeripherals(serviceUUIDs?: string[]): Promise<Peripheral[]>;
/**
* [Android only]
*
* Return the bonded peripherals.
*
* @returns
*/
getBondedPeripherals(): Promise<Peripheral[]>;
/**
* Return the discovered peripherals after a scan.
*/
getDiscoveredPeripherals(): Promise<Peripheral[]>;
/**
* [Android only]
*
* 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.
*
* @param peripheralId The id/mac address of the peripheral.
* @returns
*/
removePeripheral(peripheralId: string): Promise<void>;
/**
* Check whether a specific peripheral is connected and return `true` or `false`.
*
* @param peripheralId The id/mac address of the peripheral.
* @param serviceUUIDs [iOS only] Optional, only retrieve peripherals with these services. Ignored in Android.
* @returns
*/
isPeripheralConnected(peripheralId: string, serviceUUIDs?: string[]): Promise<boolean>;
/**
* Checks whether the scan is in progress and return `true` or `false`.
* @returns
*/
isScanning(): Promise<boolean>;
/**
* [Android only, API 21+]
* @param peripheralId The id/mac address of the peripheral.
* @param connectionPriority The connection priority to be requested
* @returns A promise that resolves with a boolean indicating of the connection priority was changed successfully, or rejects with an error message.
*/
requestConnectionPriority(peripheralId: string, connectionPriority: ConnectionPriority): Promise<boolean>;
/**
* [Android only, API 21+]
*
* Request an MTU size used for a given connection.
*
* @param peripheralId The id/mac address of the peripheral.
* @param mtu Size to be requested, in bytes.
* @returns A promise resolving with the negotiated MTU if it succeeded. Beware that it might not be the one requested due to device's BLE limitations on both side of the negotiation.
*/
requestMTU(peripheralId: string, mtu: number): Promise<number>;
/**
* [Android only, API 26+]
*
* Retrieve associated peripherals (from companion manager).
*
* @returns
*/
getAssociatedPeripherals(): Promise<Peripheral[]>;
/**
* [Android only, API 26+]
*
* Remove an associated peripheral.
*
* @param peripheralId Peripheral to remove
* @returns Promise that resolves once the peripheral has been removed. Rejects
* if no association is found.
*/
removeAssociatedPeripheral(peripheralId: string): Promise<void>;
/**
* [Android only]
*
* Check if current device supports the companion device manager.
*
* @return Promise resolving to a boolean.
*/
supportsCompanion(): Promise<boolean>;
/**
* [Android only, API 26+]
*
* Scan for companion devices.
*
* Rejects if the companion device manager is not supported on this device.
*
* The promise it will eventually resolve with either:
*
* 1. peripheral if user selects one
* 2. null if user "cancels" (i.e. doesn't select anything)
*
* See `BleManager.supportsCompanion`.
*
* See: https://developer.android.com/develop/connectivity/bluetooth/companion-device-pairing
*
* @param serviceUUIDs List of service UUIDs to use as a filter
*/
companionScan(serviceUUIDs: string[], options?: CompanionScanOptions): Promise<Peripheral | null>;
/**
* [Android only]
*
* Create the request to set the name of the bluetooth adapter. (https://developer.android.com/reference/android/bluetooth/BluetoothAdapter#setName(java.lang.String))
*
* @param name
*/
setName(name: string): void;
/**
* [iOS only]
* @param peripheralId The id/mac address of the peripheral.
* @returns
*/
getMaximumWriteValueLengthForWithoutResponse(peripheralId: string): Promise<number>;
/**
* [iOS only]
* @param peripheralId The id/mac address of the peripheral.
* @returns
*/
getMaximumWriteValueLengthForWithResponse(peripheralId: string): Promise<number>;
/**
* The scanning found a new peripheral.
*/
onDiscoverPeripheral(callback: EventCallback<BleDiscoverPeripheralEvent>): EventSubscription;
/**
* The scanning for peripherals is ended.
*/
onStopScan(callback: EventCallback<BleStopScanEvent>): EventSubscription;
/**
* The BLE state changed.
*/
onDidUpdateState(callback: EventCallback<BleManagerDidUpdateStateEvent>): EventSubscription;
/**
* A peripheral was connected.
*/
onConnectPeripheral(callback: EventCallback<BleConnectPeripheralEvent>): EventSubscription;
/**
* A peripheral was disconnected.
*/
onDisconnectPeripheral(callback: EventCallback<BleDisconnectPeripheralEvent>): EventSubscription;
/**
* A characteristic notified a new value.
*
* > Event will only be emitted after successful `startNotification`.
*/
onDidUpdateValueForCharacteristic(callback: EventCallback<BleManagerDidUpdateValueForCharacteristicEvent>): EventSubscription;
/**
* A bond with a peripheral was established.
*/
onPeripheralDidBond(callback: EventCallback<BleBondedPeripheralEvent>): EventSubscription;
/**
* [iOS only]
*
* This is fired when [`centralManager:WillRestoreState:`](https://developer.apple.com/documentation/corebluetooth/cbcentralmanagerdelegate/1518819-centralmanager) is called (app relaunched in the background to handle a bluetooth event).
*
* _For more on performing long-term bluetooth actions in the background:_
*
* [iOS Bluetooth State Preservation and Restoration](https://developer.apple.com/library/archive/documentation/NetworkingInternetWeb/Conceptual/CoreBluetooth_concepts/CoreBluetoothBackgroundProcessingForIOSApps/PerformingTasksWhileYourAppIsInTheBackground.html#//apple_ref/doc/uid/TP40013257-CH7-SW10)
*
* [iOS Relaunch Conditions](https://developer.apple.com/documentation/technotes/tn3115-bluetooth-state-restoration-app-relaunch-rules/)
*/
onCentralManagerWillRestoreState(callback: EventCallback<BleManagerCentralManagerWillRestoreState>): EventSubscription;
/**
* [iOS only]
*
* The peripheral received a request to start or stop providing notifications for a specified characteristic's value.
*/
onDidUpdateNotificationStateFor(callback: EventCallback<BleManagerDidUpdateNotificationStateForEvent>): EventSubscription;
/**
* User picked a device to associate with.
*
* Null if the request was cancelled by the user.
*/
onCompanionPeripheral(callback: EventCallback<BleManagerCompanionPeripheral>): EventSubscription;
}
declare const _default: BleManager;
export default _default;