feat: add bluetooth backend abstraction & support devices with multiple measurements

BLUETOOTH.md

@@ -0,0 +1,44 @@
+# Supported Bluetooth devices
+
+In general any device that supports [`Blood Pressure Service (0x1810)`](https://bitbucket.org/bluetooth-SIG/public/src/main/assigned_numbers/uuids/service_uuids.yaml#lines-77:79) could be used. The blood pressure measurement values are stored in the characteristic [`Blood Pressure Measurement (0x2A35)`](https://bitbucket.org/bluetooth-SIG/public/src/main/assigned_numbers/uuids/characteristic_uuids.yaml#lines-161:163)
+
+## Reading caveats
+
+There are some difference in how devices report their measurements.
+
+Most devices provide 2 ways to retrieve measurements over bluetooth, but there are also difference in how those operate:
+
+1. Immediately after taking a measurement
+    1. and returns all measurements stored in memory
+    2. and only returns the latest measurement
+2. As a download mode
+    1. and automatically remove all locally stored measurements after a succesful download
+    2. and leave measurements untouched, i.e. the user needs to remove the stored measurements themselves
+
+> :warning: At the moment situation 2.i is not well supported. Do not use this unless you are ok with loosing previously stored measurements
+
+## Known working devices
+
+> If your device is not listed please edit this page and add it! :bow:
+
+|Device|Bluetooth name|Read after measurement|Download mode|Automatically disconnects after reading|
+|---|---| :---: | :---: | :---: |
+|HealthForYou by Silvercrest (Type SBM 69)|SBM69| :1234: | :white_check_mark: | :white_check_mark: |
+|Omron X4 Smart|X4 Smart| :one: | :white_check_mark::wastebasket: | :white_check_mark: |
+
+#### Legenda
+
+|Icon|Description|
+| :---: | --- |
+| :no_entry_sign: |Not supported / No|
+| :white_check_mark: |Supported / Yes|
+| :one: | Returns latest measurement|
+| :1234: | Returns all measurements|
+| :white_check_mark::wastebasket: |Supported and removes all locally stored measurements|
+
+## Specifications
+
+- Blood Pressure Service: https://www.bluetooth.com/specifications/specs/blood-pressure-service-1-1-1/
+- Assigned Numbers (f.e. service & characteristic UUID's): https://www.bluetooth.com/specifications/assigned-numbers/
+- GATT Specification Supplement (f.e. data structures): https://www.bluetooth.com/specifications/gss/
+- Current Time Service: https://www.bluetooth.com/specifications/specs/current-time-service-1-1/

app/lib/config.dart

@@ -0,0 +1,10 @@
+import 'dart:io';
+
+/// Whether bluetooth is supported on this platform by this app
+final isPlatformSupportedBluetooth = Platform.isAndroid || Platform.isIOS || Platform.isMacOS || Platform.isLinux;
+
+/// Whether we are running in a test environment
+final isTestingEnvironment = Platform.environment['FLUTTER_TEST'] == 'true';
+
+/// Whether the value graph should be shown as home screen in landscape mode
+final showValueGraphAsHomeScreenInLandscapeMode = isTestingEnvironment || !Platform.isLinux;

app/lib/data_util/entry_context.dart

@@ -55,7 +55,7 @@ extension EntryUtils on BuildContext {
         }
       }
     } on ProviderNotFoundException {
-      Log.err('createEntry($initial) was called from a context without Provider.');
+      log.severe('[extension.EntryUtils] createEntry($initial) was called from a context without Provider.');
     } catch (e, stack) {
       await ErrorReporting.reportCriticalError('Error opening add measurement dialoge', '$e\n$stack',);
     }
@@ -93,7 +93,7 @@ extension EntryUtils on BuildContext {
         ),);
       }
     } on ProviderNotFoundException {
-      Log.err('deleteEntry($entry) was called from a context without Provider.');
+      log.severe('[extension.EntryUtils] deleteEntry($entry) was called from a context without Provider.');
     }
   }
 }

app/lib/features/bluetooth/backend/bluetooth_backend.dart

@@ -0,0 +1,6 @@
+/// Utility import that only exposes the bluetooth backend services that should be used.
+library;
+
+export 'package:blood_pressure_app/features/bluetooth/backend/bluetooth_device.dart' show BluetoothDevice;
+export 'package:blood_pressure_app/features/bluetooth/backend/bluetooth_manager.dart' show BluetoothManager;
+export 'package:blood_pressure_app/features/bluetooth/backend/bluetooth_state.dart' show BluetoothAdapterState;

app/lib/features/bluetooth/backend/bluetooth_connection.dart

@@ -0,0 +1,11 @@
+
+
+
+/// State of the bluetooth connection of a device
+enum BluetoothConnectionState {
+  /// Device is connected
+  connected,
+  /// Device is disconnect
+  disconnected;
+}
+

app/lib/features/bluetooth/backend/bluetooth_device.dart

