Source code for bledev.heartrate

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT

"""Heart Rate Service (0x180D): a heart rate monitor that fitness apps can read.

Serve it, advertise it, and send a measurement whenever you have one::

    from bledev.heartrate import HeartRate, CHEST

    monitor = HeartRate(location=CHEST)
    ble.register_services(monitor.service)
    connection = await ble.advertise(name="HR", services=[monitor.SERVICE])
    monitor.update(72, rr_ms=(830, 842))     # subscribed centrals are notified

The measurement carries the flags the specification defines: an 8-bit or
16-bit rate (chosen by the value), sensor contact status when you pass
``contact``, energy expended when you pass ``energy_kj``, and RR-intervals
when you pass ``rr_ms``. A notification fits ``mtu - 3`` bytes, 20 until the
central asks for more, so a measurement takes at most nine RR-intervals
beside an 8-bit rate and nothing else.

Energy expended has a control point a central writes to reset the counter.
Give ``energy_expended=True`` and run ``await monitor.reset_requested()``
where you zero your own count.

``ble.register_services()`` replaces whatever was registered before, so pass
this service together with the others. Any peripheral backend serves it:
MicroPython (`bledev.mpble`), CircuitPython (`bledev.cpble`) and the fake one
for tests.
"""

from . import Characteristic, Service, UUID

SERVICE = UUID(0x180D)
HEART_RATE_MEASUREMENT = UUID(0x2A37)
BODY_SENSOR_LOCATION = UUID(0x2A38)
HEART_RATE_CONTROL_POINT = UUID(0x2A39)

#: Body Sensor Location values.
OTHER = 0
CHEST = 1
WRIST = 2
FINGER = 3
HAND = 4
EAR_LOBE = 5
FOOT = 6

# Flags bits of the measurement.
_FORMAT_16 = 0x01
_CONTACT_SUPPORTED = 0x04  # bits 1 and 2 hold the contact status: 2 or 3
_CONTACT_DETECTED = 0x02
_ENERGY = 0x08
_RR = 0x10

_MAX_PAYLOAD = 20  # a notification on the default 23-byte MTU


[docs] def encode_measurement(bpm, rr_ms=(), energy_kj=None, contact=None): """The Heart Rate Measurement bytes: flags, rate, energy, RR-intervals. Raises `ValueError` for a value that doesn't fit or more RR-intervals than one default-MTU notification holds. """ bpm = int(bpm) if not 0 <= bpm <= 0xFFFF: raise ValueError("a heart rate is 0 to 65535 beats per minute") flags = 0 if bpm > 0xFF: flags |= _FORMAT_16 out = bytearray((0, bpm & 0xFF, bpm >> 8)) else: out = bytearray((0, bpm)) if contact is not None: flags |= _CONTACT_SUPPORTED if contact: flags |= _CONTACT_DETECTED if energy_kj is not None: energy_kj = int(energy_kj) if not 0 <= energy_kj <= 0xFFFF: raise ValueError("energy expended is 0 to 65535 kJ") flags |= _ENERGY out.append(energy_kj & 0xFF) out.append(energy_kj >> 8) rr_ms = tuple(rr_ms) if rr_ms: if len(out) + 2 * len(rr_ms) > _MAX_PAYLOAD: raise ValueError("%d RR-intervals don't fit one notification" % len(rr_ms)) flags |= _RR for ms in rr_ms: # The unit is 1/1024 s. units = int(ms * 1024 / 1000 + 0.5) if not 0 <= units <= 0xFFFF: raise ValueError("an RR-interval is 0 to 64000 ms") out.append(units & 0xFF) out.append(units >> 8) out[0] = flags return bytes(out)
[docs] class HeartRate: """A Heart Rate Service. Args: location: Where the sensor sits (`CHEST`, `WRIST`, ...), or None to leave out the Body Sensor Location characteristic. energy_expended: True to serve the control point that resets the energy count. """ SERVICE = SERVICE def __init__(self, location=None, energy_expended=False): self.service = Service(SERVICE) #: The Heart Rate Measurement `bledev.Characteristic`: notify only. self.characteristic = Characteristic( self.service, HEART_RATE_MEASUREMENT, notify=True, initial=b"\x00\x00" ) if location is not None: if not 0 <= int(location) <= 6: raise ValueError("a body sensor location is 0 to 6") Characteristic(self.service, BODY_SENSOR_LOCATION, read=True, initial=bytes((int(location),))) self._control = None if energy_expended: self._control = Characteristic( self.service, HEART_RATE_CONTROL_POINT, write=True, capture=True, max_len=1 )
[docs] def update(self, bpm, rr_ms=(), energy_kj=None, contact=None): """Send a measurement to every central subscribed to it. Args: bpm: Beats per minute. rr_ms: RR-intervals in milliseconds, oldest first. energy_kj: Energy expended since the last reset, in kilojoules. contact: True or False when the sensor can tell whether it touches skin; None when it can't. """ self.characteristic.write(encode_measurement(bpm, rr_ms, energy_kj, contact), True)
[docs] async def reset_requested(self): """Wait until a central asks to reset the energy count, then return.""" if self._control is None: raise ValueError("create HeartRate with energy_expended=True to serve the control point") while True: _, data = await self._control.written() if bytes(data) == b"\x01": return