com.idevicesinc.sweetblue

Class BleNodeConfig

java.lang.Object

com.idevicesinc.sweetblue.BleNodeConfig

Direct Known Subclasses:

BleDeviceConfig

public class BleNodeConfig
extends java.lang.Object

Provides a number of options to (optionally) pass to BleServer.setConfig(BleNodeConfig). This class is also a super class of BleManagerConfig, which you can pass to BleManager.get(Context, BleManagerConfig) or BleManager.setConfig(BleManagerConfig) to set default base options for all servers at once. For all options in this class, you may set the value to null when passed to BleServer.setConfig(BleNodeConfig) and the value will then be inherited from the BleManagerConfig passed to BleManager.get(Context, BleManagerConfig). Otherwise, if the value is not null it will override any option in the BleManagerConfig. If an option is ultimately null (null when passed to BleServer.setConfig(BleNodeConfig) *and* BleManager.get(Context, BleManagerConfig)) then it is interpreted as false or Interval.DISABLED.

TIP: You can use Interval.DISABLED instead of null to disable any time-based options, for code readability's sake.

TIP: You can use newNulled() (or nullOut()) then only set the few options you want for BleServer.setConfig(BleNodeConfig).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	BleNodeConfig.DefaultHistoricalDataLogFilter Default implementation of BleNodeConfig.HistoricalDataLogFilter set on historicalDataLogFilter that logs the most recent data reading to memory only, flushing the previous one.
static class	BleNodeConfig.DefaultTaskTimeoutRequestFilter Default implementation of TaskTimeoutRequestFilter that simply sets the timeout for all BleTask instances to BleNodeConfig.DefaultTaskTimeoutRequestFilter.DEFAULT_TASK_TIMEOUT seconds.
static interface	BleNodeConfig.HistoricalDataFactory Provide an instance to historicalDataFactory to return custom subclasses of HistoricalData if you would like.
static interface	BleNodeConfig.HistoricalDataLogFilter Provide an instance of this class to historicalDataLogFilter to control how/if historical data from BLE operations is logged.

Field Summary

Fields

