Stream heart rate from a strap or watch into the ride and the FIT file
A new HRM client in the BLE crate follows the crate's split: the 0x2A37 decoder is a pure function over bytes (u8/u16 formats, the three-state sensor-contact field, straps that append energy/RR data), and only the actor touches the radio. Anything exposing the standard Heart Rate Service works — a chest strap, or a Garmin watch with Broadcast Heart Rate on. A single-slot supervisor in the app owns the link, shaped like the trainer's and the controller's. It publishes bpm on a watch channel the session backend stamps onto each tick's telemetry — never over a heart rate FTMS itself reported, on the same authority rule as the Zwift cadence merge — and it clears the reading after eight silent seconds, so a strap taken off records nothing rather than a flatline of the last real value. From there the existing pipeline does the rest: ride screen tile, FIT records, avg/max in lap and session. The device list routes heart-rate rows to the supervisor, keeps the row alive while connected (a connected monitor stops advertising), and shows the live bpm as proof data is flowing — a connected-but-silent monitor otherwise looks exactly like a working one. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Claude Fable 5
@@ -0,0 +1,675 @@
|
||||
//! Heart rate monitor client: decoder and connection actor.
|
||||
//!
|
||||
//! Structurally a sibling of [`crate::click`]: one task owns the peripheral,
|
||||
//! callers hold a cheap handle and receive [`HeartRateEvent`]s on a broadcast
|
||||
//! channel. The wire format lives in this module too, as pure functions over
|
||||
//! bytes, because it is a single characteristic and does not earn a module of
|
||||
//! its own.
|
||||
//!
|
||||
//! ```text
|
||||
//! caller ◄──broadcast── HeartRateEvent ◄── actor ◄─notify── HRM / watch
|
||||
//! ```
|
||||
//!
|
||||
//! Works with anything that exposes the standard Heart Rate Service (`0x180D`)
|
||||
//! — a chest strap, or a sports watch with *Broadcast Heart Rate* switched on.
|
||||
//! A watch in broadcast mode accepts a single central, so connecting it here
|
||||
//! takes it away from any other app; that is a property of the watch, not of
|
||||
//! this client.
|
||||
//!
|
||||
//! Read-only in every sense: nothing is ever written to the device, so — like
|
||||
//! the Click and unlike the trainer — there is no safety sequence, only the
|
||||
//! SAF-9 obligation to actually close the link on the way out.
|
||||
|
||||
use std::future::Future;
|
||||
use std::time::Duration;
|
||||
|
||||
use btleplug::api::{Characteristic, Peripheral as _};
|
||||
use btleplug::platform::{Adapter, Peripheral};
|
||||
use futures::{Stream, StreamExt};
|
||||
use tokio::sync::{broadcast, mpsc, oneshot};
|
||||
|
||||
use crate::client::{Backoff, InFlight, DISCONNECT_TIMEOUT};
|
||||
use crate::error::FtmsError;
|
||||
use crate::indoor_bike_data::hex;
|
||||
use crate::scan::{self, DiscoveredDevice, ScanKind};
|
||||
use crate::uuids;
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Wire format (pure)
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// One decoded Heart Rate Measurement (`0x2A37`) notification.
|
||||
///
|
||||
/// Only what the app uses. The characteristic can also carry energy expended
|
||||
/// and RR intervals; both are skipped, not rejected — a device that sends them
|
||||
/// still decodes.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct HeartRateMeasurement {
|
||||
/// Beats per minute. `u16` because the flags allow it, though anything a
|
||||
/// human produces fits in a `u8`.
|
||||
pub bpm: u16,
|
||||
/// Skin contact, where the device reports the feature at all. `None` means
|
||||
/// "not supported", not "no contact" — the two must not be conflated, or
|
||||
/// every strap without the feature reads as fallen off.
|
||||
pub sensor_contact: Option<bool>,
|
||||
}
|
||||
|
||||
/// Why a Heart Rate Measurement frame would not decode.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
|
||||
pub enum HrDecodeError {
|
||||
#[error("empty heart rate measurement")]
|
||||
Empty,
|
||||
#[error("heart rate measurement of {len} bytes is too short for its flags (0x{flags:02x})")]
|
||||
TooShort { flags: u8, len: usize },
|
||||
}
|
||||
|
||||
/// Decode a Heart Rate Measurement (`0x2A37`) value.
|
||||
///
|
||||
/// Layout per the Bluetooth SIG GATT specification: a flags byte, then the
|
||||
/// heart rate as `u8` or `u16` little-endian depending on flags bit 0. Bits
|
||||
/// 1–2 describe sensor contact: bit 2 says the feature is supported, bit 1
|
||||
/// says contact is detected.
|
||||
pub fn decode_heart_rate(data: &[u8]) -> Result<HeartRateMeasurement, HrDecodeError> {
|
||||
let (&flags, rest) = data.split_first().ok_or(HrDecodeError::Empty)?;
|
||||
|
||||
let bpm = if flags & 0x01 == 0 {
|
||||
*rest.first().ok_or(HrDecodeError::TooShort {
|
||||
flags,
|
||||
len: data.len(),
|
||||
})? as u16
|
||||
} else {
|
||||
match rest {
|
||||
[lo, hi, ..] => u16::from_le_bytes([*lo, *hi]),
|
||||
_ => {
|
||||
return Err(HrDecodeError::TooShort {
|
||||
flags,
|
||||
len: data.len(),
|
||||
})
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
let sensor_contact = match flags & 0x06 {
|
||||
0x06 => Some(true),
|
||||
0x04 => Some(false),
|
||||
_ => None,
|
||||
};
|
||||
|
||||
Ok(HeartRateMeasurement {
|
||||
bpm,
|
||||
sensor_contact,
|
||||
})
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Selection and configuration
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// How to pick a heart rate monitor out of a scan.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum HrSelector {
|
||||
/// A specific device, by address — what the app uses, since the scan has
|
||||
/// already identified it. Matched without insisting on the advertisement:
|
||||
/// a device mid-connection may not be advertising its services.
|
||||
Address(String),
|
||||
/// Any peripheral advertising the Heart Rate Service (`0x180D`).
|
||||
Any,
|
||||
}
|
||||
|
||||
impl HrSelector {
|
||||
pub fn matches(&self, d: &DiscoveredDevice) -> bool {
|
||||
self.matches_parts(
|
||||
&d.address,
|
||||
d.services.contains(&uuids::HEART_RATE_SERVICE),
|
||||
&format!("{:?}", d.id),
|
||||
)
|
||||
}
|
||||
|
||||
/// The matching rule, factored out so it can be unit-tested without a
|
||||
/// `PeripheralId` (which only the platform backend can construct).
|
||||
pub(crate) fn matches_parts(
|
||||
&self,
|
||||
address: &str,
|
||||
advertises_hr: bool,
|
||||
id_debug: &str,
|
||||
) -> bool {
|
||||
match self {
|
||||
HrSelector::Address(a) => {
|
||||
address.eq_ignore_ascii_case(a)
|
||||
|| id_debug.to_lowercase().contains(&a.to_lowercase())
|
||||
}
|
||||
HrSelector::Any => advertises_hr,
|
||||
}
|
||||
}
|
||||
|
||||
/// Human-readable, for error messages the rider will actually read.
|
||||
pub fn describe(&self) -> String {
|
||||
match self {
|
||||
HrSelector::Address(a) => format!("heart rate monitor at {a}"),
|
||||
HrSelector::Any => "any heart rate monitor".to_string(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Tunables for [`HeartRateClient`].
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct HeartRateConfig {
|
||||
/// How long to look before giving up. A broadcasting device advertises
|
||||
/// continuously — unlike a Click — so this needs no extra patience.
|
||||
pub scan_timeout: Duration,
|
||||
pub backoff: Backoff,
|
||||
pub channel_capacity: usize,
|
||||
}
|
||||
|
||||
impl Default for HeartRateConfig {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
scan_timeout: Duration::from_secs(15),
|
||||
backoff: Backoff::default(),
|
||||
channel_capacity: 64,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Events and handle
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Everything the app learns from a heart rate monitor.
|
||||
#[derive(Debug, Clone, PartialEq)]
|
||||
pub enum HeartRateEvent {
|
||||
Connected {
|
||||
address: String,
|
||||
name: Option<String>,
|
||||
/// Read once at connect, where the device exposes `0x2A19` at all.
|
||||
battery_percent: Option<u8>,
|
||||
},
|
||||
/// The link dropped. The actor is retrying — this is not terminal.
|
||||
Disconnected,
|
||||
/// Reconnecting ran out of attempts and the actor has stopped (FR-1.11).
|
||||
/// Terminal: nothing further arrives on this stream.
|
||||
GaveUp { attempts: u32 },
|
||||
/// A decoded measurement.
|
||||
Measurement {
|
||||
bpm: u16,
|
||||
sensor_contact: Option<bool>,
|
||||
},
|
||||
}
|
||||
|
||||
enum Cmd {
|
||||
Shutdown { reply: oneshot::Sender<()> },
|
||||
}
|
||||
|
||||
/// Cheap, cloneable handle to a heart rate monitor session.
|
||||
#[derive(Clone)]
|
||||
pub struct HeartRateClient {
|
||||
cmd_tx: mpsc::Sender<Cmd>,
|
||||
events_tx: broadcast::Sender<HeartRateEvent>,
|
||||
address: String,
|
||||
name: Option<String>,
|
||||
battery_percent: Option<u8>,
|
||||
}
|
||||
|
||||
impl HeartRateClient {
|
||||
/// Carried on the handle rather than left to the event stream, because the
|
||||
/// first `Connected` is sent before the caller has had a chance to
|
||||
/// subscribe — same reasoning as [`crate::click::ClickClient::address`].
|
||||
pub fn address(&self) -> &str {
|
||||
&self.address
|
||||
}
|
||||
|
||||
pub fn name(&self) -> Option<&str> {
|
||||
self.name.as_deref()
|
||||
}
|
||||
|
||||
/// Battery level at connect time, where the device reported one.
|
||||
pub fn battery_percent(&self) -> Option<u8> {
|
||||
self.battery_percent
|
||||
}
|
||||
|
||||
/// Connect to a heart rate monitor and start streaming measurements.
|
||||
///
|
||||
/// Returns once the measurement characteristic is subscribed, so an `Ok`
|
||||
/// means data is genuinely on its way — not merely that a link exists.
|
||||
pub async fn connect(
|
||||
selector: HrSelector,
|
||||
config: HeartRateConfig,
|
||||
) -> Result<Self, FtmsError> {
|
||||
let adapter = scan::default_adapter().await?;
|
||||
Self::connect_with_adapter(adapter, selector, config).await
|
||||
}
|
||||
|
||||
/// As [`HeartRateClient::connect`], but abandoned as soon as `cancel`
|
||||
/// resolves. Returns `Ok(None)` when it was cancelled; any link the
|
||||
/// abandoned attempt had opened is closed before this returns (SAF-9,
|
||||
/// FR-1.10).
|
||||
pub async fn connect_cancellable(
|
||||
selector: HrSelector,
|
||||
config: HeartRateConfig,
|
||||
cancel: impl Future<Output = ()>,
|
||||
) -> Result<Option<Self>, FtmsError> {
|
||||
let in_flight = InFlight::default();
|
||||
let outcome = {
|
||||
let attempt = async {
|
||||
let adapter = scan::default_adapter().await?;
|
||||
Self::connect_on(adapter, selector, config, &in_flight).await
|
||||
};
|
||||
tokio::pin!(attempt, cancel);
|
||||
tokio::select! {
|
||||
result = &mut attempt => Some(result),
|
||||
() = &mut cancel => None,
|
||||
}
|
||||
};
|
||||
match outcome {
|
||||
Some(result) => result.map(Some),
|
||||
None => {
|
||||
tracing::info!("hr: connect attempt cancelled");
|
||||
in_flight.abandon().await;
|
||||
Ok(None)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// As [`HeartRateClient::connect`], but on a caller-supplied adapter.
|
||||
pub async fn connect_with_adapter(
|
||||
adapter: Adapter,
|
||||
selector: HrSelector,
|
||||
config: HeartRateConfig,
|
||||
) -> Result<Self, FtmsError> {
|
||||
Self::connect_on(adapter, selector, config, &InFlight::default()).await
|
||||
}
|
||||
|
||||
async fn connect_on(
|
||||
adapter: Adapter,
|
||||
selector: HrSelector,
|
||||
config: HeartRateConfig,
|
||||
in_flight: &InFlight,
|
||||
) -> Result<Self, FtmsError> {
|
||||
let (events_tx, _) = broadcast::channel(config.channel_capacity);
|
||||
let (cmd_tx, cmd_rx) = mpsc::channel(8);
|
||||
|
||||
let (session, notifications) =
|
||||
open_session(&adapter, &selector, &config, in_flight).await?;
|
||||
let (address, name, battery_percent) = (
|
||||
session.address.clone(),
|
||||
session.name.clone(),
|
||||
session.battery_percent,
|
||||
);
|
||||
// Sent for symmetry with a reconnect; the same facts ride out on the
|
||||
// handle below because nobody is subscribed yet.
|
||||
let _ = events_tx.send(HeartRateEvent::Connected {
|
||||
address: address.clone(),
|
||||
name: name.clone(),
|
||||
battery_percent,
|
||||
});
|
||||
|
||||
let actor = Actor {
|
||||
adapter,
|
||||
// Reconnect to *this* device, not to whatever HRM now answers
|
||||
// first — two straps in a household is not exotic.
|
||||
selector: if address.is_empty() {
|
||||
selector
|
||||
} else {
|
||||
HrSelector::Address(address.clone())
|
||||
},
|
||||
config,
|
||||
events_tx: events_tx.clone(),
|
||||
};
|
||||
tokio::spawn(actor.run(cmd_rx, session, Box::pin(notifications)));
|
||||
|
||||
Ok(Self {
|
||||
cmd_tx,
|
||||
events_tx,
|
||||
address,
|
||||
name,
|
||||
battery_percent,
|
||||
})
|
||||
}
|
||||
|
||||
/// Subscribe to events. Late subscribers see only what arrives after they
|
||||
/// subscribe.
|
||||
pub fn events(&self) -> broadcast::Receiver<HeartRateEvent> {
|
||||
self.events_tx.subscribe()
|
||||
}
|
||||
|
||||
/// Close the link, and wait for it to actually be closed (SAF-9).
|
||||
/// Idempotent — shutting down a stopped client is a no-op.
|
||||
pub async fn shutdown(&self) {
|
||||
let (reply, done) = oneshot::channel();
|
||||
if self.cmd_tx.send(Cmd::Shutdown { reply }).await.is_err() {
|
||||
// The actor is already gone; it tore the link down on its way out.
|
||||
return;
|
||||
}
|
||||
let _ = done.await;
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Session and actor
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/// Boxed so the initial connection and every reconnect share one type.
|
||||
type Notifications = std::pin::Pin<
|
||||
Box<dyn Stream<Item = btleplug::api::ValueNotification> + Send>,
|
||||
>;
|
||||
|
||||
struct Session {
|
||||
peripheral: Peripheral,
|
||||
address: String,
|
||||
name: Option<String>,
|
||||
battery_percent: Option<u8>,
|
||||
measurement: Characteristic,
|
||||
}
|
||||
|
||||
/// Find the device, connect and subscribe to Heart Rate Measurement.
|
||||
async fn open_session(
|
||||
adapter: &Adapter,
|
||||
selector: &HrSelector,
|
||||
config: &HeartRateConfig,
|
||||
in_flight: &InFlight,
|
||||
) -> Result<(Session, Notifications), FtmsError> {
|
||||
// Unfiltered: an address selector must match a device whatever it
|
||||
// advertises, and some backends ignore service filters anyway.
|
||||
let peripheral = scan::find_matching(
|
||||
adapter,
|
||||
ScanKind::All,
|
||||
config.scan_timeout,
|
||||
&selector.describe(),
|
||||
|d| selector.matches(d),
|
||||
)
|
||||
.await?;
|
||||
// Cancelling past this point would otherwise strand the link (FR-1.10).
|
||||
in_flight.hold(peripheral.clone());
|
||||
|
||||
match setup_session(peripheral.clone()).await {
|
||||
Ok(session) => {
|
||||
in_flight.released();
|
||||
Ok(session)
|
||||
}
|
||||
Err(e) => {
|
||||
// A failure after `connect()` leaves a live GATT link behind, and a
|
||||
// watch in broadcast mode accepts one central — held, it will not
|
||||
// advertise for the retry, so the retry loop would never succeed.
|
||||
tracing::debug!(error = %e, "hr: session setup failed; disconnecting");
|
||||
let _ = peripheral.disconnect().await;
|
||||
in_flight.released();
|
||||
Err(e)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
async fn setup_session(peripheral: Peripheral) -> Result<(Session, Notifications), FtmsError> {
|
||||
if !peripheral.is_connected().await.unwrap_or(false) {
|
||||
peripheral.connect().await?;
|
||||
}
|
||||
peripheral.discover_services().await?;
|
||||
|
||||
let chars = peripheral.characteristics();
|
||||
// Prefer the characteristic inside the Heart Rate Service, but take a
|
||||
// bare 0x2A37 anywhere — the same leniency the FTMS client extends.
|
||||
let measurement = chars
|
||||
.iter()
|
||||
.find(|c| {
|
||||
c.uuid == uuids::HEART_RATE_MEASUREMENT
|
||||
&& c.service_uuid == uuids::HEART_RATE_SERVICE
|
||||
})
|
||||
.or_else(|| chars.iter().find(|c| c.uuid == uuids::HEART_RATE_MEASUREMENT))
|
||||
.cloned()
|
||||
.ok_or(FtmsError::MissingCharacteristic(
|
||||
"Heart Rate Measurement (0x2A37)",
|
||||
))?;
|
||||
|
||||
let notifications = peripheral.notifications().await?;
|
||||
peripheral.subscribe(&measurement).await?;
|
||||
|
||||
// Best effort, once: straps report battery, watches in broadcast mode
|
||||
// usually do not. A failure here must not cost the session.
|
||||
let battery_percent = match chars.iter().find(|c| c.uuid == uuids::BATTERY_LEVEL) {
|
||||
Some(c) => peripheral
|
||||
.read(c)
|
||||
.await
|
||||
.ok()
|
||||
.and_then(|v| v.first().copied())
|
||||
.filter(|p| *p <= 100),
|
||||
None => None,
|
||||
};
|
||||
|
||||
let described = scan::describe(&peripheral).await;
|
||||
Ok((
|
||||
Session {
|
||||
address: described
|
||||
.as_ref()
|
||||
.map(|d| d.address.clone())
|
||||
.unwrap_or_default(),
|
||||
name: described.and_then(|d| d.name),
|
||||
battery_percent,
|
||||
peripheral,
|
||||
measurement,
|
||||
},
|
||||
Box::pin(notifications),
|
||||
))
|
||||
}
|
||||
|
||||
struct Actor {
|
||||
adapter: Adapter,
|
||||
selector: HrSelector,
|
||||
config: HeartRateConfig,
|
||||
events_tx: broadcast::Sender<HeartRateEvent>,
|
||||
}
|
||||
|
||||
impl Actor {
|
||||
async fn run(
|
||||
self,
|
||||
mut cmd_rx: mpsc::Receiver<Cmd>,
|
||||
mut current: Session,
|
||||
mut notifications: Notifications,
|
||||
) {
|
||||
let mut attempt = 0u32;
|
||||
|
||||
loop {
|
||||
let dropped = tokio::select! {
|
||||
cmd = cmd_rx.recv() => {
|
||||
match cmd {
|
||||
Some(Cmd::Shutdown { reply }) => {
|
||||
self.teardown(¤t).await;
|
||||
// Answered only once the link is genuinely closed
|
||||
// (SAF-9).
|
||||
let _ = reply.send(());
|
||||
return;
|
||||
}
|
||||
None => {
|
||||
self.teardown(¤t).await;
|
||||
return;
|
||||
}
|
||||
}
|
||||
}
|
||||
frame = notifications.next() => match frame {
|
||||
Some(n) => { self.handle(n.uuid, &n.value); false }
|
||||
// The stream ending is how btleplug reports a dropped link.
|
||||
None => true,
|
||||
},
|
||||
};
|
||||
|
||||
if !dropped {
|
||||
continue;
|
||||
}
|
||||
|
||||
tracing::warn!(
|
||||
selector = %self.selector.describe(),
|
||||
"hr: notification stream ended — link dropped"
|
||||
);
|
||||
let _ = self.events_tx.send(HeartRateEvent::Disconnected);
|
||||
|
||||
// FR-1.6: reconnect with backoff. A watch that left broadcast mode
|
||||
// or a strap taken off will simply not be found, which is normal.
|
||||
loop {
|
||||
if self.config.backoff.exhausted(attempt) {
|
||||
tracing::warn!("hr: giving up after {attempt} reconnect attempts");
|
||||
// Say so before going away (FR-1.11): a silent exit strands
|
||||
// the supervisor holding a handle whose actor is gone.
|
||||
let _ = self.events_tx.send(HeartRateEvent::GaveUp { attempts: attempt });
|
||||
return;
|
||||
}
|
||||
let delay = self.config.backoff.delay(attempt);
|
||||
attempt += 1;
|
||||
|
||||
// Both the backoff and the attempt stay answerable to shutdown
|
||||
// (FR-1.10, SAF-9) — an attempt runs for up to `scan_timeout`.
|
||||
let in_flight = InFlight::default();
|
||||
let outcome = {
|
||||
let attempting = async {
|
||||
tokio::time::sleep(delay).await;
|
||||
open_session(&self.adapter, &self.selector, &self.config, &in_flight)
|
||||
.await
|
||||
};
|
||||
tokio::pin!(attempting);
|
||||
tokio::select! {
|
||||
biased;
|
||||
cmd = cmd_rx.recv() => Err(cmd),
|
||||
result = &mut attempting => Ok(result),
|
||||
}
|
||||
};
|
||||
|
||||
let result = match outcome {
|
||||
Ok(result) => result,
|
||||
Err(cmd) => {
|
||||
in_flight.abandon().await;
|
||||
if let Some(Cmd::Shutdown { reply }) = cmd {
|
||||
let _ = reply.send(());
|
||||
}
|
||||
return;
|
||||
}
|
||||
};
|
||||
|
||||
match result {
|
||||
Ok((session, stream)) => {
|
||||
let _ = self.events_tx.send(HeartRateEvent::Connected {
|
||||
address: session.address.clone(),
|
||||
name: session.name.clone(),
|
||||
battery_percent: session.battery_percent,
|
||||
});
|
||||
current = session;
|
||||
notifications = stream;
|
||||
attempt = 0;
|
||||
break;
|
||||
}
|
||||
Err(e) => tracing::debug!(error = %e, "hr: reconnect failed"),
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Decode one notification into an event.
|
||||
fn handle(&self, uuid: uuid::Uuid, raw: &[u8]) {
|
||||
if uuid != uuids::HEART_RATE_MEASUREMENT {
|
||||
tracing::trace!(%uuid, raw = %hex(raw), "hr: notification on an unexpected characteristic");
|
||||
return;
|
||||
}
|
||||
match decode_heart_rate(raw) {
|
||||
Ok(m) => {
|
||||
let _ = self.events_tx.send(HeartRateEvent::Measurement {
|
||||
bpm: m.bpm,
|
||||
sensor_contact: m.sensor_contact,
|
||||
});
|
||||
}
|
||||
// Logged, never fatal (NFR-4).
|
||||
Err(e) => tracing::debug!(raw = %hex(raw), error = %e, "hr: bad measurement frame"),
|
||||
}
|
||||
}
|
||||
|
||||
/// Close the link. Bounded: this runs on the app's exit path (NFR-9).
|
||||
async fn teardown(&self, session: &Session) {
|
||||
let unsubscribe = session.peripheral.unsubscribe(&session.measurement);
|
||||
let _ = tokio::time::timeout(DISCONNECT_TIMEOUT, unsubscribe).await;
|
||||
match tokio::time::timeout(DISCONNECT_TIMEOUT, session.peripheral.disconnect()).await {
|
||||
Ok(Ok(())) => tracing::info!("hr: disconnected"),
|
||||
Ok(Err(e)) => tracing::debug!(error = %e, "hr: disconnect failed"),
|
||||
Err(_) => tracing::warn!("hr: disconnect timed out"),
|
||||
}
|
||||
let _ = self.events_tx.send(HeartRateEvent::Disconnected);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn a_plain_u8_measurement_decodes() {
|
||||
// Flags 0x00: u8 heart rate, no contact feature, nothing else.
|
||||
let m = decode_heart_rate(&[0x00, 142]).unwrap();
|
||||
assert_eq!(m.bpm, 142);
|
||||
assert_eq!(m.sensor_contact, None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn a_u16_measurement_decodes_little_endian() {
|
||||
// Flags 0x01: u16 heart rate. 0x0121 = 289 — absurd for a human but
|
||||
// the format allows it, and the decoder is a decoder, not a referee.
|
||||
let m = decode_heart_rate(&[0x01, 0x21, 0x01]).unwrap();
|
||||
assert_eq!(m.bpm, 289);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn sensor_contact_is_three_states_not_two() {
|
||||
// Bit 2 = feature supported, bit 1 = contact detected. A strap without
|
||||
// the feature must read `None`, not "fallen off".
|
||||
assert_eq!(
|
||||
decode_heart_rate(&[0x06, 100]).unwrap().sensor_contact,
|
||||
Some(true)
|
||||
);
|
||||
assert_eq!(
|
||||
decode_heart_rate(&[0x04, 100]).unwrap().sensor_contact,
|
||||
Some(false)
|
||||
);
|
||||
assert_eq!(decode_heart_rate(&[0x00, 100]).unwrap().sensor_contact, None);
|
||||
// Bit 1 without bit 2 is "feature not supported" per the spec.
|
||||
assert_eq!(decode_heart_rate(&[0x02, 100]).unwrap().sensor_contact, None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn trailing_fields_are_skipped_not_rejected() {
|
||||
// Flags 0x18: energy expended + RR intervals present. Real straps
|
||||
// (Garmin HRM-Dual, Polar H10) send these; the bpm must still decode.
|
||||
let m = decode_heart_rate(&[0x18, 155, 0x10, 0x00, 0x40, 0x03]).unwrap();
|
||||
assert_eq!(m.bpm, 155);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn short_frames_are_errors_not_panics() {
|
||||
// NFR-4: a malformed packet is a value, never a crash.
|
||||
assert_eq!(decode_heart_rate(&[]), Err(HrDecodeError::Empty));
|
||||
assert!(matches!(
|
||||
decode_heart_rate(&[0x00]),
|
||||
Err(HrDecodeError::TooShort { .. })
|
||||
));
|
||||
// u16 flag with only one byte of payload.
|
||||
assert!(matches!(
|
||||
decode_heart_rate(&[0x01, 142]),
|
||||
Err(HrDecodeError::TooShort { .. })
|
||||
));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn selector_any_requires_the_heart_rate_service() {
|
||||
let s = HrSelector::Any;
|
||||
assert!(s.matches_parts("aa:bb:cc:dd:ee:ff", true, ""));
|
||||
assert!(!s.matches_parts("aa:bb:cc:dd:ee:ff", false, ""));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn selector_address_ignores_the_advertisement() {
|
||||
// Reconnect runs against a device that may not be advertising its
|
||||
// services; the address alone identifies it.
|
||||
let s = HrSelector::Address("AA:BB:CC:DD:EE:FF".into());
|
||||
assert!(s.matches_parts("aa:bb:cc:dd:ee:ff", false, ""));
|
||||
assert!(!s.matches_parts("11:22:33:44:55:66", true, ""));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn selector_address_also_matches_an_opaque_platform_id() {
|
||||
// macOS gives UUID-shaped PeripheralIds rather than MACs.
|
||||
let s = HrSelector::Address("1E2F3A4B".into());
|
||||
assert!(s.matches_parts("", false, "PeripheralId(1e2f3a4b-....)"));
|
||||
}
|
||||
}
|
||||
@@ -13,6 +13,7 @@
|
||||
//! | [`control_point`] | `0x2AD9` encoders and response decoding | no |
|
||||
//! | [`capabilities`] | `0x2ACC`/`0x2AD5`/`0x2AD6`/`0x2AD8` decoding, and the safety gate | no |
|
||||
//! | [`zwift`] | Zwift's proprietary protocol (§2.3.1) | no |
|
||||
//! | [`heart_rate`] | `0x2A37` decoder (pure) and the HRM connection actor | decoder no, actor yes |
|
||||
//! | [`scan`] | discovery | yes |
|
||||
//! | [`client`] | the connection actor | yes |
|
||||
//!
|
||||
@@ -52,12 +53,17 @@ pub mod click;
|
||||
pub mod client;
|
||||
pub mod control_point;
|
||||
pub mod error;
|
||||
pub mod heart_rate;
|
||||
pub mod indoor_bike_data;
|
||||
pub mod scan;
|
||||
pub mod uuids;
|
||||
pub mod zwift;
|
||||
|
||||
pub use click::{ClickClient, ClickConfig, ClickEvent, PodSelector};
|
||||
pub use heart_rate::{
|
||||
decode_heart_rate, HeartRateClient, HeartRateConfig, HeartRateEvent, HeartRateMeasurement,
|
||||
HrSelector,
|
||||
};
|
||||
pub use capabilities::{
|
||||
FitnessMachineFeature, InclinationRange, PowerRange, ResistanceLevelRange, TrainerCapabilities,
|
||||
UnsupportedTarget,
|
||||
|
||||
@@ -55,6 +55,16 @@ pub const DEVICE_INFORMATION_SERVICE: Uuid = uuid16(0x180A);
|
||||
/// Battery Service — `0x180F`.
|
||||
pub const BATTERY_SERVICE: Uuid = uuid16(0x180F);
|
||||
|
||||
/// Battery Level — `0x2A19`, read.
|
||||
pub const BATTERY_LEVEL: Uuid = uuid16(0x2A19);
|
||||
|
||||
/// Heart Rate Service — `0x180D`. What a strap — or a watch in broadcast
|
||||
/// mode — advertises.
|
||||
pub const HEART_RATE_SERVICE: Uuid = uuid16(0x180D);
|
||||
|
||||
/// Heart Rate Measurement — `0x2A37`, notify.
|
||||
pub const HEART_RATE_MEASUREMENT: Uuid = uuid16(0x2A37);
|
||||
|
||||
/// Human-readable name for a well-known UUID, for logging and the probe CLI.
|
||||
/// Returns `None` for anything not recognised.
|
||||
pub fn well_known_name(uuid: Uuid) -> Option<&'static str> {
|
||||
@@ -79,6 +89,8 @@ pub fn well_known_name(uuid: Uuid) -> Option<&'static str> {
|
||||
0x1816 => "Cycling Speed and Cadence",
|
||||
0x2A00 => "Device Name",
|
||||
0x2A19 => "Battery Level",
|
||||
0x2A37 => "Heart Rate Measurement",
|
||||
0x2A38 => "Body Sensor Location",
|
||||
0x2A24 => "Model Number String",
|
||||
0x2A25 => "Serial Number String",
|
||||
0x2A26 => "Firmware Revision String",
|
||||
|
||||
Reference in New Issue
Block a user