Merge pull request #342 from OpenStrap/feat/polar-pmd

polar pmd: pair + stream ppi from a verity sense or oh1

Author: abdulsaheel

lib/ble/adapters/_registry.dart

@@ -53,6 +53,18 @@ import 'signals.dart';
 const String kHeartRateServiceUuid = '0000180d-0000-1000-8000-00805f9b34fb';
 const String kHeartRateMeasurementUuid = '00002a37-0000-1000-8000-00805f9b34fb';
 
+/// A Polar optical sensor's PMD (measurement data) service. Plain GATT — no
+/// encryption, no key exchange, no bonding requirement at this layer.
+const String kPolarPmdService = 'fb005c80-02e7-f387-1cad-8acd2d8df0c8';
+
+/// Write-with-response, indicate. Every PMD command goes here; its indicate
+/// reply carries the command's outcome.
+const String kPolarPmdControlChar = 'fb005c81-02e7-f387-1cad-8acd2d8df0c8';
+
+/// Notify. Every measurement stream this service can carry shares this one
+/// data characteristic — see `polar_pmd.dart` (adapter) for why only the PPI
+/// stream is decoded.
+const String kPolarPmdDataChar = 'fb005c82-02e7-f387-1cad-8acd2d8df0c8';
 /// A generic white-label smart ring's GATT service ("R11M"/"R10M", also sold
 /// as "TK5") — NOT the Colmi R11/R12, a different, unrelated product on a
 /// different protocol.
@@ -792,6 +804,29 @@ const BandEntry kBleHrs = BandEntry.notify(
   timeAnchor: TimeAnchor.arrival,
 );
 
+/// A Polar optical sensor (Verity Sense, OH1) speaking the PMD service, PPI
+/// stream only.
+///
+/// Plain unencrypted GATT — a control-point write plus a data notify, no
+/// bonding requirement at this layer, same shape as [kBleHrs] with one
+/// addition: streaming has to be switched on with a control-point write
+/// before the data characteristic says anything, and the adapter is what does
+/// that (see `polar_pmd.dart`).
+///
+/// EXPERIMENTAL and it stays that way: nobody on this project owns one, so not
+/// a byte of this path has met hardware (ASSUMPTIONS R6). It pairs, connects,
+/// and streams decoded beats; `kDerivableSources` stays empty until someone
+/// has actually held one.
+const BandEntry kPolarPmd = BandEntry.notify(
+  id: 'polar_pmd',
+  label: 'Polar sensor',
+  service: kPolarPmdService,
+  characteristics: <String>[kPolarPmdControlChar, kPolarPmdDataChar],
+  // PPI carries beat-to-beat durations and no clock of its own. See
+  // [TimeAnchor].
+  timeAnchor: TimeAnchor.arrival,
+);
+
 /// The Oura ring, a fetch-by-cursor band with a challenge-response handshake.
 ///
 /// NOT framed, and the three fields a framed entry carries would each be wrong
@@ -1506,6 +1541,7 @@ const List<BandEntry> kBandRegistry = <BandEntry>[
   kWhoopGen5,
   kBleHrs,
   kOura,
+  kPolarPmd,
   kCoros,
   kUltrahuman,
   kWithingsSteelHr,
@@ -1594,6 +1630,10 @@ const Map<String, Map<InputSignal, Duration>> kAdapterSignals =
     InputSignal.rrIntervals: Duration(seconds: 1),
   },
   'oura': <InputSignal, Duration>{},
