Heart rate monitor

Shared access to the optical heart rate sensor (BPM, HRV and SpO2). More...

Modules
	HRM activity scene
	What the user is doing, so the sensor algorithm can use a motion-tuned model.
	HRM manager internals
	Manager state, tuning constants and kernel subscriptions.

Data Structures
struct	HRMAccelData
	Accelerometer samples for the HRM driver's motion compensation. More...
struct	HRMData
	Data reported by the HRM driver. More...

Macros
#define	HRM_MANAGER_ACCEL_RATE_MILLIHZ   (25000)
	Accelerometer sampling rate provided to the HRM driver, in mHz (25 Hz).
#define	HRM_MANAGER_MAX_ACCEL_SAMPLES   ((2 * HRM_MANAGER_ACCEL_RATE_MILLIHZ) / 1000)
	Accelerometer samples buffered for the driver: 2 s, in case a handshake is missed.
#define	HRM_MANAGER_APP_EXIT_EXPIRATION_SEC   PBL_SEC_PER_HOUR
	Expiration given to the subscription of an app that exits, in seconds.
#define	HRM_INVALID_SESSION_REF   0
	Invalid subscription handle.
#define	HRM_SUBSCRIPTION_EXPIRING_WARNING_SEC   5
	Minimum warning before a subscription expires, in seconds.

Typedefs
typedef uint32_t	HRMSessionRef
	Subscription handle.

Enumerations
enum	HRMQuality {   HRMQuality_OffWrist = -1 , HRMQuality_Worst = 0 , HRMQuality_Poor , HRMQuality_Acceptable ,   HRMQuality_Good , HRMQuality_Excellent }
	Quality of a reading, as graded by the sensor algorithm. More...
enum	HRMFeatureShift { HRMFeatureShift_BPM = 0 , HRMFeatureShift_HRV = 1 , HRMFeatureShift_SpO2 = 2 , HRMFeatureShiftMax }
	Bit positions of HRMFeature. More...
enum	HRMFeature { HRMFeature_BPM = (1 << HRMFeatureShift_BPM) , HRMFeature_HRV = (1 << HRMFeatureShift_HRV) , HRMFeature_SpO2 = (1 << HRMFeatureShift_SpO2) , HRMFeatureMax }
	Sensor features, combined as a bitmask. More...

Functions
HRMAccelData *	hrm_manager_get_accel_data (void)
	Get the accelerometer samples collected since the last release.
void	hrm_manager_release_accel_data (void)
	Empty and unlock the buffer returned by hrm_manager_get_accel_data().
void	hrm_manager_init (void)
	Initialize the HRM manager.
void	hrm_manager_handle_prefs_changed (void)
	Re-evaluate the sensor state after the HRM related preferences changed.
bool	hrm_manager_has_continuous_green_subscriber (void)
	Check whether a live subscriber keeps the green optical path on continuously.
HRMSessionRef	sys_hrm_manager_app_subscribe (AppInstallId app_id, uint32_t update_interval_s, uint16_t expire_s, HRMFeature features)
	Subscribe an app or worker to sensor updates.
HRMSessionRef	sys_hrm_manager_get_app_subscription (AppInstallId app_id)
	Get the subscription of an app or worker.
bool	sys_hrm_manager_unsubscribe (HRMSessionRef session)
	Unsubscribe, turning the sensor off if no longer needed.
bool	sys_hrm_manager_set_features (HRMSessionRef session, HRMFeature features)
	Change the features of a subscription.
bool	sys_hrm_manager_set_update_interval (HRMSessionRef session, uint32_t update_interval_s, uint16_t expire_s)
	Change the update interval and expiration of a subscription.
bool	sys_hrm_manager_get_subscription_info (HRMSessionRef session, AppInstallId *app_id, uint32_t *update_interval_s, uint16_t *expire_s, HRMFeature *features)
	Get information on a subscription.
bool	sys_hrm_manager_is_hrm_present (void)
	Check whether a heart rate monitor is present and accessible.
void	hrm_manager_enable (bool on)
	Enable or disable the HRM manager for the current run level.
void	hrm_manager_new_data_cb (const HRMData *data)
	Report new data from the HRM driver.
void	hrm_manager_process_cleanup (PebbleTask task, AppInstallId app_id)
	Clean up after an app or worker exited.

Detailed Description

Shared access to the optical heart rate sensor (BPM, HRV and SpO2).

Subscribers ask for a set of features and an update interval. A subscriber is due when its interval has elapsed since it last got a usable reading; the manager turns the sensor on (HRM_SENSOR_SPIN_UP_SEC early) while any subscriber is due and off otherwise. While on, the driver reports data about once per second and every reading is delivered to every subscriber of that feature, so intervals at or below the spin-up time keep the sensor on continuously.

