com.polidea.rxandroidble2

Interface RxBleConnection

All Known Implementing Classes:

RxBleConnectionImpl

public interface RxBleConnection

The BLE connection handle, supporting GATT operations. Operations are enqueued and the library makes sure that they are not executed in the same time within the client instance.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	RxBleConnection.ConnectionPriority Description of correct values of connection priority
static interface	RxBleConnection.Connector Deprecated.
static interface	RxBleConnection.LongWriteOperationBuilder The interface of a CharacteristicLongWriteOperation builder.
static class	RxBleConnection.RxBleConnectionState
static interface	RxBleConnection.WriteOperationAckStrategy
static interface	RxBleConnection.WriteOperationRetryStrategy Retry strategy allows retrying a long write operation.

Field Summary

Fields

Modifier and Type	Field and Description
static int	GATT_MTU_MAXIMUM The maximum supported value for MTU (Maximum Transfer Unit) used by a bluetooth connection on Android OS.
static int	GATT_MTU_MINIMUM The minimum (default) value for MTU (Maximum Transfer Unit) used by a bluetooth connection.
static int	GATT_READ_MTU_OVERHEAD The overhead value that is subtracted from the amount of bytes available when reading from a characteristic.
static int	GATT_WRITE_MTU_OVERHEAD The overhead value that is subtracted from the amount of bytes available when writing to a characteristic.

Method Summary

Modifier and Type	Method and Description
RxBleConnection.LongWriteOperationBuilder	createNewLongWriteBuilder() Returns a LongWriteOperationBuilder used for creating atomic write operations divided into multiple writes.
<any>	discoverServices() Performs GATT service discovery and emits discovered results.
<any>	discoverServices(long timeout, java.util.concurrent.TimeUnit timeUnit) Performs GATT service discovery and emits discovered results.
<any>	getCharacteristic(java.util.UUID characteristicUuid) Deprecated.
int	getMtu() Get currently negotiated MTU value.
<any>	observeConnectionParametersUpdates() Allows observing of connection parameters updates.
<T> <any>	queue(RxBleCustomOperation<T> operation) This method requires deep knowledge of RxAndroidBLE internals.
<T> <any>	queue(RxBleCustomOperation<T> operation, Priority priority) This method requires deep knowledge of RxAndroidBLE internals.
<any>	readCharacteristic(android.bluetooth.BluetoothGattCharacteristic characteristic) Performs GATT read operation on a given characteristic.
<any>	readCharacteristic(java.util.UUID characteristicUuid) Performs GATT read operation on a characteristic with given UUID.
<any>	readDescriptor(android.bluetooth.BluetoothGattDescriptor descriptor) Performs GATT read operation on a descriptor from a characteristic with a given UUID from a service with a given UUID.
<any>	readDescriptor(java.util.UUID serviceUuid, java.util.UUID characteristicUuid, java.util.UUID descriptorUuid) Performs GATT read operation on a descriptor from a characteristic with a given UUID from a service with a given UUID.
<any>	readRssi() Performs GATT read rssi operation.
Completable	requestConnectionPriority(int connectionPriority, long delay, java.util.concurrent.TimeUnit timeUnit) Performs a GATT request connection priority operation, which requests a connection parameter update on the remote device.
<any>	requestMtu(int mtu) Performs GATT MTU (Maximum Transfer Unit) request.
<any>	setupIndication(android.bluetooth.BluetoothGattCharacteristic characteristic)
<any>	setupIndication(android.bluetooth.BluetoothGattCharacteristic characteristic, NotificationSetupMode setupMode) Setup characteristic indication in order to receive callbacks when given characteristic has been changed.
<any>	setupIndication(java.util.UUID characteristicUuid)
<any>	setupIndication(java.util.UUID characteristicUuid, NotificationSetupMode setupMode) Setup characteristic indication in order to receive callbacks when given characteristic has been changed.
<any>	setupNotification(android.bluetooth.BluetoothGattCharacteristic characteristic)
<any>	setupNotification(android.bluetooth.BluetoothGattCharacteristic characteristic, NotificationSetupMode setupMode) Setup characteristic notification in order to receive callbacks when given characteristic has been changed.
<any>	setupNotification(java.util.UUID characteristicUuid)
<any>	setupNotification(java.util.UUID characteristicUuid, NotificationSetupMode setupMode) Setup characteristic notification in order to receive callbacks when given characteristic has been changed.
<any>	writeCharacteristic(android.bluetooth.BluetoothGattCharacteristic bluetoothGattCharacteristic, byte[] data) Performs GATT write operation on a given characteristic.
<any>	writeCharacteristic(java.util.UUID characteristicUuid, byte[] data) Performs GATT write operation on a characteristic with given UUID.
Completable	writeDescriptor(android.bluetooth.BluetoothGattDescriptor descriptor, byte[] data) Performs GATT write operation on a given descriptor.
Completable	writeDescriptor(java.util.UUID serviceUuid, java.util.UUID characteristicUuid, java.util.UUID descriptorUuid, byte[] data) Performs GATT write operation on a descriptor from a characteristic with a given UUID from a service with a given UUID.

