public interface RxBleConnection
| 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.
|
| 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.
|
| 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.
|
static final int GATT_WRITE_MTU_OVERHEAD
static final int GATT_READ_MTU_OVERHEAD
static final int GATT_MTU_MINIMUM
static final int GATT_MTU_MAXIMUM
<any> discoverServices()
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
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.<any> discoverServices(long timeout,
java.util.concurrent.TimeUnit timeUnit)
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.
timeout - multiplier of TimeUnit after which the discovery will timeout in case of no return valuestimeUnit - TimeUnit for the timeoutBleGattCannotStartException - 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.<any> setupNotification(java.util.UUID characteristicUuid)
with default setup mode.<any> setupNotification(android.bluetooth.BluetoothGattCharacteristic characteristic)
with default setup mode.<any> setupNotification(java.util.UUID characteristicUuid,
NotificationSetupMode setupMode)
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
characteristicUuid - Characteristic UUID for notification setup.setupMode - Configures how the notification is set up. For available modes see NotificationSetupMode.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<any> setupNotification(android.bluetooth.BluetoothGattCharacteristic characteristic,
NotificationSetupMode setupMode)
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()
characteristic - Characteristic for notification setup.setupMode - Configures how the notification is set up. For available modes see NotificationSetupMode.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<any> setupIndication(java.util.UUID characteristicUuid)
with default setup mode.<any> setupIndication(android.bluetooth.BluetoothGattCharacteristic characteristic)
with default setup mode.<any> setupIndication(java.util.UUID characteristicUuid,
NotificationSetupMode setupMode)
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
characteristicUuid - Characteristic UUID for indication setup.setupMode - Configures how the notification is set up. For available modes see NotificationSetupMode.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<any> setupIndication(android.bluetooth.BluetoothGattCharacteristic characteristic,
NotificationSetupMode setupMode)
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()
characteristic - Characteristic for indication setup.setupMode - Configures how the notification is set up. For available modes see NotificationSetupMode.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@Deprecated <any> getCharacteristic(java.util.UUID characteristicUuid)
characteristicUuid - Requested characteristic UUID.BleCharacteristicNotFoundException - if characteristic with given UUID hasn't been found.<any> readCharacteristic(java.util.UUID characteristicUuid)
characteristicUuid - Requested characteristic UUID.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<any> readCharacteristic(android.bluetooth.BluetoothGattCharacteristic characteristic)
characteristic - Requested characteristic.BleGattCannotStartException - if read operation couldn't be started for internal reason.BleGattException - if read operation failedto obtain the characteristic.,
to obtain the characteristic.<any> writeCharacteristic(java.util.UUID characteristicUuid,
byte[] data)
characteristicUuid - Requested characteristic UUID.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<any> writeCharacteristic(android.bluetooth.BluetoothGattCharacteristic bluetoothGattCharacteristic,
byte[] data)
bluetoothGattCharacteristic - Characteristic to write.data - the byte array to writeBleGattCannotStartException - if write operation couldn't be started for internal reason.BleGattException - if write operation failedto obtain the characteristic.,
to obtain the characteristic.RxBleConnection.LongWriteOperationBuilder createNewLongWriteBuilder()
writeCharacteristic(UUID, byte[]) should be sufficient.<any> readDescriptor(java.util.UUID serviceUuid,
java.util.UUID characteristicUuid,
java.util.UUID descriptorUuid)
serviceUuid - Requested BluetoothGattService UUIDcharacteristicUuid - Requested BluetoothGattCharacteristic UUIDdescriptorUuid - Requested BluetoothGattDescriptor UUIDBleGattCannotStartException - if read operation couldn't be started for internal reason.BleGattException - if read operation failedto obtain the characteristic.,
to obtain the characteristic.<any> readDescriptor(android.bluetooth.BluetoothGattDescriptor descriptor)
descriptor - Requested BluetoothGattDescriptorBleGattCannotStartException - if read operation couldn't be started for internal reason.BleGattException - if read operation failedto obtain the characteristic from which you can get the {@link BluetoothGattDescriptor}.,
to obtain the {@link BluetoothGattDescriptor}.Completable writeDescriptor(java.util.UUID serviceUuid,
java.util.UUID characteristicUuid,
java.util.UUID descriptorUuid,
byte[] data)
serviceUuid - Requested BluetoothGattDescriptor UUIDcharacteristicUuid - Requested BluetoothGattCharacteristic UUIDdescriptorUuid - Requested BluetoothGattDescriptor UUIDBleGattCannotStartException - if write operation couldn't be started for internal reason.BleGattException - if write operation failedCompletable writeDescriptor(android.bluetooth.BluetoothGattDescriptor descriptor,
byte[] data)
descriptor - Requested BluetoothGattDescriptorBleGattCannotStartException - if write operation couldn't be started for internal reason.BleGattException - if write operation failedto obtain the characteristic.,
to obtain the characteristic.Completable requestConnectionPriority(int connectionPriority,
long delay,
java.util.concurrent.TimeUnit timeUnit)
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.
connectionPriority - requested connection prioritydelay - delay after which operation is assumed to be successful (must be shorter than 30 seconds)timeUnit - time unit of the delayBleGattCannotStartException - with BleGattOperationType.CONNECTION_PRIORITY_CHANGE type
if requested operation returned false or threw exceptionjava.lang.IllegalArgumentException - in case of invalid connection priority or delay<any> observeConnectionParametersUpdates()
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).<any> readRssi()
<any> requestMtu(int mtu)
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.int getMtu()
<T> <any> queue(RxBleCustomOperation<T> operation)
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.
T - The type returned by the RxBleCustomOperation instance.operation - The custom operation to queue.<T> <any> queue(RxBleCustomOperation<T> operation, Priority priority)
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.
T - The type returned by the RxBleCustomOperation instance.operation - The custom operation to queue.priority - Priority affected to this operation