src.bluetooth_sig.gatt.characteristics.heart_rate_measurement

Heart Rate Measurement characteristic implementation.

Attributes

Name

Description

RR_INTERVAL_RESOLUTION

logger

Classes

Name

Description

HeartRateData

Parsed data from Heart Rate Measurement characteristic.

HeartRateMeasurementCharacteristic

Heart Rate Measurement characteristic (0x2A37).

HeartRateMeasurementFlags

Heart Rate Measurement flags as per Bluetooth SIG specification.

SensorContactState

Sensor contact state enumeration.

Module Contents

class src.bluetooth_sig.gatt.characteristics.heart_rate_measurement.HeartRateData

Bases: msgspec.Struct

Parsed data from Heart Rate Measurement characteristic.

heart_rate

Heart rate in beats per minute (0-UINT16_MAX)

sensor_contact

State of sensor contact detection

energy_expended

Optional energy expended in kilojoules

rr_intervals

Tuple of R-R intervals in seconds (immutable)

flags

Raw flags byte for reference

sensor_location

Optional body sensor location from context (BodySensorLocation enum)

energy_expended: int | None = None
flags: HeartRateMeasurementFlags
heart_rate: int
rr_intervals: tuple[float, Ellipsis] = ()
sensor_contact: SensorContactState
sensor_location: src.bluetooth_sig.gatt.characteristics.body_sensor_location.BodySensorLocation | None = None
class src.bluetooth_sig.gatt.characteristics.heart_rate_measurement.HeartRateMeasurementCharacteristic

Bases: src.bluetooth_sig.gatt.characteristics.base.BaseCharacteristic[HeartRateData]

Heart Rate Measurement characteristic (0x2A37).

Used in Heart Rate Service (spec: Heart Rate Service 1.0, Heart Rate Profile 1.0) to transmit instantaneous heart rate plus optional energy expended and RR-Interval metrics.

Specification summary (flags byte bit assignments - see adopted spec & Errata 23224):

Bit 0 (0x01): Heart Rate Value Format (0 = uint8, 1 = uint16) Bit 1 (0x02): Sensor Contact Supported Bit 2 (0x04): Sensor Contact Detected (valid only when Bit1 set) Bit 3 (0x08): Energy Expended Present (adds 2 bytes, little-endian, in kilo Joules) Bit 4 (0x10): RR-Interval(s) Present (sequence of 16-bit values, units 1/1024 s) Bits 5-7: Reserved (must be 0)

Parsing Rules:

  • Minimum length: 2 bytes (flags + at least one byte of heart rate value)

  • If Bit0 set, heart rate is 16 bits; else 8 bits

  • Energy Expended only parsed if flag set AND 2 bytes remain

  • RR-Intervals parsed greedily in pairs until buffer end when flag set

  • RR-Interval raw value converted to seconds: raw / 1024.0

  • Sensor contact state derived from Bits1/2 tri-state (not supported, not detected, detected)

Validation:

  • Heart rate validated within 0..UINT16_MAX (spec does not strictly define upper physiological bound)

  • RR interval constrained to 0.0-65.535 s (fits 16-bit / 1024 scaling and guards against malformed data)

  • Energy expended 0..UINT16_MAX

References

RR_INTERVAL_RESOLUTION = 1024.0
allow_variable_length: bool = True
min_length: int = 2
class src.bluetooth_sig.gatt.characteristics.heart_rate_measurement.HeartRateMeasurementFlags

Bases: enum.IntFlag

Heart Rate Measurement flags as per Bluetooth SIG specification.

ENERGY_EXPENDED_PRESENT = 8
HEART_RATE_VALUE_FORMAT_UINT16 = 1
RR_INTERVAL_PRESENT = 16
SENSOR_CONTACT_DETECTED = 4
SENSOR_CONTACT_SUPPORTED = 2
class src.bluetooth_sig.gatt.characteristics.heart_rate_measurement.SensorContactState

Bases: enum.IntEnum

Sensor contact state enumeration.

classmethod from_flags(flags: int) → SensorContactState

Create enum from heart rate flags.

DETECTED = 2
NOT_DETECTED = 1
NOT_SUPPORTED = 0
src.bluetooth_sig.gatt.characteristics.heart_rate_measurement.RR_INTERVAL_RESOLUTION = 1024.0
src.bluetooth_sig.gatt.characteristics.heart_rate_measurement.logger