Field Detail

GATT_WRITE_MTU_OVERHEAD

static final int GATT_WRITE_MTU_OVERHEAD

The overhead value that is subtracted from the amount of bytes available when writing to a characteristic. The default MTU value on Android is 23 bytes which gives effectively 23 - GATT_WRITE_MTU_OVERHEAD = 20 bytes available for payload.

See Also:

Constant Field Values

GATT_READ_MTU_OVERHEAD

static final int GATT_READ_MTU_OVERHEAD

The overhead value that is subtracted from the amount of bytes available when reading from a characteristic. The default MTU value on Android is 23 bytes which gives effectively 23 - GATT_READ_MTU_OVERHEAD = 22 bytes available for payload.

See Also:

Constant Field Values

GATT_MTU_MINIMUM

static final int GATT_MTU_MINIMUM

The minimum (default) value for MTU (Maximum Transfer Unit) used by a bluetooth connection.

See Also:

Constant Field Values

GATT_MTU_MAXIMUM

static final int GATT_MTU_MAXIMUM

The maximum supported value for MTU (Maximum Transfer Unit) used by a bluetooth connection on Android OS. https://android.googlesource.com/platform/external/bluetooth/bluedroid/+/android-5.1.0_r1/stack/include/gatt_api.h#119

See Also:

Constant Field Values

Method Detail

discoverServices

<any> discoverServices()

Performs GATT service discovery and emits discovered results. After service discovery you can walk through BluetoothGattServices and BluetoothGattCharacteristics.

Result of the discovery is cached internally so consecutive calls won't trigger BLE operation and can be considered relatively lightweight. Uses default timeout of 20 seconds

Returns:

Observable emitting result a GATT service discovery.

Throws:

BleGattCannotStartException - with BleGattOperationType.SERVICE_DISCOVERY type, when it wasn't possible to start the discovery for internal reasons.

BleGattException - in case of GATT operation error with BleGattOperationType.SERVICE_DISCOVERY type.

discoverServices

<any> discoverServices(long timeout,
                       java.util.concurrent.TimeUnit timeUnit)

Performs GATT service discovery and emits discovered results. After service discovery you can walk through BluetoothGattServices and BluetoothGattCharacteristics.

Result of the discovery is cached internally so consecutive calls won't trigger BLE operation and can be considered relatively lightweight. Timeouts after specified amount of time.

Parameters:

timeout - multiplier of TimeUnit after which the discovery will timeout in case of no return values

timeUnit - TimeUnit for the timeout

Returns:

Observable emitting result a GATT service discovery.

Throws:

BleGattCannotStartException - with BleGattOperationType.SERVICE_DISCOVERY type, when it wasn't possible to start the discovery for internal reasons.

BleGattException - in case of GATT operation error with BleGattOperationType.SERVICE_DISCOVERY type.

setupNotification

<any> setupNotification(java.util.UUID characteristicUuid)

See Also:

with default setup mode.

setupNotification

<any> setupNotification(android.bluetooth.BluetoothGattCharacteristic characteristic)

See Also:

with default setup mode.