+  'polar_pmd': {
+    InputSignal.hrSparse: Duration(seconds: 1),
+    InputSignal.rrIntervals: Duration(seconds: 1),
+  },
   'ring11m': <InputSignal, Duration>{},
   'coros': {
     InputSignal.hrSparse: Duration(seconds: 1),

lib/ble/adapters/adapter.dart

@@ -366,6 +366,18 @@ class ReplayBandLink implements BandLink {
 
   /// End every channel, which ends `run()`. Await the run subscription's
   /// `done` after this rather than guessing at a delay.
+  ///
+  /// PLAIN AND UNCONDITIONAL, on purpose — a `hasListener`-gated version (skip
+  /// the await, fire-and-forget `close()` on a channel with no listener yet)
+  /// was tried here and reverted: it reproducibly hung `HrsLink.ingestForTest`
+  /// teardown (`test/pair_sensor_test.dart`'s disarm case), bisected down to
+  /// this exact conditional — not the round-draining wrapper some earlier
+  /// version of this method also carried, which made no difference either
+  /// way. A single-subscription `StreamController.close()` is normally safe to
+  /// await even with no listener attached — it does not block waiting for one
+  /// to appear — so there was no real bug this gate was fixing; whatever
+  /// narrow race it was reasoning about did not hold up against the real
+  /// fixture. Keep this plain.
   Future<void> close() async {
     for (final c in _channels.values) {
       await c.close();

lib/ble/adapters/polar_pmd.dart

@@ -0,0 +1,136 @@
+// A Polar optical sensor's PMD (measurement data) service, PPI stream only —
+// as a [BandAdapter].
+//
+// NOTHING HERE HAS MET HARDWARE. Nobody on this project owns one and
+// `flutter_blue_plus` has no simulator path, so everything below is verified
+// by the wire layout in `polar_pmd.dart` (protocol), the fixtures in
+// `test/adapters/polar_pmd_adapter_test.dart` and the compiler. It ships
+// EXPERIMENTAL (ASSUMPTIONS R6) until the owner has held one and cross-
+// confirms it.
+//
+// PPI ONLY, deliberately. The PMD service also carries PPG, ECG, accelerometer
+// and gyroscope streams — none of them are decoded here, and each would need
+// its own settings negotiation and its own undecoded-raw-archive format for a
+// stream nothing consumes today. PPI needs no settings block, streams online
+// with one control-point write, and is fully decoded per-sample, so there is
+// nothing to archive raw — same reasoning `ble_hrs` already gives for skipping
+// `raw`.
+
+import 'dart:async';
+
+import 'package:openstrap_protocol/openstrap_protocol.dart';
+
+import '_registry.dart';
+import 'adapter.dart';
+import 'signals.dart';
+
+/// The adapter. Const, and it holds no session state — everything a session
+/// needs lives inside [run].
+class PolarPmdAdapter extends BandAdapter {
+  const PolarPmdAdapter();
+
+  @override
+  BandEntry get entry => kPolarPmd;
+
+  /// HR + beat interval — functionally the same pair `ble_hrs` declares, from
+  /// a different physical sensor. See that adapter's own doc on why a
+  /// declared-but-absent signal is worse than a missing one; this is the
+  /// honest statement of what a PPI stream physically carries.
+  @override
+  Map<InputSignal, Duration> get signals => const {
+        InputSignal.hrSparse: Duration(seconds: 1),
+        InputSignal.rrIntervals: Duration(seconds: 1),
+      };
+
+  /// How long to wait for the START command's control-point reply before
+  /// giving up on this session — short, because a sensor that never answers
+  /// it will never stream either.
+  static const Duration _startTimeout = Duration(seconds: 5);
+
+  @override
+  Stream<BandEvent> run(BandLink link) async* {
+    // The control-point reply this session is waiting for, resolved the
+    // moment a START reply for the PPI type arrives. A misbehaving sensor
+    // that never answers times out rather than hanging the session.
+    final started = Completer<bool>();
+    final controlSub = link.notify(kPolarPmdControlChar).listen((rec) {
+      final r = parsePolarPmdControlResponse(rec.$2);
+      if (r != null &&
+          r.reqOpcode == kPolarPmdOpRequestMeasurementStart &&
+          r.measType == kPolarPmdMeasTypePpi &&
+          !started.isCompleted) {
+        started.complete(r.ok);
+      }
+    });
+    // SUBSCRIBED NOW, READ LATER. The sensor is free to start streaming the
+    // moment the START write lands — before this session has even seen its
+    // control-point ack — so the data characteristic has to be listened to
+    // (and its notifications therefore buffered) from the same instant as
+    // the control characteristic, not only once the ack arrives. A single-
+    // subscription controller queues everything `.add`ed before `.stream`
+    // gets its listener, which is what makes the two-step
+    // subscribe-then-consume below lose nothing. Same shape `oura.dart`'s
+    // `_Inbox` exists for; smaller because this stream needs no "next with
+    // timeout", just a buffered pass-through.
+    final dataEvents = StreamController<(int, List<int>)>();
+    final dataSub = link.notify(kPolarPmdDataChar).listen(
+          dataEvents.add,
+          onDone: dataEvents.close,
+          onError: dataEvents.addError,
+        );
+    try {
+      if (!await link.write(kPolarPmdControlChar, polarPmdStartPpi())) {
+        link.log('polar_pmd: START write refused; ending the session.');
+        return;
+      }
+      final ok = await started.future
+          .timeout(_startTimeout, onTimeout: () => false);
+      if (!ok) {
+        link.log('polar_pmd: PPI start was not confirmed; ending the '
+            'session.');
+        return;
+      }
+      await for (final (atSec, value) in dataEvents.stream) {
+        final samples = parsePolarPmdPpiFrame(value);
+        if (samples == null) continue;
+        final neutrals = [
+          for (final s in samples)
+            // hr == 0 is the sensor's own "no valid beat this record" — a
+            // refusal, not a low reading. Storing it would put a fabricated
+            // zero into a heart-rate series, the same rule `ble_hrs` applies
+            // to a strap reporting no skin contact.
+            if (s.hr != 0)
+              NeutralSample(
+                anchor: TimeAnchor.arrival,
+                tsEpoch: atSec,
+                hr: s.hr,
+                rrMs: [s.ppiMs],
+                vendor: {
+                  'blocker': s.blocker,
+                  // Raw bits, under their own name — their real-world
+                  // polarity is not independently confirmed against
+                  // hardware, so nothing here gates on them (see
+                  // `PolarPpiSample.skinContactBits`'s own doc).
+                  'skin_contact': s.skinContactBits,
+                  'error_ms': s.errorEstimateMs,
+                },
+              ),
+        ];
+        if (neutrals.isNotEmpty) yield SampleBatch(neutrals);
+      }
+    } finally {
+      // Best-effort: a link that has already dropped simply refuses this
+      // write, which is fine — the sensor stops streaming on disconnect
+      // regardless.
+      unawaited(link.write(kPolarPmdControlChar, polarPmdStopPpi()));
+      await controlSub.cancel();
+      await dataSub.cancel();
+      unawaited(dataEvents.close());
+    }
+    // No OffloadCheckpoint, ever. Online streaming only — nothing is stored
+    // on the sensor for this stream, so there is nothing to tell it to forget.
+  }
+}
+
+/// The single instance. Const, so it costs nothing to reference.
+const PolarPmdAdapter kPolarPmdAdapter = PolarPmdAdapter();

lib/ble/hrs_link.dart

@@ -76,6 +76,7 @@ import 'miband_link.dart' show MiBand234Link;
 import 'o2ring_link.dart' show O2RingLink;
 import 'oura_link.dart' show OuraLink;
 import 'pebble_link.dart' show PebbleLink;
+import 'polar_pmd_link.dart' show PolarPmdLink;
 import 'qhybrid_link.dart' show QHybridLink;
 import 'ring11m_link.dart' show Ring11mLink;
 import 'ringconn_link.dart' show RingConnLink;
@@ -757,12 +758,17 @@ class HrsLink {
       return;
     }
     // Before the row goes, not after: a live session would keep writing rows
-    // under an id nothing can explain any more. GATED ON THE ROW BEING THE
-    // ARMED HRS SENSOR, not called unconditionally — this fallback used to run
-    // for ANY adapter without its own branch above, which would tear down a
-    // live chest-strap session while forgetting an unrelated device (e.g. a
-    // Lefun ring paired alongside one).
-    if (row?['adapter_id'] == kBleHrsAdapter.id) {
+    // under an id nothing can explain any more. Every live-session link
+    // capable of writing under this id gets disarmed, not just this class's
+    // own — a Polar row's live sensor is `PolarPmdLink`, not `instance`. GATED
+    // ON THE ROW BEING THE ARMED HRS SENSOR for the `instance` branch, not
+    // called unconditionally — this fallback used to run for ANY adapter
+    // without its own branch above, which would tear down a live chest-strap
+    // session while forgetting an unrelated device (e.g. a Lefun ring paired
+    // alongside one).
+    if (row?['adapter_id'] == kPolarPmd.id) {
+      await PolarPmdLink.instance.disarm();
+    } else if (row?['adapter_id'] == kBleHrsAdapter.id) {
       await instance.disarm();
     }
     await LocalDb.deleteDevice(id);