- BLE operation methods (i.e.
writeCharacteristic(...)
, etc.) return theRequest
class now, instead of boolean. onLinklossOccur
callback has been renamed toonLinkLossOccurred
.- GATT callbacks (for example:
onCharacteristicRead
,onCharacteristicNotified
, etc.) insideBleManagerGattCallback
has been deprecated. UseRequest
callbacks instead. - Build-in Battery Level support has been deprecated. Request Battery Level as any other value.
- A new callbacks method:
onBondingFailed
has been added toBleManagerCallbacks
. shouldAutoConnect()
has ben deprecated, useuseAutoConnect(boolean)
inConnectRequest
instead.- Timeout is supported for connect, disconnect and wait for notification/indication.
Most BLE operations do not support setting timeout, as receiving the
BluetoothGattCallback
is required in order to perform the next operation. - Atomic
RequestQueue
andReliableWriteRequest
are supported. - BLE Library 2.0 uses Java 8. There's no good reason for this except to push the ecosystem to having this be a default. As of AGP 3.2 there is no reason not to do this (via butterknife).
- Replace
initGatt(BluetoothGatt)
withinitialize()
:
Old code:
@Override
protected Deque<Request> initGatt(final BluetoothGatt gatt) {
final LinkedList<Request> requests = new LinkedList<>();
requests.add(Request.newEnableNotificationsRequest(characteristic));
return requests;
}
New code:
@Override
protected void initialize() {
setNotificationCallback(characteristic)
.with(new DataReceivedCallback() {
@Override
public void onDataReceived(@NonNull final BluetoothDevice device, @NonNull final Data data) {
...
}
});
enableNotifications(characteristic)
.enqueue();
}
See changes in Android nRF Toolbox and Android nRF Blinky for more examples.
Remember to call .enqueue()
method for initialization requests!
Connect's completion callback is called after the initialization is done (without or with errors).
- Move your callback implementation from
BleManagerGattCallback
to request callbacks. - To split logic from parsing, we recommend to extend
DataReceivedCallback
interface in a class where your parse your data, and return higher-level values. For a sample, check out nRF Toolbox and Android BLE Common Library. If you are depending on a SIG adopted profile, like Heart Rate Monitor, Proximity, etc., feel free to include the BLE Common Library in your project. It has all the parsers implemented. If your profile isn't there, we are happy to accept PRs. connect()
anddisconnect()
methods also require calling.enqueue()
in asynchronous use.- Replace the
shouldAutoConnect()
method in the manager withconnect(device).useAutConnect(true).enqueue()/await()
.
BleManager
is no longer a generic class. TheBleManagerCallbacks
interface, previously used to notify about connection and bond states, battery level (deprecated) and application-level callbacks, has been deprecated, together withBleManager#setGattCallbacks(...)
. Instead:- Use
BlaManager#setConnectionObserver(...)
to get connection state updates. - Use
BleManager#setBondingObserver(...)
to get bonding events. - If required, manage application-level callbacks in your manager (that extends
BleManager
). - To make transition easier,
LegacyBleManager
class was introduced that can be used pretty much like the oldBleManager
. It even hasmCallbacks
property.
- Use
- Some fields in the BleManager got rid of the Hungarian Notation. In particular,
mCallbacks was renamed to callbacks (except in
LegacyBleManager
), and it got deprecated. - The protected method
getGattCallback()
inBleManager
is now called from the constructor, so can't return a final field of a manager, as they are not initialized yet. Instead, instantiate theBleManagerGattCallback
class from there.
- To make quick transition from 2.1 to 2.2, change the base class of your
BleManager
implementation toLegacyBleManager
and make sure you return an object (not null) fromgetGattCallback()
:
class MyBleManager extends LegacyBleManager<MyBleManagerCallbacks> {
// [...]
@NonNull
@Override
protected BleManagerGattCallback getGattCallback() {
// Before 2.2 it was allowed to return a class property here, but properties are initiated
// after the constructor, so they would still be null here. Instead, create a new object:
return new MyBleManagerGattCallback();
}
// [...]
}
- Remove the type parameter from your
BleManager
implementation class:
class MyBleManager extends BleManager {
// [...]
}
-
Replace
setGattCallbacks(callbacks)
withsetConnectionObserver(observer)
and optionallysetBondingObserver(observer)
. If you are usingandroidx.lifecycle.LiveData
, consider usingno.nordicsemi.android:ble-livedata:$ble-version
dependency in your gradle file. In that case, extendObservableBleManager
instead ofBleManager
and usegetState()
andgetBondingState()
(orstate
andbondingState
properties in Kotlin) to getLiveData
objects. See nRF Blinky for an example.a) The
ConnectionObserver
no longer hasonServicesDiscovered
method.b)
onLinkLossOccurred
was replaced withonDeviceDisconnected
with reasonConnectionObserver#REASON_LINK_LOSS
.c)
onDeviceNotSupported
was replaced withonDeviceDisconnected
with reasonConnectionObserver#REASON_NOT_SUPPORTED
. -
In 2.1.x the implementation of
BleManager
had access to user defined callbacks (mCallbacks
), which could have been used to notify a Service or Activity about incoming notifications, etc. AsBleManager
is no longer a generic type, you'll have to implement this logic on your own. E.g., nRF Blinky is exposing LED and Button state usingLiveData
, which are available for the Activity throughViewModel
.