setupNotification

<any> setupNotification(java.util.UUID characteristicUuid,
                        NotificationSetupMode setupMode)

Setup characteristic notification in order to receive callbacks when given characteristic has been changed. Returned observable will emit Observable once the notification setup has been completed. It is possible to setup more observables for the same characteristic and the lifecycle of the notification will be shared among them.

Notification is automatically unregistered once this observable is unsubscribed. NOTE: due to stateful nature of characteristics if one will setupIndication() before setupNotification() the notification will not be set up and will emit an BleCharacteristicNotificationOfOtherTypeAlreadySetException

Parameters:

characteristicUuid - Characteristic UUID for notification setup.

setupMode - Configures how the notification is set up. For available modes see NotificationSetupMode.

Returns:

Observable emitting another observable when the notification setup is complete.

Throws:

BleCharacteristicNotFoundException - if characteristic with given UUID hasn't been found.

BleCannotSetCharacteristicNotificationException - if setup process notification setup process fail. This may be an internal reason or lack of permissions.

BleConflictingNotificationAlreadySetException - if indication is already setup for this characteristic

setupNotification

<any> setupNotification(android.bluetooth.BluetoothGattCharacteristic characteristic,
                        NotificationSetupMode setupMode)

Setup characteristic notification in order to receive callbacks when given characteristic has been changed. Returned observable will emit Observable once the notification setup has been completed. It is possible to setup more observables for the same characteristic and the lifecycle of the notification will be shared among them.

Notification is automatically unregistered once this observable is unsubscribed.

NOTE: due to stateful nature of characteristics if one will setupIndication() before setupNotification() the notification will not be set up and will emit an BleCharacteristicNotificationOfOtherTypeAlreadySetException

The characteristic can be retrieved from RxBleDeviceServices emitted from discoverServices()

Parameters:

characteristic - Characteristic for notification setup.

setupMode - Configures how the notification is set up. For available modes see NotificationSetupMode.

Returns:

Observable emitting another observable when the notification setup is complete.

Throws:

BleCannotSetCharacteristicNotificationException - if setup process notification setup process fail. This may be an internal reason or lack of permissions.

BleConflictingNotificationAlreadySetException - if indication is already setup for this characteristic

setupIndication

<any> setupIndication(java.util.UUID characteristicUuid)

See Also:

with default setup mode.

setupIndication

<any> setupIndication(android.bluetooth.BluetoothGattCharacteristic characteristic)

See Also:

with default setup mode.

setupIndication

<any> setupIndication(java.util.UUID characteristicUuid,
                      NotificationSetupMode setupMode)

Setup characteristic indication in order to receive callbacks when given characteristic has been changed. Returned observable will emit Observable once the indication setup has been completed. It is possible to setup more observables for the same characteristic and the lifecycle of the indication will be shared among them.

Indication is automatically unregistered once this observable is unsubscribed.

NOTE: due to stateful nature of characteristics if one will setupNotification() before setupIndication() the indication will not be set up and will emit an BleCharacteristicNotificationOfOtherTypeAlreadySetException

Parameters:

characteristicUuid - Characteristic UUID for indication setup.

setupMode - Configures how the notification is set up. For available modes see NotificationSetupMode.

Returns:

Observable emitting another observable when the indication setup is complete.

Throws:

BleCharacteristicNotFoundException - if characteristic with given UUID hasn't been found.

BleCannotSetCharacteristicNotificationException - if setup process indication setup process fail. This may be an internal reason or lack of permissions.

BleConflictingNotificationAlreadySetException - if notification is already setup for this characteristic

setupIndication

<any> setupIndication(android.bluetooth.BluetoothGattCharacteristic characteristic,
                      NotificationSetupMode setupMode)

Setup characteristic indication in order to receive callbacks when given characteristic has been changed. Returned observable will emit Observable once the indication setup has been completed. It is possible to setup more observables for the same characteristic and the lifecycle of the indication will be shared among them.

Indication is automatically unregistered once this observable is unsubscribed.

NOTE: due to stateful nature of characteristics if one will setupNotification() before setupIndication() the indication will not be set up and will emit an BleCharacteristicNotificationOfOtherTypeAlreadySetException

