com.polidea.rxandroidble2

Class RxBleClient

java.lang.Object

com.polidea.rxandroidble2.RxBleClient

public abstract class RxBleClient
extends java.lang.Object

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RxBleClient.State

Constructor Summary

Constructors

Constructor and Description
RxBleClient()

Method Summary

Modifier and Type	Method and Description
static RxBleClient	create(android.content.Context context) Returns instance of RxBleClient using application context.
abstract BackgroundScanner	getBackgroundScanner() Returns a background scanner instance that can be used to handle background scans, even if your process is stopped.
abstract RxBleDevice	getBleDevice(java.lang.String macAddress) Obtain instance of RxBleDevice for provided MAC address.
abstract java.util.Set<RxBleDevice>	getBondedDevices() A function returning a set of currently bonded devices If Bluetooth state is not STATE_ON, this API will return an empty set.
abstract RxBleClient.State	getState() Returns the current state of the RxBleClient environment, which may be helpful in deciding if particular functionality should be used at a given moment.
abstract <any>	observeStateChanges() Returns an observable emitting state _changes_ of the RxBleClient environment which may be helpful in deciding if particular functionality should be used at a given moment.
abstract <any>	scanBleDevices(ScanSettings scanSettings, ScanFilter... scanFilters) Returns an infinite observable emitting BLE scan results.
abstract <any>	scanBleDevices(java.util.UUID... filterServiceUUIDs) Deprecated. use scanBleDevices(ScanSettings, ScanFilter...) instead
static void	setLogLevel(int logLevel) Deprecated. use updateLogOptions(LogOptions)
static void	updateLogOptions(LogOptions logOptions) Method for updating logging options.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RxBleClient

public RxBleClient()

Method Detail

create

public static RxBleClient create(android.content.Context context)

Returns instance of RxBleClient using application context. It is required by the client to maintain single instance of RxBleClient.

Parameters:

context - Any Android context

Returns:

BLE client instance.

setLogLevel

@Deprecated
public static void setLogLevel(int logLevel)

Deprecated. use updateLogOptions(LogOptions)

A convenience method. Sets the log level that will be printed out in the console. Default is LogLevel.NONE which logs nothing.

Parameters:

logLevel - the minimum log level to log

updateLogOptions

public static void updateLogOptions(LogOptions logOptions)

Method for updating logging options. Properties not set in LogOptions will not get updated.

Default behaviour: MAC addresses are not logged (MAC='XX:XX:XX:XX:XX:XX'), uuids are not logged (uuid='...'), byte array values are not logged (value=[...]), logger is logging to the logcat (Log), all scanned peripherals are logged if log level allows it, log level is set not to log anything (LogConstants.NONE)

Parameters:

logOptions - the logging options

getBleDevice

public abstract RxBleDevice getBleDevice(java.lang.String macAddress)

Obtain instance of RxBleDevice for provided MAC address. This may be the same instance that was provided during scan operation but this in not guaranteed.

Parameters:

macAddress - Bluetooth LE device MAC address.

Returns:

Handle for Bluetooth LE operations.

Throws:

java.lang.UnsupportedOperationException - if called on system without Bluetooth capabilities

getBondedDevices

public abstract java.util.Set<RxBleDevice> getBondedDevices()

A function returning a set of currently bonded devices If Bluetooth state is not STATE_ON, this API will return an empty set. After turning on Bluetooth, wait for ACTION_STATE_CHANGED with STATE_ON to get the updated value.

Returns:

set of currently bonded devices

Throws:

java.lang.UnsupportedOperationException - if called on system without Bluetooth capabilities

scanBleDevices

@Deprecated
public abstract <any> scanBleDevices(java.util.UUID... filterServiceUUIDs)

Deprecated. use scanBleDevices(ScanSettings, ScanFilter...) instead

Returns an infinite observable emitting BLE scan results. Scan is automatically started and stopped based on the Observable lifecycle. Scan is started when the Observable is subscribed and stopped when unsubscribed. You can safely subscribe multiple observers to this observable. When defining filterServiceUUIDs have in mind that the RxBleScanResult will be emitted only if _all_ UUIDs are present in the advertisement.

The library automatically handles Bluetooth adapter's state changes but you are supposed to prompt the user to enable it if it's disabled.

Parameters:

filterServiceUUIDs - Filtering settings. Scan results are only filtered by exported services. All specified UUIDs must be present in the advertisement data to match the filter.

Throws:

BleScanException - emits in case of error starting the scan

scanBleDevices

public abstract <any> scanBleDevices(ScanSettings scanSettings,
                                     ScanFilter... scanFilters)

Returns an infinite observable emitting BLE scan results. Scan is automatically started and stopped based on the Observable lifecycle. Scan is started on subscribe and stopped on unsubscribe. You can safely subscribe multiple observers to this observable.

The library automatically handles Bluetooth adapter state changes but you are supposed to prompt the user to enable it if it is disabled This function works on Android 4.3 in compatibility (emulated) mode.

Parameters:

scanSettings - Scan settings

scanFilters - Filtering settings. ScanResult will be emitted if any of the passed scan filters will match.

getBackgroundScanner

public abstract BackgroundScanner getBackgroundScanner()

Returns a background scanner instance that can be used to handle background scans, even if your process is stopped.

observeStateChanges

public abstract <any> observeStateChanges()

Returns an observable emitting state _changes_ of the RxBleClient environment which may be helpful in deciding if particular functionality should be used at a given moment.

Returns:

the observable

See Also:

for {@link State} precedence order Examples: - If the device is in {@link State#READY} and the user will turn off the bluetooth adapter then {@link State#BLUETOOTH_NOT_ENABLED} will be emitted. - If the device is in {@link State#BLUETOOTH_NOT_ENABLED} then changing state of Location Services will not cause emissions because of the checks order - If the device is in {@link State#BLUETOOTH_NOT_AVAILABLE} then this {@link Observable} will complete because any other checks will not be performed as devices are not expected to obtain bluetooth capabilities during runtime To get the initial {@link State} and then observe changes you can use: `observeStateChanges().startWith(getState())`.

getState

public abstract RxBleClient.State getState()

Returns the current state of the RxBleClient environment, which may be helpful in deciding if particular functionality should be used at a given moment. The function concentrates on states that are blocking the full functionality of the library. Checking order: 1. Is Bluetooth available? 2. Is Location Permission granted? (if needed = API>=23) 3. Is Bluetooth Adapter on? 4. Are Location Services enabled? (if needed = API>=23) If any of the checks fails an appropriate State is returned and next checks are not performed. State precedence order is as follows: RxBleClient.State.BLUETOOTH_NOT_AVAILABLE if check #1 fails, RxBleClient.State.LOCATION_PERMISSION_NOT_GRANTED if check #2 fails, RxBleClient.State.BLUETOOTH_NOT_ENABLED if check #3 fails, RxBleClient.State.LOCATION_SERVICES_NOT_ENABLED if check #4 fails, RxBleClient.State.READY

Returns:

the current state