Merge pull request #362 from OpenStrap/feat/coros-sensor-adapter

add coros sports watch support

Author: abdulsaheel

lib/ble/adapters/_registry.dart

@@ -139,6 +139,24 @@ const String kOuraCommandChar = '98ed0002-a541-11e4-b6a0-0002a5d5c51b';
 /// event share this one characteristic — there is no separate data pipe.
 const String kOuraNotifyChar = '98ed0003-a541-11e4-b6a0-0002a5d5c51b';
 
+/// One of the Nordic-UART-shaped 128-bit services a Coros watch exposes
+/// alongside the standard SIG services below — used here only as the scan
+/// filter, since a bare `0000180d` (heart rate) would collide with
+/// [kBleHrs] and get shadowed by it (that entry is matched first). NOT
+/// independently confirmed against a real advertisement payload (post-connect
+/// service enumeration is documented; the advertised UUID list is not) — see
+/// `coros.dart`'s own header before trusting this against real hardware.
+const String kCorosService = '6e400001-b5a3-f393-e0a9-77656c6f6f70';
+
+/// Standard Battery Service characteristic, read+notify, one byte 0-100.
+const String kBatteryLevelUuid = '00002a19-0000-1000-8000-00805f9b34fb';
+
+/// Standard Device Information Service characteristics — read-only UTF-8
+/// strings, no notify property.
+const String kModelNumberUuid = '00002a24-0000-1000-8000-00805f9b34fb';
+const String kSerialNumberUuid = '00002a25-0000-1000-8000-00805f9b34fb';
+const String kFirmwareRevisionUuid = '00002a26-0000-1000-8000-00805f9b34fb';
+
 /// Garmin's Multi-Link service — one characteristic pair carries every
 /// logical service (GFDI, the numbered real-time streams) this device family
 /// speaks, routed by a handle byte. See `protocol`'s `garmin.dart`.
@@ -788,6 +806,35 @@ const BandEntry kOura = BandEntry.notify(
   timeAnchor: TimeAnchor.arrival,
 );
 
+/// A Coros sports watch (Pace/Apex/Vertix series): every standard GATT
+/// service answers a plain connect, no pairing or bonding enforced.
+///
+/// NOT framed: no envelope, no command channel, no offload — see the header
+/// note on why activity/sleep/step history stays out of scope entirely.
+///
+/// `characteristics` IS BATTERY ALONE, deliberately. The Bluetooth SIG's
+/// Device Information Service marks model/serial/firmware as OPTIONAL —
+/// gating the connect on any of them is how a real watch that simply omits
+/// one string fails `missingCharacteristics` and never connects at all.
+/// `CorosAdapter._readString` already answers null for a characteristic that
+/// is not there; the honest gate is the one characteristic every watch in
+/// scope should answer. Heart rate is read via [kHeartRateMeasurementUuid]
+/// directly in `coros.dart` and is equally NOT required here, for the same
+/// reason: a watch that answers battery and identity but not heart rate
+/// should still connect.
+///
+/// EXPERIMENTAL, and it stays that way: nobody on this project owns one, so
+/// not a byte of this path has met hardware (ASSUMPTIONS R6). `signals` is
+/// `const {}`-equivalent territory for anything but the generic HR parse —
+/// `kDerivableSources` stays empty regardless, same as every other band here.
+const BandEntry kCoros = BandEntry.notify(
+  id: 'coros',
+  label: 'Coros watch',
+  service: kCorosService,
+  characteristics: <String>[kBatteryLevelUuid],
+  timeAnchor: TimeAnchor.arrival,
+);
+
 /// A Garmin sports watch (GFDI v2), paired through the watch's own
 /// Settings -> Sensors & Accessories -> Phone -> Pair Phone menu.
 ///