The characteristic can be retrieved from RxBleDeviceServices emitted from discoverServices()

Parameters:

characteristic - Characteristic for indication setup.

setupMode - Configures how the notification is set up. For available modes see NotificationSetupMode.

Returns:

Observable emitting another observable when the indication setup is complete.

Throws:

BleCannotSetCharacteristicNotificationException - if setup process indication setup process fail. This may be an internal reason or lack of permissions.

BleConflictingNotificationAlreadySetException - if notification is already setup for this characteristic

getCharacteristic

@Deprecated
<any> getCharacteristic(java.util.UUID characteristicUuid)

Deprecated.

Convenience method for characteristic retrieval. First step is service discovery which is followed by service/characteristic traversal. This is an alias to:

1. discoverServices()
2. RxBleDeviceServices.getCharacteristic(UUID)

Parameters:

characteristicUuid - Requested characteristic UUID.

Returns:

Observable emitting matching characteristic or error if hasn't been found.

Throws:

BleCharacteristicNotFoundException - if characteristic with given UUID hasn't been found.

readCharacteristic

<any> readCharacteristic(java.util.UUID characteristicUuid)

Performs GATT read operation on a characteristic with given UUID.

Parameters:

characteristicUuid - Requested characteristic UUID.

Returns:

Observable emitting characteristic value or an error in case of failure.

Throws:

BleCharacteristicNotFoundException - if characteristic with given UUID hasn't been found.

BleGattCannotStartException - if read operation couldn't be started for internal reason.

BleGattException - if read operation failed

readCharacteristic

<any> readCharacteristic(android.bluetooth.BluetoothGattCharacteristic characteristic)

Performs GATT read operation on a given characteristic.

Parameters:

characteristic - Requested characteristic.

Returns:

Observable emitting characteristic value or an error in case of failure.

Throws:

BleGattCannotStartException - if read operation couldn't be started for internal reason.

BleGattException - if read operation failed

See Also:

to obtain the characteristic., to obtain the characteristic.

writeCharacteristic

<any> writeCharacteristic(java.util.UUID characteristicUuid,
                          byte[] data)

Performs GATT write operation on a characteristic with given UUID.

Parameters:

characteristicUuid - Requested characteristic UUID.

Returns:

Observable emitting characteristic value after write or an error in case of failure.

Throws:

BleCharacteristicNotFoundException - if characteristic with given UUID hasn't been found.

BleGattCannotStartException - if write operation couldn't be started for internal reason.

BleGattException - if write operation failed

writeCharacteristic

<any> writeCharacteristic(android.bluetooth.BluetoothGattCharacteristic bluetoothGattCharacteristic,
                          byte[] data)

Performs GATT write operation on a given characteristic.

Parameters:

bluetoothGattCharacteristic - Characteristic to write.

data - the byte array to write

Returns:

Observable emitting written data or an error in case of failure.

Throws:

BleGattCannotStartException - if write operation couldn't be started for internal reason.

BleGattException - if write operation failed

See Also:

to obtain the characteristic., to obtain the characteristic.

createNewLongWriteBuilder

RxBleConnection.LongWriteOperationBuilder createNewLongWriteBuilder()

