README.md

@@ -4,9 +4,13 @@
 
 An Android library that solves a lot of Android's Bluetooth Low Energy problems.
 
-> **Warning**
+> [!Note]
+> We're working on a new version of Bluetooth LE library, which eventually will replace this one:
+> [Kotlin BLE Library / version 2.0](https://github.com/NordicSemiconductor/Kotlin-BLE-Library/tree/version/2.0).
+> Mind, that version 2 is not backward compatible version 1 or with this library.
 >
-> This library is getting replaced by our new [Kotlin BLE Library](https://github.com/NordicSemiconductor/Kotlin-BLE-Library).
+> Currently, the library is in the early development stage. It is not recommended for production use,
+> but we encourage you to try it out and provide feedback.
 >
 > The new library offers the following improvements over this one:
 >  * 100% Kotlin code
@@ -23,24 +27,24 @@ The library may be found on Maven Central repository.
 Add it to your project by adding the following dependency:
 
 ```groovy
-implementation 'no.nordicsemi.android:ble:2.7.4'
+implementation 'no.nordicsemi.android:ble:2.7.5'
 ```
 The last version not migrated to AndroidX is 2.0.5.
 
 BLE library with Kotlin extension is available in:
 ```groovy
-implementation 'no.nordicsemi.android:ble-ktx:2.7.4'
+implementation 'no.nordicsemi.android:ble-ktx:2.7.5'
 ```
 
 To import the BLE library with set of parsers for common Bluetooth SIG characteristics, use:
 ```groovy
-implementation 'no.nordicsemi.android:ble-common:2.7.4'
+implementation 'no.nordicsemi.android:ble-common:2.7.5'
 ```
 For more information, read [this](BLE-COMMON.md).
 
 An extension for easier integration with `LiveData` is available after adding:
 ```groovy
-implementation 'no.nordicsemi.android:ble-livedata:2.7.4'
+implementation 'no.nordicsemi.android:ble-livedata:2.7.5'
 ```
 This extension adds `ObservableBleManager` with `state` and `bondingState` properties, which
 notify about connection and bond state using `androidx.lifecycle.LiveData`.

ble/src/main/java/no/nordicsemi/android/ble/BleManagerHandler.java

@@ -337,7 +337,7 @@ public void onReceive(final Context context, final Intent intent) {
 						postCallback(c -> c.onBondingFailed(device));
 						postBondingStateChange(o -> o.onBondingFailed(device));
 						log(Log.WARN, () -> "Bonding failed");
-						if (request != null && request.type == Request.Type.CREATE_BOND) {
+						if (request != null && (request.type == Request.Type.CREATE_BOND || request.type == Request.Type.ENSURE_BOND)) {
 							request.notifyFail(device, FailCallback.REASON_REQUEST_FAILED);
 							request = null;
 						}
@@ -389,7 +389,7 @@ public void onReceive(final Context context, final Intent intent) {
 					log(Log.INFO, () -> "Device bonded");
 					postCallback(c -> c.onBonded(device));
 					postBondingStateChange(o -> o.onBonded(device));
-					if (request != null && request.type == Request.Type.CREATE_BOND) {
+					if (request != null && (request.type == Request.Type.CREATE_BOND || request.type == Request.Type.ENSURE_BOND)) {
 						request.notifySuccess(device);
 						request = null;
 						break;
@@ -689,48 +689,62 @@ private boolean internalConnect(@NonNull final BluetoothDevice device,
 		// when retrying to create a connection.
 		if (connectRequest == null)
 			return false;
+
 		final boolean shouldAutoConnect = connectRequest.shouldAutoConnect();
-		// We will receive Link Loss events only when the device is connected with autoConnect=true.
-		userDisconnected = !shouldAutoConnect;
-		// The first connection will always be done with autoConnect = false to make the connection quick.
-		// If the shouldAutoConnect() method returned true, the manager will automatically try to
-		// reconnect to this device on link loss.
+		final boolean autoConnect;
 		if (shouldAutoConnect) {
-			initialConnection = true;
+			// If shouldAutoConnectCreateDirectConnectionFirst() returns true, the first connection
+			// will always be done with autoConnect = false to make the connection quick.
+			// If the shouldAutoConnect() method returned true, the manager will automatically try
+			// to reconnect to this device on link loss.
+			initialConnection = connectRequest.shouldAutoConnectCreateDirectConnectionFirst();
+			autoConnect = !initialConnection;
+		} else {
+			autoConnect = false;
 		}
+		// We will receive Link Loss events only when the device is connected with autoConnect=true.
+		userDisconnected = !shouldAutoConnect;
+
 		bluetoothDevice = device;
-		log(Log.VERBOSE, () -> connectRequest.isFirstAttempt() ? "Connecting..." : "Retrying...");
-		connectionState = BluetoothGatt.STATE_CONNECTING;
-		postCallback(c -> c.onDeviceConnecting(device));
-		postConnectionStateChange(o -> o.onDeviceConnecting(device));
+		if (!autoConnect) {
+			log(Log.VERBOSE, () -> connectRequest.isFirstAttempt() ? "Connecting..." : "Retrying...");
+			connectionState = BluetoothGatt.STATE_CONNECTING;
+			postCallback(c -> c.onDeviceConnecting(device));
+			postConnectionStateChange(o -> o.onDeviceConnecting(device));
+		}
 		connectionTime = SystemClock.elapsedRealtime();
 		if (Build.VERSION.SDK_INT > Build.VERSION_CODES.O) {
 			// connectRequest will never be null here.
 			final int preferredPhy = connectRequest.getPreferredPhy();
 			log(Log.DEBUG, () ->
-					"gatt = device.connectGatt(autoConnect = false, TRANSPORT_LE, "
+					"gatt = device.connectGatt(autoConnect = " + autoConnect + ", TRANSPORT_LE, "
 							+ ParserUtils.phyMaskToString(preferredPhy) + ")");
 
-			bluetoothGatt = device.connectGatt(context, false, gattCallback,
+			bluetoothGatt = device.connectGatt(context, autoConnect, gattCallback,
 					BluetoothDevice.TRANSPORT_LE, preferredPhy, handler);
 		} else if (Build.VERSION.SDK_INT == Build.VERSION_CODES.O) {
 			// connectRequest will never be null here.
 			final int preferredPhy = connectRequest.getPreferredPhy();
 			log(Log.DEBUG, () ->
-					"gatt = device.connectGatt(autoConnect = false, TRANSPORT_LE, "
+					"gatt = device.connectGatt(autoConnect = " + autoConnect + ", TRANSPORT_LE, "
 							+ ParserUtils.phyMaskToString(preferredPhy) + ")");
 			// A variant of connectGatt with Handled can't be used here.
 			// Check https://github.com/NordicSemiconductor/Android-BLE-Library/issues/54
 			// This bug specifically occurs in SDK 26 and is fixed in SDK 27
-			bluetoothGatt = device.connectGatt(context, false, gattCallback,
+			bluetoothGatt = device.connectGatt(context, autoConnect, gattCallback,
 					BluetoothDevice.TRANSPORT_LE, preferredPhy/*, handler*/);
 		} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
-			log(Log.DEBUG, () -> "gatt = device.connectGatt(autoConnect = false, TRANSPORT_LE)");
-			bluetoothGatt = device.connectGatt(context, false, gattCallback,
+			log(Log.DEBUG, () -> "gatt = device.connectGatt(autoConnect = " + autoConnect + ", TRANSPORT_LE)");
+			bluetoothGatt = device.connectGatt(context, autoConnect, gattCallback,
 					BluetoothDevice.TRANSPORT_LE);
 		} else {
-			log(Log.DEBUG, () -> "gatt = device.connectGatt(autoConnect = false)");
-			bluetoothGatt = device.connectGatt(context, false, gattCallback);
+			log(Log.DEBUG, () -> "gatt = device.connectGatt(autoConnect = " + autoConnect + ")");
+			bluetoothGatt = device.connectGatt(context, autoConnect, gattCallback);
+		}
+
+		if (autoConnect && this.connectRequest != null) {
+			this.connectRequest.notifySuccess(device);
+			this.connectRequest = null;
 		}
 		return true;
 	}

ble/src/main/java/no/nordicsemi/android/ble/ConnectRequest.java

@@ -60,6 +60,7 @@ public class ConnectRequest extends TimeoutableRequest {
 	@IntRange(from = 0)
 	private int delay = 0;
 	private boolean autoConnect = false;
+	private boolean autoConnectCreateDirectConnectionFirst = true;
 
 	ConnectRequest(@NonNull final Type type, @NonNull final BluetoothDevice device) {
 		super(type);
@@ -209,6 +210,47 @@ public ConnectRequest useAutoConnect(final boolean autoConnect) {
 		return this;
 	}
 
+	/**
+	 * Sets whether to connect to the remote device just once (autoConnect == false) or to add
+	 * the address to white list of devices that will be automatically connect as soon as they
+	 * become available (autoConnect == true). In the latter case, if Bluetooth adapter is enabled,
+	 * Android scans periodically for devices from the white list and, if an advertising packet
+	 * is received from such, it tries to connect to it.
+	 * When the connection is lost, the system will keep trying to reconnect to
+	 * it. If method is called with autoConnect set to true, and the connection to the device is
+	 * lost, the {@link BleManagerCallbacks#onLinkLossOccurred(BluetoothDevice)} callback is
+	 * called instead of {@link BleManagerCallbacks#onDeviceDisconnected(BluetoothDevice)}.
+	 * <p>
+	 * This feature works much better on newer Android phone models and may have issues on older
+	 * phones.
+	 * <p>
+	 * This method should only be used with bonded devices, as otherwise the device may change
+	 * it's address. It will however work also with non-bonded devices with private static address.
+	 * A connection attempt to a non-bonded device with private resolvable address will fail.
+	 * <p>
+	 * If createDirectConnectionFirst is set to true, the first connection to a device will always be
+	 * created with autoConnect flag to false
+	 * (see {@link BluetoothDevice#connectGatt(Context, boolean, BluetoothGattCallback)}). This is
+	 * to make it quick as the user most probably waits for a quick response. If autoConnect is
+	 * used (true), the following connections will be done using {@link BluetoothGatt#connect()},
+	 * which forces the autoConnect parameter to true.
+	 * If autoConnect is used (true) and createDirectConnectionFirst is set to false, the connection
+	 * to a device will be created with autoConnect flag to true from the start.
+	 *
+	 * @param autoConnect                 true to use autoConnect feature.
+	 * @param createDirectConnectionFirst If true, the first connection is always done with autoConnect
+	 *                                    parameter equal to false, to make it faster and allow to timeout
+	 *                                    if the device is unreachable.
+	 *                                    If false, the connection to a device will be created with
+	 *                                    autoConnect flag to true from the start.
+	 * @return The request.
+	 */
+	public ConnectRequest useAutoConnect(final boolean autoConnect, final boolean createDirectConnectionFirst) {
+		this.autoConnect = autoConnect;
+		this.autoConnectCreateDirectConnectionFirst = createDirectConnectionFirst;
+		return this;
+	}
+
 	/**
 	 * Sets the preferred PHY used for connection. The value should be a bitmask composed of
 	 * {@link PhyRequest#PHY_LE_1M_MASK}, {@link PhyRequest#PHY_LE_2M_MASK} or
@@ -293,4 +335,8 @@ int getRetryDelay() {
 	boolean shouldAutoConnect() {
 		return autoConnect;
 	}
+
+	boolean shouldAutoConnectCreateDirectConnectionFirst() {
+		return autoConnectCreateDirectConnectionFirst;
+	}
 }

moustache/README.mo

@@ -4,9 +4,13 @@
 
 An Android library that solves a lot of Android's Bluetooth Low Energy problems.
 
-> **Warning**
+> [!Note]
+> We're working on a new version of Bluetooth LE library, which eventually will replace this one:
+> [Kotlin BLE Library / version 2.0](https://github.com/NordicSemiconductor/Kotlin-BLE-Library/tree/version/2.0).
+> Mind, that version 2 is not backward compatible version 1 or with this library.
 >
-> This library is getting replaced by our new [Kotlin BLE Library](https://github.com/NordicSemiconductor/Kotlin-BLE-Library).
+> Currently, the library is in the early development stage. It is not recommended for production use,
+> but we encourage you to try it out and provide feedback.
 >
 > The new library offers the following improvements over this one:
 >  * 100% Kotlin code