Modifier and Type	Field and Description
java.lang.Boolean	alwaysUseAutoConnect Default is false - see the boolean autoConnect parameters of BluetoothDevice.connectGatt(Context, boolean, android.bluetooth.BluetoothGattCallback) and BluetoothGattServer.connect(BluetoothDevice, boolean).
boolean	autoStripeWrites Default is true - this will automatically stripe writes that are larger than the MTU size into multiple WRITE requests for you.
static int	DEFAULT_MAX_CONNECTION_FAIL_HISTORY_SIZE The default size of the list that keeps track of a BleNode's connection failure history.
static int	DEFAULT_MTU_SIZE The default MTU size in bytes for gatt reads/writes/notifies/etc.
java.lang.Boolean	disconnectIsCancellable Default is true - controls whether the library is allowed to optimize fast disconnect/reconnect cycles by actually not disconnecting in the native stack at all.
static int	GATT_READ_MTU_OVERHEAD The overhead in bytes that is subtracted from the total mtu size (e.g.
static int	GATT_WRITE_MTU_OVERHEAD The overhead in bytes that is subtracted from the total mtu size (e.g.
BleNodeConfig.HistoricalDataFactory	historicalDataFactory Implement this to override the default behavior, which is simply to return an instance created with the constructor HistoricalData.HistoricalData(byte[], com.idevicesinc.sweetblue.utils.EpochTime).
BleNodeConfig.HistoricalDataLogFilter	historicalDataLogFilter Default is an instance of BleNodeConfig.DefaultHistoricalDataLogFilter - set an implementation here to control how/if data is logged.
static int	INVALID_TX_POWER Constant for an invalid or unknown transmission power.
ReconnectFilter	reconnectFilter Default is an instance of DefaultReconnectFilter using the timings that are public static final members thereof - set your own implementation here to have fine-grain control over reconnect behavior while a device is BleDeviceState.RECONNECTING_LONG_TERM or BleDeviceState.RECONNECTING_SHORT_TERM.
TaskTimeoutRequestFilter	taskTimeoutRequestFilter Default is an instance of BleNodeConfig.DefaultTaskTimeoutRequestFilter - set an implementation here to have fine control over how long individual BleTask instances can take before they are considered "timed out" and failed.

Constructor Summary

Constructors

Constructor and Description
BleNodeConfig() Creates a BleNodeConfig with all default options set.
BleNodeConfig(org.json.JSONObject jo) Creates a BleNodeConfig with all default options set.

Method Summary

Modifier and Type	Method and Description
BleNodeConfig	clone()
static double	getTimeout(TaskTimeoutRequestFilter.TaskTimeoutRequestEvent event)
static BleNodeConfig	newNulled() Convenience method that returns a nulled out BleNodeConfig, which is useful when using BleServer.setConfig(BleNodeConfig) to only override a few options from BleManagerConfig passed to BleManager.get(Context, BleManagerConfig) or BleManager.setConfig(BleManagerConfig).
void	nullOut() Sets all Nullable options in BleNodeConfig, BleDeviceConfig, BleManagerConfig to null so for example it's easier to cherry-pick just a few options to override from BleManagerConfig when using BleDevice.setConfig(BleDeviceConfig).
void	readJSON(org.json.JSONObject jo) Accepts a JSON object that represents a set of configuration options.
org.json.JSONObject	writeJSON() Creates and returns a JSONObject that represents all of the mutable settings of this object.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MTU_SIZE

public static final int DEFAULT_MTU_SIZE

The default MTU size in bytes for gatt reads/writes/notifies/etc.

See Also:

Constant Field Values

GATT_WRITE_MTU_OVERHEAD

public static final int GATT_WRITE_MTU_OVERHEAD

The overhead in bytes that is subtracted from the total mtu size (e.g. DEFAULT_MTU_SIZE) to give you the effective payload size that your application can send. For Android this payload size is almost always 23-3=20 bytes.

See Also:

Constant Field Values

GATT_READ_MTU_OVERHEAD

public static final int GATT_READ_MTU_OVERHEAD

The overhead in bytes that is subtracted from the total mtu size (e.g. DEFAULT_MTU_SIZE) to give you the effective payload size that your application can receive. For Android this payload size is almost always 23-1=22 bytes.

See Also:

Constant Field Values

INVALID_TX_POWER

public static final int INVALID_TX_POWER

Constant for an invalid or unknown transmission power.

See Also:

BleDevice.getTxPower(), BleDeviceConfig.defaultTxPower, Constant Field Values

DEFAULT_MAX_CONNECTION_FAIL_HISTORY_SIZE

public static final int DEFAULT_MAX_CONNECTION_FAIL_HISTORY_SIZE

The default size of the list that keeps track of a BleNode's connection failure history. This is to prevent the list from growing too large, if the device is unable to connect, and you have a large long term reconnect time set with reconnectFilter.

See Also:

Constant Field Values

alwaysUseAutoConnect

public java.lang.Boolean alwaysUseAutoConnect

Default is false - see the boolean autoConnect parameters of BluetoothDevice.connectGatt(Context, boolean, android.bluetooth.BluetoothGattCallback) and BluetoothGattServer.connect(BluetoothDevice, boolean).

This parameter is one of Android's deepest mysteries. By default we keep it false, but it has been observed that a connection can fail or time out, but then if you try again with autoConnect set to true it works! One would think, why not always set it to true? Well, while true is anecdotally more stable, it also (anecdotally) makes for longer connection times, which becomes a UX problem. Would you rather have a 5-10 second connection process that is successful with 99% of devices, or a 1-2 second connection process that is successful with 95% of devices? By default we've chosen the latter.

HOWEVER, it's important to note that you can have fine-grained control over its usage through the ReconnectFilter.onConnectFailed(ReconnectFilter.ConnectFailEvent) returned from ReconnectFilter.onConnectFailed(ReconnectFilter.ConnectFailEvent) (or the equivalent structures that are inner structures of BleServer).

So really this option mainly exists for those situations where you KNOW that you have a device or server that only works with autoConnect==true and you want connection time to be faster (i.e. you don't want to wait for that first failed connection for the library to internally start using autoConnect==true).

disconnectIsCancellable

public java.lang.Boolean disconnectIsCancellable

Default is true - controls whether the library is allowed to optimize fast disconnect/reconnect cycles by actually not disconnecting in the native stack at all. For example, if this option is true and your BleDevice is BleDeviceState.BLE_CONNECTED, calling BleDevice.disconnect() then BleDevice.connect() again won't result in a native disconnect/reconnect - your actual physical ble device firmware won't know that a disconnect was requested.

autoStripeWrites

public boolean autoStripeWrites

Default is true - this will automatically stripe writes that are larger than the MTU size into multiple WRITE requests for you. If you are using BleDevice.negotiateMtu(int), this may make things unstable.

taskTimeoutRequestFilter

public TaskTimeoutRequestFilter taskTimeoutRequestFilter

Default is an instance of BleNodeConfig.DefaultTaskTimeoutRequestFilter - set an implementation here to have fine control over how long individual BleTask instances can take before they are considered "timed out" and failed.

NOTE: Setting this to null will disable timeouts for all BleTask instances, which would probably be very dangerous to do - a task could just sit there spinning forever.

historicalDataLogFilter

public BleNodeConfig.HistoricalDataLogFilter historicalDataLogFilter

Default is an instance of BleNodeConfig.DefaultHistoricalDataLogFilter - set an implementation here to control how/if data is logged.

historicalDataFactory

public BleNodeConfig.HistoricalDataFactory historicalDataFactory

Implement this to override the default behavior, which is simply to return an instance created with the constructor HistoricalData.HistoricalData(byte[], com.idevicesinc.sweetblue.utils.EpochTime).

reconnectFilter

public ReconnectFilter reconnectFilter

Default is an instance of DefaultReconnectFilter using the timings that are public static final members thereof - set your own implementation here to have fine-grain control over reconnect behavior while a device is BleDeviceState.RECONNECTING_LONG_TERM or BleDeviceState.RECONNECTING_SHORT_TERM. This is basically how often and how long the library attempts to reconnect to a device that for example may have gone out of range. Set this variable to null if reconnect behavior isn't desired. If not null, your app may find BleManagerConfig.manageCpuWakeLock useful in order to force the app/phone to stay awake while attempting a reconnect.

See Also:

BleManagerConfig.manageCpuWakeLock, ReconnectFilter, DefaultReconnectFilter

Constructor Detail

BleNodeConfig

public BleNodeConfig()

Creates a BleNodeConfig with all default options set. See each member of this class for what the default options are set to. Consider using newNulled() also.

BleNodeConfig

public BleNodeConfig(org.json.JSONObject jo)

Creates a BleNodeConfig with all default options set. Then, any configuration options specified in the given JSONObject will be applied over the defaults. See writeJSON() regarding the creation of the JSONObject

Method Detail

nullOut

public void nullOut()

Sets all Nullable options in BleNodeConfig, BleDeviceConfig, BleManagerConfig to null so for example it's easier to cherry-pick just a few options to override from BleManagerConfig when using BleDevice.setConfig(BleDeviceConfig).

NOTE: This doesn't affect any non-nullable subclass members of BleManagerConfig like BleManagerConfig.stopScanOnPause.

newNulled

public static BleNodeConfig newNulled()

Convenience method that returns a nulled out BleNodeConfig, which is useful when using BleServer.setConfig(BleNodeConfig) to only override a few options from BleManagerConfig passed to BleManager.get(Context, BleManagerConfig) or BleManager.setConfig(BleManagerConfig).

getTimeout

public static double getTimeout(TaskTimeoutRequestFilter.TaskTimeoutRequestEvent event)

clone

public BleNodeConfig clone()

Overrides:

clone in class java.lang.Object

writeJSON

public org.json.JSONObject writeJSON()

Creates and returns a JSONObject that represents all of the mutable settings of this object. Keys are variable names and objects are values represented in JSON form. Only types that we know how to convert to JSON will be included.

readJSON

public void readJSON(org.json.JSONObject jo)

Accepts a JSON object that represents a set of configuration options. These options will be applied to this object, overwriting any existing options. Options not defined in the JSON object will not be effected at all.