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

BLUETOOTH.md

@@ -0,0 +1,43 @@
+# 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
+
+- 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,18 @@
+import 'dart:io';
+import 'package:blood_pressure_app/logging.dart';
+
+/// Default name for global [log] instance (not used when printing messages atm)
+const defaultLoggerName = 'BloodPressureMonitor';
+
+/// Prefix used when printing log messages
+const loggerRecordPrefix = 'BPM';
+
+/// 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
+/// TODO: This functionality basically blocks the UI until the device is back into portrait mode, maybe best to implement this differently
+final showValueGraphAsHomeScreenInLandscapeMode = isTestingEnvironment || !Platform.isLinux;

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

@@ -0,0 +1,42 @@
+import 'dart:async';
+import 'package:blood_pressure_app/features/bluetooth/backend/bluetooth_low_energy/ble_manager.dart';
+import 'package:blood_pressure_app/features/bluetooth/backend/flutter_blue_plus/fbp_manager.dart';
+import 'package:blood_pressure_app/features/bluetooth/backend/flutter_blue_plus/flutter_blue_plus_mockable.dart';
+import 'package:blood_pressure_app/features/bluetooth/backend/mock/mock_manager.dart';
+import 'package:blood_pressure_app/logging.dart';
+import 'package:collection/collection.dart';
+import 'package:flutter/foundation.dart';
+
+part 'bluetooth_connection.dart';
+part 'bluetooth_device.dart';
+part 'bluetooth_discovery.dart';
+part 'bluetooth_manager.dart';
+part 'bluetooth_service.dart';
+part 'bluetooth_state.dart';
+part 'bluetooth_utils.dart';
+
+/// Supported bluetooth backend implementations
+///
+/// Enum values provide a [create] instance method to easily get a new backend instance
+enum BluetoothBackend {
+  /// Use the package 'bluetooth_low_energy' as backend manager
+  bluetoothLowEnergy,
+  /// Use the package 'flutter_blue_plus' as backend manager
+  flutterBluePlus,
+  /// Use a (partially) mocked backend manager.
+  /// Note that for full fledged testing it might be better to use flutter_blue_plus with a
+  /// custom [FlutterBluePlusMockable] instance
+  mock;
+
+  /// Create a bluetooth backend instance for the current enum value
+  BluetoothManager create() {
+    switch(this) {
+      case BluetoothBackend.bluetoothLowEnergy:
+        return BluetoothLowEnergyManager();
+      case BluetoothBackend.flutterBluePlus:
+        return FlutterBluePlusManager();
+      case BluetoothBackend.mock:
+        return MockBluetoothManager();
+    }
+  }
+}

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

@@ -0,0 +1,26 @@
+part of 'bluetooth_backend.dart';
+
+/// State of the bluetooth connection of a device
+enum BluetoothConnectionState {
+  /// Device is connected
+  connected,
+  /// Device is disconnect
+  disconnected;
+}
+
+/// Bluetooth connection state parser base class
+///
+/// This is a separate helper class as factory or static methods cannot be abstract,
+/// so even though this class only has one method it's useful to enforce the types
+abstract class BluetoothConnectionStateParser<BackendConnectionState> extends StreamDataParser<BackendConnectionState, BluetoothConnectionState> {}
+
+/// Transforms the backend's bluetooth adapter state stream to emit [BluetoothAdapterState]'s
+///
+/// Can normally be used directly, backends should only inject a customized [BluetoothAdapterStateParser]
+class BluetoothConnectionStateStreamTransformer<BackendConnectionState, BASP extends BluetoothConnectionStateParser<BackendConnectionState>>
+  extends StreamDataParserTransformer<BackendConnectionState, BluetoothConnectionState, BASP> {
+  /// Create a [BluetoothConnectionStateStreamTransformer] instance
+  ///
+  /// [stateParser] The [BluetoothConnectionStateParser] that provides the backend specific logic to convert [BackendConnectionState] to [BluetoothConnectionState]
+  BluetoothConnectionStateStreamTransformer({ required super.stateParser, super.sync, super.cancelOnError });
+}

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

@@ -0,0 +1,169 @@
+part of 'bluetooth_backend.dart';
+
+/// Wrapper class for bluetooth implementations to generically expose required functionality
+///
+/// This class can't be used directly, it should be implemented by a backend
+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
+  late final BM _manager;
+
+  /// Corresponding BluetoothManager
+  BM get manager => _manager;
+
+  /// Original source device as returned by the backend
+  late final BackendDevice _source;
+
+  /// Original source device as returned by the backend
+  BackendDevice get source => _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();
+
+  /// 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.
+  @protected
+  final List<bool Function(bool wasConnected)> disconnectCallbacks = [];
+
+  /// Connect to the device
+  ///
+  /// Always call disconnect when ready after calling connect
+  Future<bool> connect({ VoidCallback? onConnect, bool Function(bool wasConnected)? onDisconnect, ValueSetter<Object>? onError, int maxTries = 5 }) {
+    final completer = Completer<bool>();
+    int connectTry = 1;
+
+    logger.finer('connect: Init');
+
+    if (onDisconnect != null) {
+      disconnectCallbacks.add(onDisconnect);
+    }
+
+    /// Local helper util to only complete the completer when it's not completed yet
+    void doComplete(bool res) => !completer.isCompleted ? completer.complete(res) : null;
+
+    _connectionListener = connectionStream.listen((BluetoothConnectionState state) {
+      logger.finest('connectionStream.listen[isConnected: $_isConnected]: $state, connectTry: $connectTry');
+
+      switch (state) {
+        case BluetoothConnectionState.connected:
+          connectTry = 0; // reset try count
+
+          onConnect??();
+          doComplete(true);
+          _isConnected = true;
+          return;
+        case BluetoothConnectionState.disconnected:
+          final wasConnected = _isConnected;
+          // TODO: does this make even sense? I.e. can this listener be called with successive disconnected states?
+          if (!wasConnected && connectTry < maxTries) {
+            connectTry++;
+            backendConnect();
+            return;
+          }
+
+          for (final fn in disconnectCallbacks.reversed) {
+            if (fn(wasConnected)) {
+              // ignore other disconnect callbacks
+              break;
+            }
+          }
+
+          disconnectCallbacks.clear();
+          doComplete(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();
+    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 {
+    _services ??= await discoverServices();
+    if (_services == null) {
+      logger.finer('Failed to discoverServices on: $this');
+    }
+    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();
+    try {
+      return services?.firstWhere((service) => service.uuid == uuid);
+    } on StateError {
+      return null;
+    }
+  }
+
+  /// Retrieves the value of [characteristic] from the device, the value is added to [value]
+  /// 
+  /// Note that a [characteristic] could have multiple values, hency why [value] is a list of a list.
+  /// Also note that [value] is a function arg as the return value is an indication if the read was
+  /// succesful or not. This function could convert a listener to a Future and reading a characteristic
+  /// could return muliple value items. So value could contain data even though the read gave an error
+  /// indicating not all data had been read from the device.
+  Future<bool> getCharacteristicValueByUuid(BC characteristic, List<Uint8List> value);
+
+  @override
+  String toString() => 'BluetoothDevice{name: $name, deviceId: $deviceId}';
+}
+
+/// Bluetooth device parser base class
+///
+/// This is a separate helper class as factory or static methods cannot be abstract,
+/// so even though this class only has one method it's useful to enforce the types
+abstract class BluetoothDeviceParser<T> {
+  /// Method that converts the raw bluetooth device data to a [BluetoothDevice] instance
+  BluetoothDevice parse(T rawDevice, BluetoothManager manager);
+}