The green (BPM, HRV) and red/IR (SpO2) optical paths are mutually exclusive; SpO2 wins when due. Background subscribers only get the features allowed by the heart rate and blood oxygen preferences, foreground apps get what they ask for. The sensor stays off while charging or when the run level disables it.

Apps and workers subscribe through the syscalls and receive PEBBLE_HRM_EVENT events on their queue. KernelBG clients subscribe with a callback (see HRM manager internals):

static void prv_hrm_cb(PebbleHRMEvent *event, void *context) {
  if (event->event_type == HRMEvent_BPM && event->bpm.quality >= HRMQuality_Acceptable) {
    // event->bpm.bpm
  } else if (event->event_type == HRMEvent_SubscriptionExpiring) {
    // renew with sys_hrm_manager_set_update_interval() if still needed
  }
}
 
// 1 s updates, expiring after 10 minutes
HRMSessionRef session = hrm_manager_subscribe_with_callback(
    INSTALL_ID_INVALID, 1, 10 * 60, HRMFeature_BPM, false, prv_hrm_cb, NULL);
...
sys_hrm_manager_unsubscribe(session);

---

Data Structure Documentation

HRMAccelData

struct HRMAccelData

Accelerometer samples for the HRM driver's motion compensation.

Data Fields
AccelRawData	data[HRM_MANAGER_MAX_ACCEL_SAMPLES]	Samples, in mG.
uint32_t	num_samples	Number of valid samples in data.

HRMData

struct HRMData

Data reported by the HRM driver.

Data Fields
HRMFeature	features	Features with valid data in this report.
uint8_t	hrm_bpm	Heart rate, in beats per minute.
HRMQuality	hrm_quality	Heart rate quality.
uint16_t	hrv_ppi_ms	Peak-to-peak interval, in milliseconds.
HRMQuality	hrv_quality	HRV quality.
uint8_t	spo2_confidence	Raw algorithm confidence coefficient (debug).
bool	spo2_invalid	Raw algorithm invalid flag (debug); a reading with it clear is usable.
uint8_t	spo2_percent	Blood oxygen saturation, in percent.
HRMQuality	spo2_quality	SpO2 quality.
uint8_t	spo2_valid_level	Raw algorithm valid level (debug).

Macro Definition Documentation

HRM_INVALID_SESSION_REF

#define HRM_INVALID_SESSION_REF   0

Invalid subscription handle.

HRM_MANAGER_ACCEL_RATE_MILLIHZ

#define HRM_MANAGER_ACCEL_RATE_MILLIHZ   (25000)

Accelerometer sampling rate provided to the HRM driver, in mHz (25 Hz).

HRM_MANAGER_APP_EXIT_EXPIRATION_SEC

#define HRM_MANAGER_APP_EXIT_EXPIRATION_SEC   PBL_SEC_PER_HOUR

Expiration given to the subscription of an app that exits, in seconds.

HRM_MANAGER_MAX_ACCEL_SAMPLES

#define HRM_MANAGER_MAX_ACCEL_SAMPLES   ((2 * HRM_MANAGER_ACCEL_RATE_MILLIHZ) / 1000)

Accelerometer samples buffered for the driver: 2 s, in case a handshake is missed.

HRM_SUBSCRIPTION_EXPIRING_WARNING_SEC

#define HRM_SUBSCRIPTION_EXPIRING_WARNING_SEC   5

Minimum warning before a subscription expires, in seconds.

A HRMEvent_SubscriptionExpiring event is sent this long, or one update interval if longer, before expiration.

Typedef Documentation

HRMSessionRef

typedef uint32_t HRMSessionRef

Subscription handle.

Enumeration Type Documentation

HRMFeature

enum HRMFeature

Sensor features, combined as a bitmask.

Enumerator
HRMFeature_BPM	Heart rate, in beats per minute.
HRMFeature_HRV	Heart rate variability (peak-to-peak interval).
HRMFeature_SpO2	Blood oxygen saturation.
HRMFeatureMax	Upper bound of the feature values.

HRMFeatureShift

enum HRMFeatureShift

Bit positions of HRMFeature.

Enumerator
HRMFeatureShift_BPM	Heart rate.
HRMFeatureShift_HRV	Heart rate variability.
HRMFeatureShift_SpO2	Blood oxygen saturation.
HRMFeatureShiftMax	Number of features.

HRMQuality

enum HRMQuality

Quality of a reading, as graded by the sensor algorithm.

Enumerator
HRMQuality_OffWrist	The watch is not on the wrist.
HRMQuality_Worst	Worst quality.
HRMQuality_Poor	Poor quality.
HRMQuality_Acceptable	Acceptable quality.
HRMQuality_Good	Good quality.
HRMQuality_Excellent	Excellent quality.

Function Documentation

hrm_manager_enable()

void hrm_manager_enable

(

bool

on

)

Enable or disable the HRM manager for the current run level.

Subscribers are kept while disabled but get no updates.

Parameters

on	Whether the sensor may be turned on.

