Merge pull request #213 from NordicSemiconductor/connection-states

`Closed` connection state removed in favor of `Disconnected`

Author: philips77

client-android-mock/src/main/java/no/nordicsemi/kotlin/ble/client/android/mock/internal/MockExecutor.kt

@@ -59,7 +59,7 @@ open class MockExecutor(
     name: String?,
 ): Peripheral.Executor {
     override val type: PeripheralType = peripheralSpec.type
-    override val initialState: ConnectionState = ConnectionState.Closed
+    override val initialState: ConnectionState = ConnectionState.Disconnected()
     override val initialServices: List<RemoteService> = emptyList()
 
     override val identifier: String = peripheralSpec.identifier

client-android/src/main/java/no/nordicsemi/kotlin/ble/client/android/internal/NativeExecutor.kt

@@ -76,7 +76,7 @@ internal class NativeExecutor(
     } catch (_: SecurityException) {
         name
     }
-    override val initialState: ConnectionState = ConnectionState.Closed
+    override val initialState: ConnectionState = ConnectionState.Disconnected()
     override val initialServices: List<RemoteService> = emptyList()
 
     /**

client-core-android/src/main/java/no/nordicsemi/kotlin/ble/client/android/Peripheral.kt

@@ -260,15 +260,15 @@ open class Peripheral(
                             // direct connection.
                             //
                             // See: https://cs.android.com/android/platform/superproject/main/+/main:packages/modules/Bluetooth/system/stack/gatt/gatt_api.cc;l=1450
-                            val reason = state.reason
+                            val reason = state.reason!!
                             if (reason is Reason.Unknown && (reason.status == 133 || reason.status == 135)) {
                                 logger.warn("Connection attempt failed (reason: {})", Reason.UnsupportedAddress)
                                 _state.update { ConnectionState.Disconnected(Reason.UnsupportedAddress) }
                                 throw ConnectionFailedException(Reason.UnsupportedAddress)
                             }
-                            logger.warn("Connection attempt failed (reason: {})", state.reason)
+                            logger.warn("Connection attempt failed (reason: {})", reason)
                             _state.update { state }
-                            throw ConnectionFailedException(state.reason)
+                            throw ConnectionFailedException(reason)
                         }
                         else -> {}
                     }
@@ -309,9 +309,10 @@ open class Peripheral(
                         }
                         is ConnectionState.Disconnected -> {
                             check(options.retry > 0) {
-                                logger.warn("Connection attempt failed (reason: {})", state.reason)
+                                val reason = state.reason!!
+                                logger.warn("Connection attempt failed (reason: {})", reason)
                                 _state.update { state }
-                                throw ConnectionFailedException(state.reason)
+                                throw ConnectionFailedException(reason)
                             }
                             logger.warn("Connection attempt failed (reason: {}), retrying in {}...",
                                 state.reason, options.retryDelay)
@@ -581,7 +582,6 @@ open class Peripheral(
      * by [services] will emit an empty list of services following by updated list of services
      * when the new service discovery is complete.
      *
-     * The peripheral must be in any state other then [ConnectionState.Closed].
      * It is safe to call this method when the peripheral is connected, connecting, or disconnecting.
      * It may be called when the device is disconnected but only when the connection was made using
      * [AutoConnect][CentralManager.ConnectionOptions.AutoConnect] option in which case the system
@@ -590,9 +590,9 @@ open class Peripheral(
      * A connection made using [Direct][CentralManager.ConnectionOptions.Direct] option closes
      * automatically immediately after disconnection.
      *
-     * When invoked when closed the method throws [PeripheralClosedException].
+     * When invoked on a closed connection the method throws [PeripheralClosedException].
      *
-     * @throws PeripheralClosedException If the peripheral is in [Closed][ConnectionState.Closed] state.
+     * @throws PeripheralClosedException If the peripheral is closed.
      * @throws OperationFailedException If cache could not be refreshed.
      * @throws SecurityException If BLUETOOTH_CONNECT permission is denied.
      */

client-core-android/src/main/java/no/nordicsemi/kotlin/ble/client/android/preview/PreviewPeripheral.kt

@@ -386,7 +386,7 @@ open class PreviewPeripheral(
     type: PeripheralType = PeripheralType.LE,
     rssi: Int = -40, // dBm
     phy: PhyInUse = PhyInUse.PHY_LE_1M,
-    state: ConnectionState = ConnectionState.Closed,
+    state: ConnectionState = ConnectionState.Disconnected(),
     services: ServerScope.() -> Unit = {
         Service(Service.GENERIC_ACCESS_UUID) {
             Characteristic(

client-core/src/main/java/no/nordicsemi/kotlin/ble/client/GattEvent.kt

@@ -57,10 +57,10 @@ sealed class GattEvent {
 data class ConnectionStateChanged(val newState: ConnectionState) : GattEvent() {
 
     /**
-     * Returns whether the new state is [ConnectionState.Disconnected] or [ConnectionState.Closed].
+     * Returns whether the new state is [ConnectionState.Disconnected].
      */
     val disconnected: Boolean
-        get() = newState is ConnectionState.Disconnected || newState is ConnectionState.Closed
+        get() = newState is ConnectionState.Disconnected
 }
 
 /**

client-core/src/main/java/no/nordicsemi/kotlin/ble/client/Peripheral.kt

@@ -41,7 +41,6 @@ import kotlinx.coroutines.flow.SharedFlow
 import kotlinx.coroutines.flow.SharingStarted
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
-import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.filterIsInstance
 import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.flow.firstOrNull
@@ -239,14 +238,28 @@ abstract class Peripheral<ID: Any, EX: Peripheral.Executor<ID>>(
 
         gattEventCollector = impl.events
             // Handle each GATT event.
-            .onEach { handle(it) }
-            // In case of a Connection State Changed event...
-            .filterIsInstance(ConnectionStateChanged::class)
-            // ...when the device got disconnected and the closeWhenDisconnected flag was set...
-            .filter { closeWhenDisconnected && it.newState is ConnectionState.Disconnected }
-            // ...cancel the collector. This will call...
-            .onEach { gattEventCollector?.cancel() }
-            // ...the onCompletion method.
+            .onEach { event ->
+                when {
+                    // In case of a disconnection event...
+                    event is ConnectionStateChanged && event.newState is ConnectionState.Disconnected -> {
+                        // ...when the connection was terminated using disconnect() or cancelled,
+                        // or the closeWhenDisconnected flag was set (no automatic reconnection)
+                        // process the event and cancel the collector.
+                        if (event.newState.isUserInitiated || closeWhenDisconnected) {
+                            handle(event)
+                            // This will call the onCompletion method below.
+                            gattEventCollector?.cancel()
+                        } else {
+                            // If the connection will be retried, switch immediately to Connecting state.
+                            // Note: This changes state Connected -> Connecting, without going through
+                            //       Disconnected state.
+                            handle(ConnectionStateChanged(ConnectionState.Connecting))
+                        }
+                    }
+                    // Handle other events.
+                    else -> handle(event)
+                }
+            }
             .onCompletion {
                 gattEventCollector = null
                 close()
@@ -266,7 +279,6 @@ abstract class Peripheral<ID: Any, EX: Peripheral.Executor<ID>>(
             handleClose()
             serviceDiscoveryRequested = false
             impl.close()
-            _state.update { ConnectionState.Closed }
         }
         gattEventCollector = null
     }
@@ -315,6 +327,9 @@ abstract class Peripheral<ID: Any, EX: Peripheral.Executor<ID>>(
                     is ConnectionState.Connected -> {
                         initiateConnection()
                     }
+                    // When the link is lost, a peripheral state may transition from Connected
+                    // to Connecting or Disconnected.
+                    is ConnectionState.Connecting,
                     is ConnectionState.Disconnected -> {
                         handleDisconnection()
                     }
@@ -486,10 +501,6 @@ abstract class Peripheral<ID: Any, EX: Peripheral.Executor<ID>>(
     suspend fun disconnect() {
         // Depending on the state...
         when (state.value) {
-            is ConnectionState.Closed -> {
-                // Do nothing when already closed.
-                return
-            }
             is ConnectionState.Disconnected -> {
                 // Make sure auto-connection is closed.
                 close()

core/src/main/java/no/nordicsemi/kotlin/ble/core/ConnectionState.kt

@@ -33,30 +33,54 @@
 
 package no.nordicsemi.kotlin.ble.core
 
+import no.nordicsemi.kotlin.ble.core.ConnectionState.Disconnected.Reason.Cancelled
+import no.nordicsemi.kotlin.ble.core.ConnectionState.Disconnected.Reason.Success
 import kotlin.time.Duration
 
 /**
  * Connection state of a Bluetooth LE peripheral.
  */
 sealed class ConnectionState {
 
-    /** Connection has been initiated. */
+    /**
+     * The client is trying to connect to the peripheral.
+     *
+     * When connected, the state will change to [Connected].
+     *
+     * On timeout or cancellation, the state will change to [Disconnected] with the correct reason.
+     */
     data object Connecting: ConnectionState()
 
-    /** The peripheral is connected. */
+    /**
+     * The peripheral is connected.
+     *
+     * When the connection terminates, the state will change to [Disconnected]
+     * or [Connecting] if the client will try to reconnect.
+     */
     data object Connected: ConnectionState()
 
-    /** Disconnection has been initiated. */
+    /**
+     * Disconnection has been initiated.
+     *
+     * This state is set when the `disconnect()` method is called on the peripheral.
+     *
+     * This is followed by [Disconnected] state with reason [Success][Disconnected.Reason.Success].
+     */
     data object Disconnecting: ConnectionState()
 
     /**
      * Device has disconnected.
      *
-     * This state may be immediately followed by [Closed] state.
+     * If the [reason] is null, it means that no connection attempt was made. This is
+     * the initial state of the peripheral.
+     *
+     * Note, that it doesn't mean that the peripheral is not connected, it may be connected
+     * using another [Manager].
      *
-     * @param reason Reason of disconnection.
+     * @param reason Reason of disconnection or `null` if the connection was never initiated.
+     * This is the initial state of the peripheral.
      */
-    data class Disconnected(val reason: Reason): ConnectionState() {
+    data class Disconnected(val reason: Reason? = null): ConnectionState() {
 
         /** Reason of disconnection. */
         sealed class Reason {
@@ -115,21 +139,22 @@ sealed class ConnectionState {
              * @property duration The duration of the timeout.
              */
             data class Timeout(val duration: Duration): Reason()
-
-            /** A quick check whether the disconnection was initiated by the user. */
-            val isUserInitiated: Boolean
-                get() = this is Success || this is Cancelled
         }
-    }
 
-    /** The connection is closed. */
-    data object Closed: ConnectionState()
+        /**
+         * A quick check whether the disconnection was initiated by the user.
+         *
+         * This returns `false` in the initial state, that is before the connection attempt was started.
+         */
+        val isUserInitiated: Boolean
+            get() = reason is Success || reason is Cancelled
+    }
 
     /** Whether the connection is open. */
     val isConnected: Boolean
         get() = this is Connected
 
     /** Whether the connection closed or getting closed. */
     val isDisconnected: Boolean
-        get() = this is Disconnected || this is Closed
+        get() = this is Disconnected
 }

sample/src/main/java/no/nordicsemi/kotlin/ble/android/sample/scanner/ScannerViewModel.kt

@@ -41,7 +41,6 @@ import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
-import kotlinx.coroutines.flow.buffer
 import kotlinx.coroutines.flow.catch
 import kotlinx.coroutines.flow.filterNot
 import kotlinx.coroutines.flow.filterNotNull
@@ -355,7 +354,6 @@ class ScannerViewModel @Inject constructor(
 
     private fun observePeripheralState(peripheral: Peripheral, scope: CoroutineScope) {
         peripheral.state
-            .buffer()
             .onEach {
                 Timber.i("State of $peripheral: $it")
 
@@ -367,7 +365,7 @@ class ScannerViewModel @Inject constructor(
                         }
                     }
 
-                    is ConnectionState.Closed -> {
+                    is ConnectionState.Disconnected -> {
                         // Just for testing, wait with cancelling the scope to get all the logs.
                         delay(500)
                         // Cancel connection scope, so that previously launched jobs are cancelled.