public class BleManagerConfig extends BleDeviceConfig
BleManager.get(Context, BleManagerConfig)
singleton getter or BleManager.setConfig(BleManagerConfig)
.
Use Interval.DISABLED
or null
to disable any time-based options.Modifier and Type | Class and Description |
---|---|
static class |
BleManagerConfig.DeviceNameComparator
Default sorter class for sorting the list of devices in
BleManager . |
BleDeviceConfig.AuthTransactionFactory<T extends BleTransaction.Auth>, BleDeviceConfig.DefaultBondFilter, BleDeviceConfig.InitTransactionFactory<T extends BleTransaction.Init>, BleDeviceConfig.RefreshOption
BleNodeConfig.DefaultHistoricalDataLogFilter, BleNodeConfig.DefaultTaskTimeoutRequestFilter, BleNodeConfig.HistoricalDataFactory, BleNodeConfig.HistoricalDataLogFilter
Modifier and Type | Field and Description |
---|---|
boolean |
autoPauseResumeDetection
Default is
true - Controls whether BleManager.onResume() and BleManager.onPause() will get called
automatically by using Application.ActivityLifecycleCallbacks . |
Interval |
autoScanDelayAfterBleTurnsOn
Default is
Interval.DISABLED . |
Interval |
autoScanDelayAfterResume
Default is 0.5 seconds - Unless
Interval.DISABLED ,
this option will kick off a scan autoScanDelayAfterResume seconds after BleManager.onResume() is called, if
and only if a scan had been started by calling BleManager.startScan(ScanOptions) (or any of it's overloads). |
boolean |
autoScanDuringOta
Default is
false - set this to allow or disallow autoscanning while any
BleDevice is BleDeviceState.PERFORMING_OTA . |
Interval |
autoScanPauseTimeWhileAppIsBackgrounded
Default is
Interval.DISABLED - If you want a different scan time while the app is backgrounded, versus foregrounded, set this
option. |
Interval |
autoUpdateRate
Default is 0.0202 seconds - The rate at which the library's internal update loop ticks.
|
boolean |
blockingShutdown
Default is
false - This makes it so that BleManager.shutdown() is a blocking call. |
IBluetoothManager |
bluetoothManagerImplementation
This option is exposed for unit testing.
|
static double |
DEFAULT_AUTO_SCAN_DELAY_AFTER_RESUME
Default value for
autoScanDelayAfterResume . |
static double |
DEFAULT_AUTO_UPDATE_RATE
Default value for
autoUpdateRate . |
static double |
DEFAULT_CLASSIC_SCAN_BOOST_TIME
Default value for
scanClassicBoostLength . |
static double |
DEFAULT_DELAY_BEFORE_IDLE
Default value for
minTimeToIdle . |
static double |
DEFAULT_IDLE_UPDATE_RATE
Default value for
idleUpdateRate . |
static double |
DEFAULT_MANAGER_STATE_POLL_RATE
Default value for
defaultStatePollRate |
static double |
DEFAULT_SCAN_INFINITE_INTERVAL_TIME
Default value for
infiniteScanInterval |
static double |
DEFAULT_SCAN_INFINITE_PAUSE_TIME
Default value for
infinitePauseInterval |
static double |
DEFAULT_UH_OH_CALLBACK_THROTTLE
Default value for
uhOhCallbackThrottle . |
DiscoveryListener |
defaultDiscoveryListener
Default is
null - can also be set post-construction with BleManager.setListener_Discovery(DiscoveryListener) ,
which will override the implementation provided here. |
java.util.Comparator<BleDevice> |
defaultListComparator
Default is
BleManagerConfig.DeviceNameComparator . |
BleManagerState[] |
defaultManagerStates |
java.util.List<NativeScanFilter> |
defaultNativeScanFilterList
Default is
EMPTY_NATIVE_FILTER , which is an empty filter (nothing gets filtered out). |
ScanFilter |
defaultScanFilter
Default is
null , meaning no filtering - all discovered devices will
be piped through your DiscoveryListener instance
and added to the internal list of BleManager . |
Interval |
defaultStatePollRate
Default is
DEFAULT_MANAGER_STATE_POLL_RATE seconds - The rate at which the library will poll the native manager's
state. |
Interval |
delayBetweenTasks
Default is
Interval.DISABLED - This sets an amount of time to delay between executing each task in the queue. |
static java.util.List<NativeScanFilter> |
EMPTY_NATIVE_FILTER
Default native scan filter used by the library if
defaultNativeScanFilterList is not set. |
boolean |
enableCrashResolver
Default is
false - this option may help mitigate crashes with "Unfortunately,
Bluetooth Share has stopped" error messages. |
boolean |
enableCrashResolverForReset
Default is
true - this option gates whether the "crash resolver" described in enableCrashResolver
is invoked during a BleManager.reset() operation to forcefully clear the memory that causes the crash. |
Interval |
idealMinScanTime
Default is
BleDeviceConfig.DEFAULT_MINIMUM_SCAN_TIME seconds - Minimum amount of time in seconds that the library strives to give to a scanning operation. |
Interval |
idleUpdateRate
Default is 0.5 seconds - The rate at which the library's internal update loop ticks, after
minTimeToIdle has elapsed. |
Interval |
infinitePauseInterval
Default is
DEFAULT_SCAN_INFINITE_PAUSE_TIME - This is the amount of time SweetBlue will wait before resuming a scan. |
Interval |
infiniteScanInterval
Default is
DEFAULT_SCAN_INFINITE_INTERVAL_TIME - When running an infinite scan, SweetBlue will pause the scan, and restart it again a short
time later, defined by infinitePauseInterval . |
SweetLogger |
logger
Default is
DefaultLogger - which prints the log statements to Android's logcat. |
LogOptions |
loggingOptions
Default is
LogOptions.OFF - There are 3 static instances you can use for convenience - LogOptions.OFF ,
LogOptions.ON , and LogOptions.ALL_ON . |
boolean |
manageCpuWakeLock
Default is
true - requires the Manifest.permission.WAKE_LOCK permission in your app's manifest file. |
boolean |
manageLastUhOhOnDisk
Default is
true - This allows SweetBlue to store the last Uh Oh time to disk. |
static double |
MAX_CLASSIC_SCAN_TIME
Maximum amount of time for a classic scan to run.
|
Interval |
minTimeToIdle
Default is 20.0 seconds - This is the amount of time the library will wait with no tasks before
lowering the update loop tick to
idleUpdateRate . |
boolean |
postCallbacksToMainThread
Default is
true - whether all callbacks are posted to the main thread or from SweetBlue's internal
thread. |
boolean |
requestBackgroundOperation
Default is
false . |
boolean |
revertToClassicDiscoveryIfNeeded
Default is
true - SweetBlue uses BluetoothAdapter.startLeScan(BluetoothAdapter.LeScanCallback) by default but for unknown
reasons this can fail sometimes. |
BleScanApi |
scanApi
Default is
BleScanApi.AUTO - see BleScanApi for more details. |
Interval |
scanClassicBoostLength
Default is
Interval.DISABLED - This will run a short classic scan before a regular BLE scan. |
BleScanPower |
scanPower
NOTE: This is ONLY applicable on devices running Lollipop or above.
|
Interval |
scanReportDelay
Default is
Interval.ZERO seconds - Only applicable for Lollipop and up (i.e. |
IBluetoothServer.Factory |
serverFactory
This option is exposed for unit testing.
|
boolean |
stopScanOnPause
Default is
true - makes it so BleManager.stopScan() is called automatically after BleManager.onPause() . |
TimeTrackerSetting |
timeTrackerSetting
Controls if we should record/print information about the time taken by the update loop in
BleManager and BleDevice
|
Interval |
uhOhCallbackThrottle
Default is 30.0 seconds -
UhOhListener.UhOh callbacks from UhOhListener
can be a little spammy at times so this is an option to throttle them back on a per-UhOhListener.UhOh basis. |
ThreadHandler |
updateHandler
Default is
null . |
UpdateCallback |
updateLoopCallback
Default is
null - provide an instance here that will be called at the end of BleManager 's update loop. |
UpdateThreadType |
updateThreadType
Default is
UpdateThreadType.THREAD , which uses a background thread. |
java.util.List<UuidNameMap> |
uuidNameMaps
|
allowDuplicatePollEntries, alwaysBondOnConnect, autoBondFixes, autoEnableNotifiesOnReconnect, autoGetServices, autoNegotiateMtuOnReconnect, autoReconnectDeviceWhenBleTurnsBackOn, bluetoothDeviceFactory, bondFilter, bondingFailFailsConnection, bondRetryFilter, cacheDeviceOnUndiscovery, clearGattOnOtaSuccess, connectFailRetryConnectingOverall, connectionBugFixTimeout, DEFAULT_CONNECTION_BUG_FIX_TIMEOUT, DEFAULT_GATT_REFRESH_DELAY, DEFAULT_MAX_BOND_RETRIES, DEFAULT_MAX_CONNECTION_FAIL_HISTORY_SIZE, DEFAULT_MINIMUM_SCAN_TIME, DEFAULT_RSSI_AUTO_POLL_RATE, DEFAULT_RSSI_MAX, DEFAULT_RSSI_MIN, DEFAULT_RUNNING_AVERAGE_N, DEFAULT_SCAN_KEEP_ALIVE, DEFAULT_TX_POWER, defaultAuthFactory, defaultDeviceStates, defaultInitFactory, defaultTransactionAtomicity, defaultTxPower, equalOpportunityReadsWrites, forceBondDialog, forceBondHackInterval, gattFactory, gattRefreshDelay, gattRefreshOption, includeOtaReadWriteTimesInAverage, manageLastDisconnectOnDisk, maxConnectionFailHistorySize, minScanTimeNeededForUndiscovery, mtuTestCallback, nForAverageRunningReadTime, nForAverageRunningWriteTime, phyOptions, reconnectFilter, retainDeviceWhenBleTurnsOff, rssi_max, rssi_min, rssiAutoPollRate, saveNameChangesToDisk, serviceDiscoveryDelay, tryBondingWhileDisconnected, tryBondingWhileDisconnected_manageOnDisk, undiscoverDeviceWhenBleTurnsOff, undiscoveryKeepAlive, useGattRefresh, useLeTransportForBonding
alwaysUseAutoConnect, autoStripeWrites, DEFAULT_MTU_SIZE, disconnectIsCancellable, GATT_READ_MTU_OVERHEAD, GATT_WRITE_MTU_OVERHEAD, historicalDataFactory, historicalDataLogFilter, INVALID_TX_POWER, taskTimeoutRequestFilter
Modifier | Constructor and Description |
---|---|
|
BleManagerConfig()
Creates a
BleManagerConfig with all default options set. |
|
BleManagerConfig(org.json.JSONObject jo)
Creates a
BleManagerConfig with all default options set. |
protected |
BleManagerConfig(LogOptions logOptions)
Convenience constructor that populates
uuidNameMaps with Uuids
using ReflectionUuidNameMap if logging is enabled. |
Modifier and Type | Method and Description |
---|---|
BleManagerConfig |
clone() |
static BleManagerConfig |
newWithLogging()
Returns a new constructor that populates
uuidNameMaps with Uuids
using ReflectionUuidNameMap to help with readable logging. |
newNulled
getTimeout, nullOut, readJSON, writeJSON
public static final double DEFAULT_AUTO_SCAN_DELAY_AFTER_RESUME
autoScanDelayAfterResume
.public static final double DEFAULT_AUTO_UPDATE_RATE
autoUpdateRate
.public static final double DEFAULT_IDLE_UPDATE_RATE
idleUpdateRate
.public static final double DEFAULT_DELAY_BEFORE_IDLE
minTimeToIdle
.public static final double DEFAULT_UH_OH_CALLBACK_THROTTLE
uhOhCallbackThrottle
.public static final double DEFAULT_CLASSIC_SCAN_BOOST_TIME
scanClassicBoostLength
.public static final double DEFAULT_SCAN_INFINITE_INTERVAL_TIME
infiniteScanInterval
public static final double DEFAULT_SCAN_INFINITE_PAUSE_TIME
infinitePauseInterval
public static final double DEFAULT_MANAGER_STATE_POLL_RATE
defaultStatePollRate
public static final java.util.List<NativeScanFilter> EMPTY_NATIVE_FILTER
defaultNativeScanFilterList
is not set.public static final double MAX_CLASSIC_SCAN_TIME
public LogOptions loggingOptions
LogOptions.OFF
- There are 3 static instances you can use for convenience - LogOptions.OFF
,
LogOptions.ON
, and LogOptions.ALL_ON
. If you want more fine-grained logs, then instantiate LogOptions
with the levels of logging
you would like for SweetBlue logs, and native logs (logs printed when receiving any native callbacks).public TimeTrackerSetting timeTrackerSetting
public SweetLogger logger
DefaultLogger
- which prints the log statements to Android's logcat. If you want to
pipe the log statements elsewhere, create a class which implements SweetLogger
, and set this field
with an instance of it. If loggingOptions
is not set -- or it's set to LogOptions.OFF
--, then this option will not affect anything.public BleManagerState[] defaultManagerStates
public boolean enableCrashResolver
false
- this option may help mitigate crashes with "Unfortunately,
Bluetooth Share has stopped" error messages. See https://github.com/RadiusNetworks/bluetooth-crash-resolver or
http://developer.radiusnetworks.com/2014/04/02/a-solution-for-android-bluetooth-crashes.html or
Google "Bluetooth Crash Resolver" for more information.
BleManager.shutdown()
, first, then any of the get calls to re-instantiate the
BleManager
instance.enableCrashResolverForReset
public boolean enableCrashResolverForReset
true
- this option gates whether the "crash resolver" described in enableCrashResolver
is invoked during a BleManager.reset()
operation to forcefully clear the memory that causes the crash.enableCrashResolver
public boolean stopScanOnPause
true
- makes it so BleManager.stopScan()
is called automatically after BleManager.onPause()
.
If you're doing an infinite scan (e.g. by calling BleManager.startScan()
, i.e. no timeout), then the scan
will automatically continue after BleManager.onResume()
is called.BleManager.onPause()
public Interval scanClassicBoostLength
Interval.DISABLED
- This will run a short classic scan before a regular BLE scan. Sometimes, for whatever reason, the native
BLE stack will refuse to see a particular device. However, if you go into Bluetooth settings on the phone, it sees it (they do a classic scan
here), and suddenly it shows up in a BLE scan after that. So the idea with this feature is to do the same thing without having to go into
Bluetooth settings.
This seems to affect the number of devices that are returned in total, and how quickly they are discovered, so this is disabled by default now.
If you decide that you need to use it, we recommend going with a time length of DEFAULT_CLASSIC_SCAN_BOOST_TIME
.
public Interval infiniteScanInterval
DEFAULT_SCAN_INFINITE_INTERVAL_TIME
- When running an infinite scan, SweetBlue will pause the scan, and restart it again a short
time later, defined by infinitePauseInterval
. The android stack tends to find less and less devices the longer a scan runs. This helps to keep
scan results coming in when performing an infinite scan, leading to better results.public Interval infinitePauseInterval
DEFAULT_SCAN_INFINITE_PAUSE_TIME
- This is the amount of time SweetBlue will wait before resuming a scan.
public boolean autoScanDuringOta
false
- set this to allow or disallow autoscanning while any
BleDevice
is BleDeviceState.PERFORMING_OTA
. If false,
then OTAs may complete faster if you're not periodically scanning
through BleManager.startPeriodicScan(Interval, Interval)
.
BleManager.startScan()
will still start a scan regardless.public boolean revertToClassicDiscoveryIfNeeded
true
- SweetBlue uses BluetoothAdapter.startLeScan(BluetoothAdapter.LeScanCallback)
by default but for unknown
reasons this can fail sometimes. In this case SweetBlue can revert to using classic bluetooth
discovery through BluetoothAdapter.startDiscovery()
. Be aware that classic
discovery may not discover some or any advertising BLE devices, nor will it provide
a ScanFilter.ScanEvent.scanRecord()
or ScanFilter.ScanEvent.advertisedServices()
to ScanFilter.onEvent(ScanFilter.ScanEvent)
.
Most likely you will be forced to filter on name only for your implementation of
ScanFilter.onEvent(ScanFilter.ScanEvent)
.
As such this is meant as a better-than-nothing back-up solution for BLE scanning.public UpdateThreadType updateThreadType
UpdateThreadType.THREAD
, which uses a background thread. This option specifies what thread SweetBlue will run all it's logic in.
If you want to run SweetBlue's logic in a thread you've already created, then set this option to UpdateThreadType.USER_CUSTOM
. You also need
to set updateHandler
with an instance of ThreadHandler
.ThreadHandler
public ThreadHandler updateHandler
null
. This option is ignored, unless updateThreadType
is set to UpdateThreadType.USER_CUSTOM
. If this option is
null
, and updateThreadType
is UpdateThreadType.USER_CUSTOM
, then the default will be used instead.ThreadHandler
public boolean postCallbacksToMainThread
true
- whether all callbacks are posted to the main thread or from SweetBlue's internal
thread. If updateThreadType
==UpdateThreadType.MAIN
then this setting is meaningless because SweetBlue's
internal thread is already the main thread to begin with.public boolean manageCpuWakeLock
true
- requires the Manifest.permission.WAKE_LOCK
permission in your app's manifest file.
It should look like this: <uses-permission android:name="android.permission.WAKE_LOCK" />
Sets whether the library will attempt to obtain a wake lock in certain situations.
For now the only situation is when there are no remote bluetooth devices
BleDeviceState.BLE_CONNECTED
but one or more devices are BleDeviceState.RECONNECTING_LONG_TERM
.
The wake lock will be released when devices are reconnected (e.g. from coming back
into range) or when reconnection is stopped either through BleDevice.disconnect()
or returning
ReconnectFilter.ConnectionLostPlease.stopRetrying()
from
ReconnectFilter.onConnectionLost(ReconnectFilter.ConnectionLostEvent)
.
Wake locks will also be released if Bluetooth is turned off either from the App or OS settings.
Note that Android itself uses some kind of implicit wake lock when you are connected to
one or more devices and requires no explicit wake lock nor any extra permissions to do so.public boolean requestBackgroundOperation
false
. This setting affects BleSetupHelper
when requesting location
services permissions on devices running android 10 or higher. If you need to have scan results work when your app is in
the background you must set this option to true
, and add the manifest permission
Manifest.permission.ACCESS_BACKGROUND_LOCATION
to your app's AndroidManifest.xml file.public boolean autoPauseResumeDetection
true
- Controls whether BleManager.onResume()
and BleManager.onPause()
will get called
automatically by using Application.ActivityLifecycleCallbacks
.public Interval uhOhCallbackThrottle
UhOhListener.UhOh
callbacks from UhOhListener
can be a little spammy at times so this is an option to throttle them back on a per-UhOhListener.UhOh
basis.
Set this to Interval.DISABLED
to receive all every UhOhListener.UhOh
and manage them yourself.UhOhListener
public boolean manageLastUhOhOnDisk
true
- This allows SweetBlue to store the last Uh Oh time to disk. This makes it so that even if you shutdown, and restart
BleManager
, SweetBlue will still respect the uhOhCallbackThrottle
. Otherwise, if you restart the manager, and get an UhOhListener.UhOh
it will be dispatched immediately.public boolean blockingShutdown
false
- This makes it so that BleManager.shutdown()
is a blocking call. The method will wait until all devices have been
disconnected.public Interval autoScanDelayAfterResume
Interval.DISABLED
,
this option will kick off a scan autoScanDelayAfterResume
seconds after BleManager.onResume()
is called, if
and only if a scan had been started by calling BleManager.startScan(ScanOptions)
(or any of it's overloads).public Interval autoScanDelayAfterBleTurnsOn
Interval.DISABLED
. If set, this will automatically start scanning after the specified Interval
. This also
depends on if a scan had been running before BLE turned off. If not, then this is ignored.public Interval autoScanPauseTimeWhileAppIsBackgrounded
Interval.DISABLED
- If you want a different scan time while the app is backgrounded, versus foregrounded, set this
option.BleManager.onPause()
public Interval idealMinScanTime
BleDeviceConfig.DEFAULT_MINIMUM_SCAN_TIME
seconds - Minimum amount of time in seconds that the library strives to give to a scanning operation.public Interval autoUpdateRate
public Interval defaultStatePollRate
DEFAULT_MANAGER_STATE_POLL_RATE
seconds - The rate at which the library will poll the native manager's
state. This only applies to devices running Marshmallow or higher. This call can drain the battery if it's left at the same
rate as autoUpdateRate
, as it uses reflection to poll the native state. This is needed on some phones where SweetBlue
doesn't receive a state change when it should.
If this is null
, then state polling will be disabled.public Interval idleUpdateRate
minTimeToIdle
has elapsed.public Interval minTimeToIdle
idleUpdateRate
.public Interval delayBetweenTasks
Interval.DISABLED
- This sets an amount of time to delay between executing each task in the queue. The delay simply makes sure
that the amount of time requested here has passed since the last task ended.public Interval scanReportDelay
Interval.ZERO
seconds - Only applicable for Lollipop and up (i.e. > 5.0), this is the value given to
ScanSettings.Builder.setReportDelay(long)
so that scan results are "batched" ¯\_(ツ)_/¯. It's not clear from source
code, API documentation, or internet search what effects this has, when you would want to use it, etc. The reason we use the default
value provided is largely subjective. It seemed to help discover a peripheral faster on the Nexus 7 that was only advertising on channels
37 and 38 - i.e. not on channel 39 too.
Interval.ZERO
for the delay.
BluetoothAdapter.isOffloadedScanBatchingSupported()
returns true
- otherwise
it has no effect because the hardware does not support it.public ScanFilter defaultScanFilter
null
, meaning no filtering - all discovered devices will
be piped through your DiscoveryListener
instance
and added to the internal list of BleManager
.ScanFilter
public java.util.List<NativeScanFilter> defaultNativeScanFilterList
EMPTY_NATIVE_FILTER
, which is an empty filter (nothing gets filtered out). In Android 8.1, a change was made to stop
scan results being returned when the screen is turned off. This simple hack fixes a good amount of phones, however, it seems some phones
are more aggressive with their filter checks. So, this option is here to allow you to set Android's native ScanFilter directly. Note that
if you are expecting results on a phone running 8.1+ when the screen is off, you will need to run the scan in a foreground service.
NOTE: If you set this filter, it will force scanApi
to BleScanApi.POST_LOLLIPOP
, except when running on a device which
is on 4.3, or 4.4. The native scan filter here is ONLY applicable to lollipop and above.public DiscoveryListener defaultDiscoveryListener
null
- can also be set post-construction with BleManager.setListener_Discovery(DiscoveryListener)
,
which will override the implementation provided here.DiscoveryListener
public BleScanApi scanApi
BleScanApi.AUTO
- see BleScanApi
for more details.
NOTE: If defaultNativeScanFilterList
is set to anything but the default, then this option will be forced to use
BleScanApi.POST_LOLLIPOP
, as the ScanFilters only work on lollipop and above.public BleScanPower scanPower
BleScanPower.AUTO
- see BleScanPower
for more details.public UpdateCallback updateLoopCallback
null
- provide an instance here that will be called at the end of BleManager
's update loop.
This might be useful for extension/wrapper libraries or apps that want to tie into the BleManager
instance's existing update loop.public IBluetoothServer.Factory serverFactory
public IBluetoothManager bluetoothManagerImplementation
public java.util.List<UuidNameMap> uuidNameMaps
null
- optional, only used if loggingOptions
is not LogOptions.OFF
. Provides a look-up table
so logs can show the name associated with a UUID
along with its numeric string.public java.util.Comparator<BleDevice> defaultListComparator
BleManagerConfig.DeviceNameComparator
. This specifies how to
sort the list of devices in BleManager
.public BleManagerConfig()
BleManagerConfig
with all default options set. See each member of this class
for what the default options are set to.public BleManagerConfig(org.json.JSONObject jo)
BleManagerConfig
with all default options set. Then, any configuration options
specified in the given JSONObject will be applied over the defaults. See BleNodeConfig.writeJSON()
regarding the creation of the JSONObjectprotected BleManagerConfig(LogOptions logOptions)
uuidNameMaps
with Uuids
using ReflectionUuidNameMap
if logging is enabled.logOptions
- Sets loggingOptions
.public static BleManagerConfig newWithLogging()
uuidNameMaps
with Uuids
using ReflectionUuidNameMap
to help with readable logging. This sets loggingOptions
to
LogOptions.ON
.public BleManagerConfig clone()
clone
in class BleDeviceConfig