hrm_manager_get_accel_data()

HRMAccelData * hrm_manager_get_accel_data

(

void

)

Get the accelerometer samples collected since the last release.

Locks the buffer until hrm_manager_release_accel_data(). For the HRM driver.

Returns

Locked sample buffer.

hrm_manager_handle_prefs_changed()

void hrm_manager_handle_prefs_changed

(

void

)

Re-evaluate the sensor state after the HRM related preferences changed.

hrm_manager_has_continuous_green_subscriber()

bool hrm_manager_has_continuous_green_subscriber

(

void

)

Check whether a live subscriber keeps the green optical path on continuously.

That is, a BPM or HRV subscriber with an interval within HRM_SENSOR_SPIN_UP_SEC (live workout heart rate, the BLE heart rate relay, a foreground app). Background SpO2 readers use it to defer their measurement window instead of taking the optical path away.

Returns

true if such a subscriber exists.

hrm_manager_init()

void hrm_manager_init

(

void

)

Initialize the HRM manager.

hrm_manager_new_data_cb()

void hrm_manager_new_data_cb

(

const HRMData *

data

)

Report new data from the HRM driver.

Called about once per second while the sensor is on. Queues events for the subscribers of the reported features.

Parameters

data

New data.

hrm_manager_process_cleanup()

void hrm_manager_process_cleanup	(	PebbleTask	task,
		AppInstallId	app_id
	)

Clean up after an app or worker exited.

Makes its subscription expire within HRM_MANAGER_APP_EXIT_EXPIRATION_SEC, unless it already expires sooner.

Parameters

task	Task of the process.
app_id	App install id.

hrm_manager_release_accel_data()

void hrm_manager_release_accel_data

(

void

)

Empty and unlock the buffer returned by hrm_manager_get_accel_data().

sys_hrm_manager_app_subscribe()

HRMSessionRef sys_hrm_manager_app_subscribe	(	AppInstallId	app_id,
		uint32_t	update_interval_s,
		uint16_t	expire_s,
		HRMFeature	features
	)

Subscribe an app or worker to sensor updates.

Not for KernelBG or KernelMain clients, see hrm_manager_subscribe_with_callback(). An existing subscription of the caller is replaced, keeping its session reference. Events are delivered as PEBBLE_HRM_EVENT to the caller's task. Foreground apps with an interval of at most HRM_LOW_LATENCY_MAX_INTERVAL_S get low latency updates.

Parameters

app_id	Caller's app install id.
update_interval_s	Requested update interval, in seconds.
expire_s	Seconds after which the subscription expires, 0 for never.
features	Requested features.

Returns

Session reference.

sys_hrm_manager_get_app_subscription()

HRMSessionRef sys_hrm_manager_get_app_subscription

(

AppInstallId

app_id

)

Get the subscription of an app or worker.

Not for KernelBG subscriptions.

Parameters

app_id

App install id.

Returns

Session reference, HRM_INVALID_SESSION_REF if none.

sys_hrm_manager_get_subscription_info()

bool sys_hrm_manager_get_subscription_info	(	HRMSessionRef	session,
		AppInstallId *	app_id,
		uint32_t *	update_interval_s,
		uint16_t *	expire_s,
		HRMFeature *	features
	)

Get information on a subscription.

Parameters

	session	Session reference.
[out]	app_id	If not NULL, app install id of the subscriber.
[out]	update_interval_s	If not NULL, update interval, in seconds.
[out]	expire_s	If not NULL, seconds until expiration, 0 for never.
[out]	features	If not NULL, requested features.

Returns

true on success, false if the subscription was not found.

sys_hrm_manager_is_hrm_present()

bool sys_hrm_manager_is_hrm_present

(

void

)

Check whether a heart rate monitor is present and accessible.

Returns

true if the HRM service is built in (CONFIG_SERVICE_HRM).

sys_hrm_manager_set_features()

bool sys_hrm_manager_set_features	(	HRMSessionRef	session,
		HRMFeature	features
	)

Change the features of a subscription.

A subscription without features is kept but ignored: it never turns the sensor on and receives no data.

Parameters

session	Session reference.
features	Requested features.

Returns

true on success, false if the subscription was not found.

sys_hrm_manager_set_update_interval()

bool sys_hrm_manager_set_update_interval	(	HRMSessionRef	session,
		uint32_t	update_interval_s,
		uint16_t	expire_s
	)

Change the update interval and expiration of a subscription.

Parameters

session	Session reference.
update_interval_s	Requested update interval, in seconds.
expire_s	Seconds from now after which the subscription expires, 0 for never.

Returns

true on success, false if the subscription was not found.

sys_hrm_manager_unsubscribe()

bool sys_hrm_manager_unsubscribe

(

HRMSessionRef

session

)

Unsubscribe, turning the sensor off if no longer needed.

Parameters

session

Session reference.

Returns

true on success, false if the subscription was not found.