public enum BleDeviceState extends java.lang.Enum<BleDeviceState> implements State
BleDevice
can be in.
Note that a device can and usually will be in multiple states simultaneously.
Use BleDevice.setListener_State(DeviceStateListener)
to be notified of state changes.DeviceStateListener
State.ChangeEvent<T_State extends State>, State.ChangeIntent
Enum Constant and Description |
---|
ADVERTISING
When
BleDevice.getOrigin() is BleDeviceOrigin.FROM_DISCOVERY , a device will always be in this state while BLE_CONNECTED
is not active. |
ATTEMPTING_CONNECTION_FIX
A
BleDevice will be in this state if it is attempting to fix a connection bug where the first time a device is bonded, the connection
will be left open by the underlying bluetooth stack, even though it will report it's state as being disconnected. |
AUTHENTICATED
This state becomes active either if the
BleTransaction provided to BleDevice.connect(BleTransaction.Auth) or
BleDevice.connect(BleTransaction.Auth, BleTransaction.Init) succeeds with BleTransaction.succeed() , OR if you use
BleDevice.connect() or BleDevice.connect(BleTransaction.Init) - i.e. |
AUTHENTICATING
This state can only become active if you use
BleDevice.connect(BleTransaction.Auth) or BleDevice.connect(BleTransaction.Auth, BleTransaction.Init)
to start a connection with an authentication transaction. |
BLE_CONNECTED
Analogous to
BluetoothProfile.STATE_CONNECTED . |
BLE_CONNECTING
Analogous to
BluetoothProfile.STATE_CONNECTING . |
BLE_DISCONNECTED
The device will always be in this state while
BLE_CONNECTED is not active. |
BONDED
Analogous to
BluetoothDevice.BOND_BONDED . |
BONDING
Analogous to
BluetoothDevice.BOND_BONDING . |
CONNECTED
"Simple" state to check if a device is connected.
|
CONNECTING
"Simple" state to check if a device is connecting.
|
CONNECTING_OVERALL
A convenience flag for checking if the device is connecting in an overall sense.
|
DISCONNECTED
"Simple" state to check if a device is disconnected or not.
|
DISCOVERED
The device will always be in this state unless it becomes
UNDISCOVERED . |
DISCOVERING_SERVICES
This state is active while we request a list of services from the native stack after becoming
BLE_CONNECTED . |
HIGH_SPEED
Only applicable to android devices running Oreo, and with compatible Bluetooth 5 hardware.
|
INITIALIZED
This is generally the state you want to listen for to consider your
BleDevice "fully" connected and ready to go, instead of
basing it off of just BLE_CONNECTED . |
INITIALIZING
This state can only become active if you use
BleDevice.connect(BleTransaction.Init) or BleDevice.connect(BleTransaction.Auth, BleTransaction.Init)
to start a connection with an initialization transaction. |
LONG_RANGE_2X
Only applicable to android devices running Oreo, and with compatible Bluetooth 5 hardware.
|
LONG_RANGE_4x
Only applicable to android devices running Oreo, and with compatible Bluetooth 5 hardware.
|
NULL
Dummy value returned from any method that would otherwise return Java's built-in
null . |
PERFORMING_OTA
This state for "over-the-air" updates becomes active when you call
BleDevice.performOta(BleTransaction.Ota) and remains active until the provided
BleTransaction calls BleTransaction.succeed() or BleTransaction.fail() (or of course if your BleDevice
becomes BLE_DISCONNECTED ). |
RECONNECTING_LONG_TERM
If
BleNodeConfig.reconnectFilter is set appropriately and the device implicitly disconnects, either through going out of range,
signal disruption, or whatever, then the device will enter this state. |
RECONNECTING_SHORT_TERM
If
BleNodeConfig.reconnectFilter is set appropriately and the device implicitly disconnects this state will be entered. |
REQUESTING_PHY
This state only applies for android devices running Oreo (8.0), and have Bluetooth 5 support.
|
RETRYING_BLE_CONNECTION
This state indicates that a connect has failed, but SweetBlue will be retrying the connection again.
|
SERVICES_DISCOVERED
This state is active after
DISCOVERING_SERVICES completes successfully. |
UNBONDED
Analogous to
BluetoothDevice.BOND_NONE . |
UNDISCOVERED
The device has been undiscovered and you should have been notified through
DiscoveryListener.onEvent(DiscoveryListener.DiscoveryEvent) . |
Modifier and Type | Field and Description |
---|---|
static BleDeviceState[] |
DEFAULT_STATES |
static int |
FULL_MASK
Full bitwise mask made by ORing all
BleDeviceState instances together. |
Modifier and Type | Method and Description |
---|---|
int |
bit() |
boolean |
didEnter(int oldStateBits,
int newStateBits)
Given an old and new state mask, for example from
DeviceStateListener.onEvent(com.idevicesinc.sweetblue.DeviceStateListener.StateEvent)
or ManagerStateListener.onEvent(com.idevicesinc.sweetblue.ManagerStateListener.StateEvent) , this method tells you whether the
the 'this' state was appended. |
boolean |
didExit(int oldStateBits,
int newStateBits)
Reverse of
State.didEnter(int, int) . |
static BleDeviceState |
getTransitoryConnectionState(int stateMask)
A convenience for UI purposes, this returns the "highest" connection state representing
a transition from one state to another, so something with "ING" in the name (except
PERFORMING_OTA ). |
boolean |
isInternal() |
boolean |
isNull()
Returns
true if this state is meant to stand in for Java's built-in null . |
int |
or(BitwiseEnum state) |
boolean |
overlaps(int mask) |
static BleDeviceState |
valueOf(java.lang.String name)
Returns the enum constant of this type with the specified name.
|
static BleDeviceState[] |
values()
Returns an array containing the constants of this enum type, in
the order they are declared.
|
static BleDeviceState[] |
VALUES()
Returns same as
values() , but for performance reasons this does not return a new array every time. |
public static final BleDeviceState ATTEMPTING_CONNECTION_FIX
BleDevice
will be in this state if it is attempting to fix a connection bug where the first time a device is bonded, the connection
will be left open by the underlying bluetooth stack, even though it will report it's state as being disconnected. The "fix" is to unbond, then
bond again, then connect, and finally disconnect. This doesn't fix the issue 100% of the time, but from anecdotal testing, it's very close.public static final BleDeviceState NULL
null
.
A normal BleDevice
will never be in this state, but this will be the sole state of BleDevice.NULL
.public static final BleDeviceState UNDISCOVERED
DiscoveryListener.onEvent(DiscoveryListener.DiscoveryEvent)
.
This means the object is effectively dead. BleManager
has removed all references to it and you should do the same.public static final BleDeviceState RECONNECTING_LONG_TERM
BleNodeConfig.reconnectFilter
is set appropriately and the device implicitly disconnects, either through going out of range,
signal disruption, or whatever, then the device will enter this state. It will continue in this state until you return
ReconnectFilter.ConnectionLostPlease.stopRetrying()
from ReconnectFilter.onConnectionLost(ReconnectFilter.ConnectionLostEvent)
or call BleDevice.disconnect()
or when the device actually successfully reconnects.RECONNECTING_SHORT_TERM
public static final BleDeviceState RECONNECTING_SHORT_TERM
BleNodeConfig.reconnectFilter
is set appropriately and the device implicitly disconnects this state will be entered.
Unlike with RECONNECTING_LONG_TERM
, entering this state does not mean that the BleDevice
becomes BLE_DISCONNECTED
.
By all outward appearances the library treats the BleDevice
as still being BLE_CONNECTED
while transparently trying
to reconnect under the hood using BleNodeConfig.reconnectFilter
. You can even perform
BleDevice.read(UUID, ReadWriteListener)
, BleDevice.write(java.util.UUID, byte[])
, etc.
and they will be queued up until the device *actually* reconnects under the hood.RECONNECTING_LONG_TERM
public static final BleDeviceState RETRYING_BLE_CONNECTION
BLE_DISCONNECTED
, and look like it's not doing anything, unless it's
also in this state. This is not to be confused with RECONNECTING_SHORT_TERM
or RECONNECTING_LONG_TERM
, which only go into those
states once the BleDevice
gets into the INITIALIZED
state.public static final BleDeviceState DISCOVERED
UNDISCOVERED
.public static final BleDeviceState ADVERTISING
BleDevice.getOrigin()
is BleDeviceOrigin.FROM_DISCOVERY
, a device will always be in this state while BLE_CONNECTED
is not active. Note that this doesn't *necessarily* mean that the actual physical device is advertising, just that it was DiscoveryListener.LifeCycle.DISCOVERED
or DiscoveryListener.LifeCycle.REDISCOVERED
through a BleManager.startScan()
, so it is still assumed to be advertising.public static final BleDeviceState BLE_DISCONNECTED
BLE_CONNECTED
is not active. Analogous to BluetoothProfile.STATE_DISCONNECTED
.public static final BleDeviceState UNBONDED
BluetoothDevice.BOND_NONE
. May not be relevant for your application if you don't use encrypted characteristics.public static final BleDeviceState BONDING
BluetoothDevice.BOND_BONDING
. May not be relevant for your application if you don't use encrypted characteristics.
From this state, a device will either become BONDED
(if successful) or UNBONDED
.
If the latter, use BondListener
to get further information on what happened.public static final BleDeviceState BONDED
BluetoothDevice.BOND_BONDED
. May not be relevant for your application if you don't use encrypted characteristics.public static final BleDeviceState CONNECTING_OVERALL
BLE_CONNECTING
,
DISCOVERING_SERVICES
, AUTHENTICATING
, or INITIALIZING
is also active. It is suggested to have BONDING
be a part of this also using BleDeviceConfig.bondFilter
but technically BONDING
can be done outside of this state.public static final BleDeviceState DISCONNECTED
public static final BleDeviceState CONNECTING
public static final BleDeviceState CONNECTED
RECONNECTING_SHORT_TERM
state, as SweetBlue will be trying to reconnect under the hood.public static final BleDeviceState REQUESTING_PHY
public static final BleDeviceState BLE_CONNECTING
BluetoothProfile.STATE_CONNECTING
. If this state is active then we're in the middle of establishing an actual BLE connection.public static final BleDeviceState BLE_CONNECTED
BluetoothProfile.STATE_CONNECTED
. Once this state becomes active we don't consider ourselves "fully" connected
because we still generally have to discover services and maybe do a few reads or writes to initialize things. So generally speaking
no significant action should be taken when the BleDevice
becomes BLE_CONNECTED
. Instead it's best to listen for INITIALIZED
.public static final BleDeviceState DISCOVERING_SERVICES
BLE_CONNECTED
.public static final BleDeviceState SERVICES_DISCOVERED
DISCOVERING_SERVICES
completes successfully.public static final BleDeviceState AUTHENTICATING
BleDevice.connect(BleTransaction.Auth)
or BleDevice.connect(BleTransaction.Auth, BleTransaction.Init)
to start a connection with an authentication transaction.public static final BleDeviceState AUTHENTICATED
BleTransaction
provided to BleDevice.connect(BleTransaction.Auth)
or
BleDevice.connect(BleTransaction.Auth, BleTransaction.Init)
succeeds with BleTransaction.succeed()
, OR if you use
BleDevice.connect()
or BleDevice.connect(BleTransaction.Init)
- i.e. you connect without authentication.
In the latter case the AUTHENTICATING
state is skipped and we go straight to being implicitly AUTHENTICATED
.public static final BleDeviceState INITIALIZING
BleDevice.connect(BleTransaction.Init)
or BleDevice.connect(BleTransaction.Auth, BleTransaction.Init)
to start a connection with an initialization transaction.public static final BleDeviceState INITIALIZED
BleDevice
"fully" connected and ready to go, instead of
basing it off of just BLE_CONNECTED
.
BleTransaction
provided to BleDevice.connect(BleTransaction.Init)
or
BleDevice.connect(BleTransaction.Auth, BleTransaction.Init)
succeeds with BleTransaction.succeed()
, OR if you use
BleDevice.connect()
or BleDevice.connect(BleTransaction.Auth)
or etc.- i.e. you connect without an initialization
transaction. In the latter case the INITIALIZING
state is skipped and we go straight to being implicitly INITIALIZED
.public static final BleDeviceState PERFORMING_OTA
BleDevice.performOta(BleTransaction.Ota)
and remains active until the provided
BleTransaction
calls BleTransaction.succeed()
or BleTransaction.fail()
(or of course if your BleDevice
becomes BLE_DISCONNECTED
).public static final BleDeviceState HIGH_SPEED
BleDevice
is currently
in the high speed state, which gives 2x the speed of Bluetooth 4.Xpublic static final BleDeviceState LONG_RANGE_2X
BleDevice
is currently
in long range (2x) state, which doubles the effective bluetooth range over 4.X.public static final BleDeviceState LONG_RANGE_4x
BleDevice
is currently
in long range (4x) state, which quadruples the effective bluetooth range over 4.X.public static final int FULL_MASK
BleDeviceState
instances together.public static final BleDeviceState[] DEFAULT_STATES
public static BleDeviceState[] values()
for (BleDeviceState c : BleDeviceState.values()) System.out.println(c);
public static BleDeviceState valueOf(java.lang.String name)
name
- the name of the enum constant to be returned.java.lang.IllegalArgumentException
- if this enum type has no constant with the specified namejava.lang.NullPointerException
- if the argument is nullpublic boolean overlaps(int mask)
public int bit()
public boolean didEnter(int oldStateBits, int newStateBits)
State
DeviceStateListener.onEvent(com.idevicesinc.sweetblue.DeviceStateListener.StateEvent)
or ManagerStateListener.onEvent(com.idevicesinc.sweetblue.ManagerStateListener.StateEvent)
, this method tells you whether the
the 'this' state was appended.didEnter
in interface State
State.didExit(int, int)
public boolean didExit(int oldStateBits, int newStateBits)
State
State.didEnter(int, int)
.didExit
in interface State
State.didEnter(int, int)
public int or(BitwiseEnum state)
public static BleDeviceState[] VALUES()
values()
, but for performance reasons this does not return a new array every time.public boolean isInternal()
public static BleDeviceState getTransitoryConnectionState(int stateMask)
PERFORMING_OTA
).
Chronologically this method returns BLE_CONNECTING
, DISCOVERING_SERVICES
,
AUTHENTICATING
(if BleDevice.connect(BleTransaction.Auth)
or
BleDevice.connect(BleTransaction.Auth, BleTransaction.Init)
is called), BONDING
(if relevant),
and INITIALIZING
(if BleDevice.connect(BleTransaction.Init)
or
BleDevice.connect(BleTransaction.Auth, BleTransaction.Init)
is called).stateMask
- Generally the value returned by BleDevice.getStateMask()
.public boolean isNull()
State
true
if this state is meant to stand in for Java's built-in null
.isNull
in interface State
isNull
in interface UsesCustomNull