Returns a LongWriteOperationBuilder used for creating atomic write operations divided into multiple writes. This is useful when the BLE peripheral does NOT handle long writes on the firmware level (in which situation a regular writeCharacteristic(UUID, byte[]) should be sufficient.

Returns:

the LongWriteOperationBuilder

readDescriptor

<any> readDescriptor(java.util.UUID serviceUuid,
                     java.util.UUID characteristicUuid,
                     java.util.UUID descriptorUuid)

Performs GATT read operation on a descriptor from a characteristic with a given UUID from a service with a given UUID.

Parameters:

serviceUuid - Requested BluetoothGattService UUID

characteristicUuid - Requested BluetoothGattCharacteristic UUID

descriptorUuid - Requested BluetoothGattDescriptor UUID

Returns:

Observable emitting the descriptor value after read or an error in case of failure.

Throws:

BleGattCannotStartException - if read operation couldn't be started for internal reason.

BleGattException - if read operation failed

See Also:

to obtain the characteristic., to obtain the characteristic.

readDescriptor

<any> readDescriptor(android.bluetooth.BluetoothGattDescriptor descriptor)

Performs GATT read operation on a descriptor from a characteristic with a given UUID from a service with a given UUID.

Parameters:

descriptor - Requested BluetoothGattDescriptor

Returns:

Observable emitting the descriptor value after read or an error in case of failure.

Throws:

BleGattCannotStartException - if read operation couldn't be started for internal reason.

BleGattException - if read operation failed

See Also:

to obtain the characteristic from which you can get the {@link BluetoothGattDescriptor}., to obtain the {@link BluetoothGattDescriptor}.

writeDescriptor

Completable writeDescriptor(java.util.UUID serviceUuid,
                            java.util.UUID characteristicUuid,
                            java.util.UUID descriptorUuid,
                            byte[] data)

Performs GATT write operation on a descriptor from a characteristic with a given UUID from a service with a given UUID.

Parameters:

serviceUuid - Requested BluetoothGattDescriptor UUID

characteristicUuid - Requested BluetoothGattCharacteristic UUID

descriptorUuid - Requested BluetoothGattDescriptor UUID

Returns:

Completable which completes after a successful write operation or an error in case of failure.

Throws:

BleGattCannotStartException - if write operation couldn't be started for internal reason.

BleGattException - if write operation failed

writeDescriptor

Completable writeDescriptor(android.bluetooth.BluetoothGattDescriptor descriptor,
                            byte[] data)

Performs GATT write operation on a given descriptor.

Parameters:

descriptor - Requested BluetoothGattDescriptor

Returns:

Completable which completes after a successful write operation or an error in case of failure.

Throws:

BleGattCannotStartException - if write operation couldn't be started for internal reason.

BleGattException - if write operation failed

See Also:

to obtain the characteristic., to obtain the characteristic.

requestConnectionPriority

Completable requestConnectionPriority(int connectionPriority,
                                      long delay,
                                      java.util.concurrent.TimeUnit timeUnit)

Performs a GATT request connection priority operation, which requests a connection parameter update on the remote device. NOTE: peripheral may silently decline request.

Tells Android to request an update of connection interval and slave latency parameters. Using BluetoothGatt.CONNECTION_PRIORITY_HIGH will increase transmission speed and battery drainage, if accepted by the device, compared to BluetoothGatt.CONNECTION_PRIORITY_BALANCED, while using BluetoothGatt.CONNECTION_PRIORITY_LOW_POWER will cause higher latencies and save battery, if accepted by the device, compared to BluetoothGatt.CONNECTION_PRIORITY_BALANCED.

By default connection is balanced.

NOTE: Till API 26 (8.0) there was no method like `BluetoothGattCallback.onConnectionPriorityChanged()`. It was not possible to know if the request was successful (accepted by the peripheral). This also causes the need of specifying when the request is considered finished (parameter delay and timeUnit). Since API 26 the mentioned callback is hidden, yet possible to use. It is not used to automatically complete this request due to Android OS changing connection parameters on its own. It is not possible to determine which callback is actually finishing the request nor if the Android OS will not change the parameters right after the request. If access to the callback is a must for your implementation you may achieve it by RxBleGattCallback.setHiddenNativeCallback(HiddenBluetoothGattCallback) via queue(RxBleCustomOperation) and create a custom request connection priority operation.

As of Lollipop the connection parameters are: * BluetoothGatt.CONNECTION_PRIORITY_BALANCED: min interval 30 ms, max interval 50 ms, slave latency 0 * BluetoothGatt.CONNECTION_PRIORITY_HIGH: min interval 7.5 ms, max interval 10ms, slave latency 0 * BluetoothGatt.CONNECTION_PRIORITY_LOW_POWER: min interval 100ms, max interval 125 ms, slave latency 2

Returned completable completes after the specified delay if and only if BluetoothGatt.requestConnectionPriority(int) has returned true.

Parameters:

connectionPriority - requested connection priority

delay - delay after which operation is assumed to be successful (must be shorter than 30 seconds)

timeUnit - time unit of the delay

Returns:

Completable which finishes after calling the request and the specified delay

Throws:

BleGattCannotStartException - with BleGattOperationType.CONNECTION_PRIORITY_CHANGE type if requested operation returned false or threw exception

java.lang.IllegalArgumentException - in case of invalid connection priority or delay

observeConnectionParametersUpdates

<any> observeConnectionParametersUpdates()

Allows observing of connection parameters updates. This is part of Android's hidden API and therefore is not guaranteed to work. It was added in API 26 (8.0, Oreo) in BluetoothGattCallback and will not work on lower API levels at all. The system does change the parameters on its own at the beginning of connection (i.e. to speed up service discovery process). The parameters may be further changed by using requestConnectionPriority(int, long, TimeUnit).

Returns:

Observable which may emit updates of the connection parameters

readRssi

<any> readRssi()

Performs GATT read rssi operation.

Returns:

Observable emitting the read RSSI value

requestMtu

<any> requestMtu(int mtu)

Performs GATT MTU (Maximum Transfer Unit) request. Timeouts after 10 seconds.

Returns:

Observable emitting result the MTU requested.

Throws:

BleGattCannotStartException - with BleGattOperationType.ON_MTU_CHANGED type, when it wasn't possible to set the MTU for internal reasons.

BleGattException - in case of GATT operation error with BleGattOperationType.ON_MTU_CHANGED type.

getMtu

int getMtu()

Get currently negotiated MTU value. On pre-lollipop Android versions it will always return 23.

Returns:

currently negotiated MTU value.

queue

<T> <any> queue(RxBleCustomOperation<T> operation)

This method requires deep knowledge of RxAndroidBLE internals. Use it only as a last resort if you know what your are doing.

Queue an operation for future execution. The method accepts a RxBleCustomOperation concrete implementation and will queue it inside connection operation queue. When ready to execute, the Observable returned by the RxBleCustomOperation.asObservable(BluetoothGatt, RxBleGattCallback, Scheduler) will be subscribed to.

Every event emitted by the Observable returned by RxBleCustomOperation.asObservable(BluetoothGatt, RxBleGattCallback, Scheduler) will be forwarded to the Observable returned by this method.

You must ensure the custom operation's Observable does terminate either via onCompleted or onError(Throwable). Otherwise, the internal queue orchestrator will wait forever for your Observable to complete. Normal queue processing will be resumed after the Observable returned by RxBleCustomOperation.asObservable(BluetoothGatt, RxBleGattCallback, Scheduler) completes.

The operation will be added to the queue using a Priority.NORMAL priority.

Type Parameters:

T - The type returned by the RxBleCustomOperation instance.

Parameters:

operation - The custom operation to queue.

Returns:

Observable emitting the value after execution or an error in case of failure.

queue

<T> <any> queue(RxBleCustomOperation<T> operation,
                Priority priority)

This method requires deep knowledge of RxAndroidBLE internals. Use it only as a last resort if you know what your are doing.

Queue an operation for future execution. The method accepts a RxBleCustomOperation concrete implementation and will queue it inside connection operation queue. When ready to execute, the Observable returned by the RxBleCustomOperation.asObservable(BluetoothGatt, RxBleGattCallback, Scheduler) will be subscribed to.

Every event emitted by the Observable returned by RxBleCustomOperation.asObservable(BluetoothGatt, RxBleGattCallback, Scheduler) will be forwarded to the Observable returned by this method.

You must ensure the custom operation's Observable does terminate either via onCompleted or onError(Throwable). Otherwise, the internal queue orchestrator will wait forever for your Observable to complete. Normal queue processing will be resumed after the Observable returned by RxBleCustomOperation.asObservable(BluetoothGatt, RxBleGattCallback, Scheduler) completes.

Type Parameters:

T - The type returned by the RxBleCustomOperation instance.

Parameters:

operation - The custom operation to queue.

priority - Priority affected to this operation

Returns:

Observable emitting the value after execution or an error in case of failure.