@@ -0,0 +1,287 @@
+
+import 'dart:async';
+
+import 'package:blood_pressure_app/features/bluetooth/backend/bluetooth_connection.dart';
+import 'package:blood_pressure_app/features/bluetooth/backend/bluetooth_manager.dart';
+import 'package:blood_pressure_app/features/bluetooth/backend/bluetooth_service.dart';
+import 'package:blood_pressure_app/logging.dart';
+import 'package:collection/collection.dart';
+import 'package:flutter/foundation.dart';
+
+/// Wrapper class for bluetooth implementations to generically expose required functionality
+abstract class BluetoothDevice<
+  BM extends BluetoothManager,
+  BS extends BluetoothService,
+  BC extends BluetoothCharacteristic,
+  BackendDevice
+> with TypeLogger {
+  /// Create a new BluetoothLowEnergyDevice
+  ///
+  /// [manager] Manager the device belongs to
+  /// [source] Device implementation of the current backend
+  BluetoothDevice(this.manager, this.source) {
+    logger.finer('init device: $this');
+  }
+
+  /// BluetoothManager this device belongs to
+  final BM manager;
+
+  /// Original source device as returned by the backend
+  final BackendDevice source;
+
+  /// (Unique?) id of the device
+  String get deviceId;
+
+  /// Name of the device
+  String get name;
+
+  /// Memoized service list for the device
+  List<BS>? _services;
+
+  bool _isConnected = false;
+  StreamSubscription<BluetoothConnectionState>? _connectionListener;
+
+  /// Whether the device is connected
+  bool get isConnected => _isConnected;
+
+  /// Stream to listen to for connection state changes after connecting to a device
+  Stream<BluetoothConnectionState> get connectionStream;
+
+  /// Backend implementation to connect to the device
+  Future<void> backendConnect();
+  /// Backend implementation to disconnect to the device
+  Future<void> backendDisconnect();
+
+  /// Require backends to implement a dispose method to cleanup any resources
+  Future<void> dispose();
+
+  /// Array of disconnect callbacks
+  ///
+  /// Disconnect callbacks are processed in reverse order, i.e. the latest added callback is executed as first. Callbacks
+  /// can return true to indicate they have fully handled the disconnect. This will then also stop executing any remaining
+  /// callbacks.
+  final List<bool Function()> disconnectCallbacks = [];
+
+  /// Connect to the device
+  ///
+  /// Always call disconnect when ready after calling connect
+  Future<bool> connect({ VoidCallback? onConnect, bool Function()? onDisconnect, ValueSetter<Object>? onError, int maxTries = 5 }) {
+    final completer = Completer<bool>();
+    logger.finer('connect: Init');
+
+    if (onDisconnect != null) {
+      disconnectCallbacks.add(onDisconnect);
+    }
+
+    _connectionListener?.cancel();
+    _connectionListener = connectionStream.listen((BluetoothConnectionState state) {
+      logger.finest('connectionStream.listen[isConnected: $_isConnected]: $state');
+
+      switch (state) {
+        case BluetoothConnectionState.connected:
+          onConnect?.call();
+          if (!completer.isCompleted) completer.complete(true);
+          _isConnected = true;
+          return;
+        case BluetoothConnectionState.disconnected:
+          for (final fn in disconnectCallbacks.reversed) {
+            if (fn()) {
+              // ignore other disconnect callbacks
+              break;
+            }
+          }
+
+          disconnectCallbacks.clear();
+          if (!completer.isCompleted) completer.complete(false);
+          _isConnected = false;
+      }
+    }, onError: onError);
+
+    backendConnect();
+    return completer.future.then((res) {
+      logger.finer('connect: completer.resolved($res)');
+      return res;
+    });
+  }
+
+  /// Disconnect & dispose the device
+  ///
+  /// Always call [disconnect] after calling [connect] to ensure all resources are disposed
+  Future<bool> disconnect() async {
+    await _connectionListener?.cancel();
+    await backendDisconnect();
+    await dispose();
+    return true;
+  }
+
+  /// Discover all available services on the device
+  ///
+  /// It's recommended to use [getServices] instead
+  Future<List<BS>?> discoverServices();
+
+  /// Return all available services for this device
+  ///
+  /// Difference with [discoverServices] is that [getServices] memoizes the results
+  Future<List<BS>?> getServices() async {
+    final logServices = _services == null; // only log services on the first call
+    _services ??= await discoverServices();
+    if (_services == null) {
+      logger.finer('Failed to discoverServices on: $this');
+    }
+
+    if (logServices) {
+      final services = _services ?? [];
+      for (final service in services) {
+        logger.finest('$service');
+        if (service.characteristics.isEmpty) {
+            logger.finest('  [no characteristics]');
+        }
+        for (final characteristic in service.characteristics) {
+            logger.finest('  $characteristic');
+        }
+      }
+    }
+
+    return _services;
+  }
+
+  /// Returns the service with requested [uuid] or null if requested service is not available
+  Future<BS?> getServiceByUuid(BluetoothUuid uuid) async {
+    final services = await getServices();
+    return services?.firstWhereOrNull((service) => service.uuid == uuid);
+  }
+
+  /// Retrieves the value of [characteristic] from the device and calls [onValue] for all received values
+  /// 
+  /// This method provides a generic implementation for async reading of data, regardless whether the
+  /// characteristic can be read directly or through a notification or indication. In case the value
+  /// is being read using an indication, then the [onValue] callback receives a second argument [complete] with
+  /// which you can stop reading the data.
+  ///
+  /// Note that a [characteristic] could have multiple values, so [onValue] can be called more then once.
+  /// TODO: implement reading values for characteristics with [canNotify]
+  Future<bool> getCharacteristicValue(BC characteristic, void Function(Uint8List value, [void Function(bool success)? complete]) onValue);
+
+  @override
+  String toString() => 'BluetoothDevice{name: $name, deviceId: $deviceId}';
+
+  @override
+  bool operator == (Object other) {
+    if (other is BluetoothDevice) {
+      return hashCode == other.hashCode;
+    }
+
+    return false;
+  }
+
+  @override
+  int get hashCode => Object.hash(deviceId, name);
+}
+
+/// Generic logic to implement an indication stream to read characteristic values
+mixin CharacteristicValueListener<
+  BM extends BluetoothManager,
+  BS extends BluetoothService,
+  BC extends BluetoothCharacteristic,
+  BackendDevice
+> on BluetoothDevice<BM, BS, BC, BackendDevice> {
+  /// List of read characteristic completers, used for cleanup on device disconnect
+  final List<Completer<bool>> _readCharacteristicCompleters = [];
+  /// List of read characteristic subscriptions, used for cleanup on device disconnect
+  final List<StreamSubscription<Uint8List?>> _readCharacteristicListeners = [];
+
+  /// Dispose of all resources used to read characteristics
+  ///
+  /// Internal method, should not be used by users
+  @protected
+  Future<void> disposeCharacteristics() async {
+    for (final completer in _readCharacteristicCompleters) {
+      // completing the completer also cancels the listener
+      completer.complete(false);
+    }
+
+    _readCharacteristicCompleters.clear();
+    _readCharacteristicListeners.clear();
+  }
+
+  /// Trigger notifications or indications for the [characteristic]
+  @protected
+  Future<bool> triggerCharacteristicValue(BC characteristic, [bool state = true]);
+
+  /// Read characteristic values from a stream
+  ///
+  /// It's not recommended to use this method directly, use [BluetoothDevice.getCharacteristicValue] instead
+  @protected
+  Future<bool> listenCharacteristicValue(
+    BC characteristic,
+    Stream<Uint8List?> characteristicValueStream,
+    void Function(Uint8List value, [void Function(bool success)? complete]) onValue
+  ) async {
+    if (!characteristic.canIndicate) {
+      return false;
+    }
+
+    final completer = Completer<bool>();
+    bool receivedSomeData = false;
+
+    bool disconnectCallback() {
+      logger.finer('listenCharacteristicValue(receivedSomeData: $receivedSomeData): onDisconnect called');
+      if (!receivedSomeData) {
+        return false;
+      }
+
+      completer.complete(true);
+      return true;
+    }
+
+    disconnectCallbacks.add(disconnectCallback);
+
+    final listener = characteristicValueStream.listen((value) {
+      if (value == null) {
+        // ignore null values
+        return;
+      }
+
+      logger.finer('listenCharacteristicValue[${value.length}] $value');
+
+      receivedSomeData = true;
+      onValue(value, completer.complete);
+    },
+      cancelOnError: true,
+      onDone: () {
+        logger.finer('listenCharacteristicValue: onDone called');
+        completer.complete(receivedSomeData);
+      },
+      onError: (Object err) {
+        logger.shout('listenCharacteristicValue: Error while reading characteristic', err);
+        completer.complete(false);
+      }
+    );
+
+    // track completer & listener so we can clean them up
+    // when the device unexpectedly disconnects (ie before
+    // any data has been received yet)
+    _readCharacteristicCompleters.add(completer);
+    _readCharacteristicListeners.add(listener);
+
+    final bool triggerSuccess = await triggerCharacteristicValue(characteristic);
+    if (!triggerSuccess) {
+      logger.warning('listenCharacteristicValue: triggerCharacteristicValue returned $triggerSuccess');
+    }
+
+    return completer.future.then((res) {
+      // Ensure listener is always cancelled when completer resolves
+      listener.cancel().then((_) => _readCharacteristicListeners.remove(listener));
+
+      // Remove stored completer reference
+      _readCharacteristicCompleters.remove(completer);
+
+      // Remove disconnect callback in case the connection was not automatically disconnected
+      if (disconnectCallbacks.remove(disconnectCallback)) {
+        logger.finer('listenCharacteristicValue: device was not automatically disconnected after completer finished, removing disconnect callback');
+      }
+
+      return res;
+    });
+  }
+}