Add logging support (#131)

Author: twyatt

README.md

@@ -17,6 +17,31 @@ To scan for nearby peripherals, the [`Scanner`] provides an [`advertisements`] [
 [`Advertisement`] objects representing advertisements seen from nearby peripherals. [`Advertisement`] objects contain
 information such as the peripheral's name and RSSI (signal strength).
 
+The [`Scanner`] may be configured via the following DSL (shown are defaults, when not specified):
+
+```kotlin
+val scanner = Scanner {
+    services = null
+    logging {
+        engine = SystemLogEngine
+        level = Warnings
+        format = Multiline
+    }
+}
+```
+
+To filter scan results at the system level (recommended), specify a list of services the remote peripheral is
+advertising, for example:
+
+```kotlin
+val scanner = Scanner {
+    services = listOf(
+        uuidFrom("f000aa80-0451-4000-b000-000000000000"),
+        uuidFrom("f000aa81-0451-4000-b000-000000000000"),
+    )
+}
+```
+
 Scanning begins when the [`advertisements`] [`Flow`] is collected and stops when the [`Flow`] collection is terminated.
 A [`Flow`] terminal operator (such as [`first`]) may be used to scan until an advertisement is found that matches a
 desired predicate. 
@@ -40,6 +65,8 @@ connection handling and I/O operations.
 val peripheral = scope.peripheral(advertisement)
 ```
 
+### Configuration
+
 To configure a `peripheral`, options may be set in the builder lambda:
 
 ```kotlin
@@ -48,6 +75,70 @@ val peripheral = scope.peripheral(advertisement) {
 }
 ```
 
+#### Logging
+
+By default, Kable only logs a small number of warnings when unexpected failures occur. To aid in debugging, additional
+logging may be enabled and configured via the `logging` DSL, for example:
+
+```kotlin
+val peripheral = scope.peripheral(advertisement) {
+    logging {
+        level = Events // or Data
+    }
+}
+```
+
+The available log levels are:
+
+- `Warnings`: Logs warnings when unexpected failures occur _(default)_
+- `Events`: Same as `Warnings` plus logs all events (e.g. writing to a characteristic)
+- `Data`: Same as `Events` plus string representation of I/O data
+
+Available logging settings are as follows (all settings are optional; shown are defaults, when not specified):
+
+```kotlin
+val peripheral = scope.peripheral(advertisement) {
+    logging {
+        engine = SystemLogEngine
+        level = Warnings
+        format = Multiline
+        data = Hex
+    }
+}
+```
+
+The format of the logs can be either `Compact` (on a single line per log) or `Multiline` (spanning multiple lines for
+details):
+
+| `Compact` | `Multiline` _(default)_ |
+|-----------|-------------------------|
+| <pre>example message(detail1=value1, detail2=value2, ...)</pre> | <pre>example message<br/>  detail1: value1<br/>  detail2: value2<br/>  ...</pre> |
+
+Display format of I/O data may be customized, either by configuring the `Hex` representation, or by providing a
+`DataProcessor`, for example:
+
+```kotlin
+val peripheral = scope.peripheral(advertisement) {
+    logging {
+        data = Hex {
+            separator = " "
+            lowerCase = false
+        }
+
+        // or...
+
+        data = DataProcessor { bytes ->
+            // todo: Convert `bytes` to desired String representation, for example:
+            bytes.joinToString { byte -> byte.toString() } // Show data as integer representation of bytes.
+        }
+    }
+}
+```
+
+_I/O data is only shown in logs when logging `level` is set to `Data`._
+
+#### Service Discovery
+
 All platforms support an `onServicesDiscovered` action (that is executed after service discovery but before observations
 are wired up):
 

buildSrc/src/main/kotlin/Dependencies.kt

@@ -27,3 +27,8 @@ object androidx {
         version: String = "1.0.0"
     ) = "androidx.startup:startup-runtime:$version"
 }
+
+fun tuulbox(
+    module: String,
+    version: String = "4.3.0"
+) = "com.juul.tuulbox:$module:$version"

core/api/core.api

@@ -182,6 +182,7 @@ public final class com/juul/kable/Peripheral$DefaultImpls {
 public final class com/juul/kable/PeripheralBuilder {
 	public final fun getPhy ()Lcom/juul/kable/Phy;
 	public final fun getTransport ()Lcom/juul/kable/Transport;
+	public final fun logging (Lkotlin/jvm/functions/Function1;)V
 	public final fun onServicesDiscovered (Lkotlin/jvm/functions/Function2;)V
 	public final fun setPhy (Lcom/juul/kable/Phy;)V
 	public final fun setTransport (Lcom/juul/kable/Transport;)V
@@ -224,9 +225,17 @@ public abstract interface class com/juul/kable/Scanner {
 	public abstract fun getAdvertisements ()Lkotlinx/coroutines/flow/Flow;
 }
 
+public final class com/juul/kable/ScannerBuilder {
+	public fun <init> ()V
+	public final fun getServices ()Ljava/util/List;
+	public final fun logging (Lkotlin/jvm/functions/Function1;)V
+	public final fun setServices (Ljava/util/List;)V
+}
+
 public final class com/juul/kable/ScannerKt {
 	public static final fun Scanner (Ljava/util/List;)Lcom/juul/kable/Scanner;
-	public static synthetic fun Scanner$default (Ljava/util/List;ILjava/lang/Object;)Lcom/juul/kable/Scanner;
+	public static final fun Scanner (Lkotlin/jvm/functions/Function1;)Lcom/juul/kable/Scanner;
+	public static synthetic fun Scanner$default (Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/juul/kable/Scanner;
 }
 
 public abstract interface class com/juul/kable/Service {
@@ -273,6 +282,10 @@ public final class com/juul/kable/State$Disconnected$Status$Cancelled : com/juul
 	public static final field INSTANCE Lcom/juul/kable/State$Disconnected$Status$Cancelled;
 }
 
+public final class com/juul/kable/State$Disconnected$Status$CentralDisconnected : com/juul/kable/State$Disconnected$Status {
+	public static final field INSTANCE Lcom/juul/kable/State$Disconnected$Status$CentralDisconnected;
+}
+
 public final class com/juul/kable/State$Disconnected$Status$ConnectionLimitReached : com/juul/kable/State$Disconnected$Status {
 	public static final field INSTANCE Lcom/juul/kable/State$Disconnected$Status$ConnectionLimitReached;
 }
@@ -285,6 +298,14 @@ public final class com/juul/kable/State$Disconnected$Status$Failed : com/juul/ka
 	public static final field INSTANCE Lcom/juul/kable/State$Disconnected$Status$Failed;
 }
 
+public final class com/juul/kable/State$Disconnected$Status$L2CapFailure : com/juul/kable/State$Disconnected$Status {
+	public static final field INSTANCE Lcom/juul/kable/State$Disconnected$Status$L2CapFailure;
+}
+
+public final class com/juul/kable/State$Disconnected$Status$LinkManagerProtocolTimeout : com/juul/kable/State$Disconnected$Status {
+	public static final field INSTANCE Lcom/juul/kable/State$Disconnected$Status$LinkManagerProtocolTimeout;
+}
+
 public final class com/juul/kable/State$Disconnected$Status$PeripheralDisconnected : com/juul/kable/State$Disconnected$Status {
 	public static final field INSTANCE Lcom/juul/kable/State$Disconnected$Status$PeripheralDisconnected;
 }
@@ -335,3 +356,66 @@ public final class com/juul/kable/WriteType : java/lang/Enum {
 	public static fun values ()[Lcom/juul/kable/WriteType;
 }
 
+public final class com/juul/kable/logs/HexBuilder {
+	public final fun getLowerCase ()Z
+	public final fun getSeparator ()Ljava/lang/String;
+	public final fun setLowerCase (Z)V
+	public final fun setSeparator (Ljava/lang/String;)V
+}
+
+public final class com/juul/kable/logs/HexKt {
+	public static final fun Hex (Lkotlin/jvm/functions/Function1;)Lcom/juul/kable/logs/Logging$DataProcessor;
+	public static synthetic fun Hex$default (Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lcom/juul/kable/logs/Logging$DataProcessor;
+	public static final fun getHex ()Lcom/juul/kable/logs/Logging$DataProcessor;
+}
+
+public abstract interface class com/juul/kable/logs/LogEngine {
+	public abstract fun assert (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+	public abstract fun debug (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+	public abstract fun error (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+	public abstract fun info (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+	public abstract fun verbose (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+	public abstract fun warn (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+}
+
+public final class com/juul/kable/logs/Logging {
+	public fun <init> ()V
+	public final fun getData ()Lcom/juul/kable/logs/Logging$DataProcessor;
+	public final fun getEngine ()Lcom/juul/kable/logs/LogEngine;
+	public final fun getFormat ()Lcom/juul/kable/logs/Logging$Format;
+	public final fun getLevel ()Lcom/juul/kable/logs/Logging$Level;
+	public final fun setData (Lcom/juul/kable/logs/Logging$DataProcessor;)V
+	public final fun setEngine (Lcom/juul/kable/logs/LogEngine;)V
+	public final fun setFormat (Lcom/juul/kable/logs/Logging$Format;)V
+	public final fun setLevel (Lcom/juul/kable/logs/Logging$Level;)V
+}
+
+public abstract interface class com/juul/kable/logs/Logging$DataProcessor {
+	public abstract fun process ([B)Ljava/lang/String;
+}
+
+public final class com/juul/kable/logs/Logging$Format : java/lang/Enum {
+	public static final field Compact Lcom/juul/kable/logs/Logging$Format;
+	public static final field Multiline Lcom/juul/kable/logs/Logging$Format;
+	public static fun valueOf (Ljava/lang/String;)Lcom/juul/kable/logs/Logging$Format;
+	public static fun values ()[Lcom/juul/kable/logs/Logging$Format;
+}
+
+public final class com/juul/kable/logs/Logging$Level : java/lang/Enum {
+	public static final field Data Lcom/juul/kable/logs/Logging$Level;
+	public static final field Events Lcom/juul/kable/logs/Logging$Level;
+	public static final field Warnings Lcom/juul/kable/logs/Logging$Level;
+	public static fun valueOf (Ljava/lang/String;)Lcom/juul/kable/logs/Logging$Level;
+	public static fun values ()[Lcom/juul/kable/logs/Logging$Level;
+}
+
+public final class com/juul/kable/logs/SystemLogEngine : com/juul/kable/logs/LogEngine {
+	public static final field INSTANCE Lcom/juul/kable/logs/SystemLogEngine;
+	public fun assert (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+	public fun debug (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+	public fun error (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+	public fun info (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+	public fun verbose (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+	public fun warn (Ljava/lang/Throwable;Ljava/lang/String;Ljava/lang/String;)V
+}
+

core/build.gradle.kts

@@ -84,10 +84,6 @@ android {
         minSdkVersion(21)
     }
 
-    buildFeatures {
-        buildConfig = false
-    }
-
     lintOptions {
         isAbortOnError = true
         isWarningsAsErrors = true

core/src/androidMain/kotlin/BluetoothDevice.kt

@@ -13,6 +13,7 @@ import android.os.Build
 import android.os.Handler
 import android.os.HandlerThread
 import com.juul.kable.gatt.Callback
+import com.juul.kable.logs.Logging
 import kotlinx.coroutines.android.asCoroutineDispatcher
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.newSingleThreadContext
@@ -27,12 +28,13 @@ internal fun BluetoothDevice.connect(
     phy: Phy,
     state: MutableStateFlow<State>,
     mtu: MutableStateFlow<Int?>,
+    logging: Logging,
     invokeOnClose: () -> Unit,
 ): Connection? =
     if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-        connectApi26(context, transport, phy, state, mtu, invokeOnClose)
+        connectApi26(context, transport, phy, state, mtu, logging, invokeOnClose)
     } else {
-        connectApi21(context, transport, state, mtu, invokeOnClose)
+        connectApi21(context, transport, state, mtu, logging, invokeOnClose)
     }
 
 /**
@@ -44,9 +46,10 @@ private fun BluetoothDevice.connectApi21(
     transport: Transport,
     state: MutableStateFlow<State>,
     mtu: MutableStateFlow<Int?>,
+    logging: Logging,
     invokeOnClose: () -> Unit,
 ): Connection? {
-    val callback = Callback(state, mtu)
+    val callback = Callback(state, mtu, logging, address)
     val bluetoothGatt = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
         connectGatt(context, false, callback, transport.intValue)
     } else {
@@ -76,13 +79,14 @@ private fun BluetoothDevice.connectApi26(
     phy: Phy,
     state: MutableStateFlow<State>,
     mtu: MutableStateFlow<Int?>,
+    logging: Logging,
     invokeOnClose: () -> Unit,
 ): Connection? {
     val thread = HandlerThread(threadName).apply { start() }
     try {
         val handler = Handler(thread.looper)
         val dispatcher = handler.asCoroutineDispatcher()
-        val callback = Callback(state, mtu)
+        val callback = Callback(state, mtu, logging, address)
 
         val bluetoothGatt =
             connectGatt(context, false, callback, transport.intValue, phy.intValue, handler)

core/src/androidMain/kotlin/Observers.kt

@@ -1,6 +1,7 @@
 package com.juul.kable
 
-import android.util.Log
+import com.juul.kable.logs.Logger
+import com.juul.kable.logs.Logging
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.filter
@@ -49,8 +50,11 @@ internal sealed class AndroidObservationEvent {
  */
 internal class Observers(
     private val peripheral: AndroidPeripheral,
+    logging: Logging,
 ) {
 
+    private val logger = Logger(logging, tag = "Kable/Observers")
+
     val characteristicChanges = MutableSharedFlow<AndroidObservationEvent>()
     private val observations = Observations()
 
@@ -82,7 +86,7 @@ internal class Observers(
                 } catch (e: NotReadyException) {
                     // Silently ignore as it is assumed that failure is due to connection drop, in which case Android
                     // will clear the notifications.
-                    Log.d(TAG, "Stop notification failure ignored.")
+                    logger.debug { message = "Stop notification failure ignored." }
                 }
             }
         }