@@ -1425,6 +1472,7 @@ const List<BandEntry> kBandRegistry = <BandEntry>[
   kWhoopGen5,
   kBleHrs,
   kOura,
+  kCoros,
   kUltrahuman,
   kWithingsSteelHr,
   kMiBand234,
@@ -1511,6 +1559,10 @@ const Map<String, Map<InputSignal, Duration>> kAdapterSignals =
     InputSignal.rrIntervals: Duration(seconds: 1),
   },
   'oura': <InputSignal, Duration>{},
+  'coros': {
+    InputSignal.hrSparse: Duration(seconds: 1),
+    InputSignal.rrIntervals: Duration(seconds: 1),
+  },
   'ultrahuman': <InputSignal, Duration>{},
   'withings_steel_hr': <InputSignal, Duration>{},
   'miband234': <InputSignal, Duration>{},

lib/ble/adapters/adapter.dart

@@ -76,8 +76,15 @@ abstract class BandLink {
   /// The whole surface used to be `notify`/`write`/`log`, and every band so
   /// far only ever needed to be WRITTEN to or NOTIFIED by. RingConn's auth
   /// needs one plain GATT read (the standard System ID characteristic, to
-  /// recover its own BLE MAC) that no framed band and no notify-only sensor
-  /// before it required — see `ringconn.dart`.
+  /// recover its own BLE MAC), and Coros's status pull needs several more
+  /// (battery, model, serial, firmware) — the first two bands that needed a
+  /// one-shot read where no framed band and no notify-only sensor before them
+  /// required one. See `ringconn.dart` and `coros.dart`.
+  ///
+  /// For a characteristic with no notify property (Device Information
+  /// Service's read-only strings, say) this is the only way to reach it —
+  /// [notify] stays the right call for anything that can push updates on its
+  /// own.
   Future<List<int>?> read(String characteristicUuid);
 
   /// Write with response, which is also what triggers bonding. Returns whether

lib/ble/adapters/coros.dart

@@ -0,0 +1,97 @@
+// A Coros sports watch (Pace/Apex/Vertix series) as a [BandAdapter]: a
+// one-shot status pull (battery, model, serial, firmware) at connect, then
+// the same generic 0x2A37 heart-rate parse [BleHrsAdapter] already has.
+//
+// SCOPE IS DELIBERATELY NARROW. Every standard SIG service on this watch
+// answers a plain connect with no pairing or bonding enforced — battery,
+// device information and heart rate are all documented, unencrypted GATT.
+// Recorded activity, sleep and step history ride a completely undocumented
+// proprietary channel with no public frame spec anywhere; decoding it would
+// mean inventing a physiological data format from nothing, which is exactly
+// what this project refuses to do. That channel is never touched here.
+//
+// NOTHING HERE HAS MET HARDWARE. Nobody on this project owns one, so ships
+// EXPERIMENTAL (ASSUMPTIONS R6): `signals` covers only the generic HR parse,
+// and `coros` stays absent from `kDerivableSources` like every other band —
+// see `_registry.dart`'s `kCoros` doc on the one real unknown (the exact
+// advertised service UUID) that still needs a real device to close.
+
+import 'dart:convert';
+
+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 CorosAdapter extends BandAdapter {
+  const CorosAdapter();
+
+  @override
+  BandEntry get entry => kCoros;
+
+  /// The generic HR parse only. Nothing else on this watch is decoded —
+  /// battery and device identity are [BandNote]s, not a physiological signal.
+  @override
+  Map<InputSignal, Duration> get signals => const {
+        InputSignal.hrSparse: Duration(seconds: 1),
+        InputSignal.rrIntervals: Duration(seconds: 1),
+      };
+
+  @override
+  Stream<BandEvent> run(BandLink link) async* {
+    // One-shot, best-effort: a watch that answers battery and identity but
+    // not heart rate (or the reverse) still gets whatever it does answer —
+    // see `kCoros`'s own doc on why none of this is required to connect.
+    final battery = await link.read(kBatteryLevelUuid);
+    if (battery != null && battery.isNotEmpty) {
+      yield BandNote('battery', battery[0]);
+    }
+    final model = await _readString(link, kModelNumberUuid);
+    if (model != null) yield BandNote('model', model);
+    final serial = await _readString(link, kSerialNumberUuid);
+    if (serial != null) yield BandNote('serial', serial);
+    final firmware = await _readString(link, kFirmwareRevisionUuid);
+    if (firmware != null) yield BandNote('firmware', firmware);
+
+    // No handshake for HR itself — same floor as `BleHrsAdapter`: one
+    // subscription, no clock, no INIT.
+    await for (final (atSec, value) in link.notify(kHeartRateMeasurementUuid)) {
+      final s = parseHeartRateMeasurement(value);
+      if (s == null) continue;
+      // The sensor's own "no skin contact" is a REFUSAL, not a low reading —
+      // see `ble_hrs.dart`'s identical guard.
+      if (s.contact == false) continue;
+      yield SampleBatch(
+        [
+          NeutralSample(
+            // ARRIVAL TIME, NOT BEAT TIME — see `ble_hrs.dart`'s doc on why.
+            anchor: TimeAnchor.arrival,
+            tsEpoch: atSec,
+            hr: s.hr,
+            rrMs: s.rrMs,
+            vendor: s.contact == null ? const {} : {'contact': s.contact},
+          ),
+        ],
+        ephemeral: false,
+      );
+    }
+    // No OffloadCheckpoint, ever. This watch's recorded history is never
+    // requested — see the header note — so there is nothing to tell it to
+    // forget.
+  }
+
+  /// A read-only Device Information string, or null for a missing
+  /// characteristic, an empty reply or one that decodes to nothing.
+  Future<String?> _readString(BandLink link, String uuid) async {
+    final bytes = await link.read(uuid);
+    if (bytes == null || bytes.isEmpty) return null;
+    final s = utf8.decode(bytes, allowMalformed: true).trim();
+    return s.isEmpty ? null : s;
+  }
+}
+
+/// The single instance. Const, so it costs nothing to reference.
+const CorosAdapter kCorosAdapter = CorosAdapter();

lib/ble/adapters/gatt_link.dart

@@ -95,6 +95,18 @@ class GattBandLink implements BandLink {
   static const Duration _notifyTimeout = Duration(seconds: 15);
   static const Duration _writeTimeout = Duration(seconds: 8);
 
+  /// [read]'s own bound — deliberately shorter than [_notifyTimeout]. A
+  /// one-shot status pull (Coros's battery/device-info reads) can run several
+  /// of these BACK TO BACK before a session's bounded window ever reaches the
+  /// notify phase; at 15s each, four sequential reads could burn a full
+  /// minute on one unresponsive characteristic before the caller's own
+  /// session timeout even has a chance to matter. 2s is still generous for a
+  /// live GATT round trip, and it is what lets a caller doing four of these
+  /// (Coros's status pull) size its own session window with real seconds left
+  /// over for whatever comes after the reads, even in the fully-unresponsive
+  /// worst case.
+  static const Duration _readTimeout = Duration(seconds: 2);
+
   /// One write in flight at a time — the same [WriteChain] `BleEngine._write`
   /// runs on, one instance per link. Not shared with the engine's: two
   /// peripherals queueing behind each other is exactly what the per-remoteId
@@ -195,10 +207,15 @@ class GattBandLink implements BandLink {
       return null;
     }
     try {
-      return await c.read().timeout(_notifyTimeout);
-    } on TimeoutException {
-      log('read timeout: no GATT response in ${_notifyTimeout.inSeconds}s.');
-      return null;
+      // The timeout goes INTO the call, not wrapped around it. flutter_blue_plus
+      // serialises every GATT operation behind one global mutex and only
+      // releases it when the operation's OWN future settles — an outer
+      // `Future.timeout` does not cancel that future, so a wrapped read still
+      // held the mutex (and the platform channel) for its internal default of
+      // 15s regardless of how quickly this method gave up on it, and every
+      // other BLE op on this phone — including the primary band's — queues
+      // behind that same mutex.
+      return await c.read(timeout: _readTimeout.inSeconds);
     } catch (e) {
       log('read error: $e');
       return null;