HRM manager internals

Manager state, tuning constants and kernel subscriptions. More...

Data Structures
struct	HRMSubscriberState
	Subscriber state. More...
struct	HRMManagerState
	HRM manager state. More...

Macros
#define	HRM_SENSOR_SPIN_UP_SEC   20
	Time needed for a good reading after turning the sensor on, in seconds.
#define	HRM_LOW_LATENCY_MAX_INTERVAL_S   2
	Maximum interval of a foreground app getting the low latency FIFO cadence, in seconds.
#define	NUM_EVENTS_TO_QUEUE   (8)
	Number of events queued for KernelBG subscribers.
#define	EVENT_STORAGE_SIZE   (sizeof(PebbleHRMEvent) * NUM_EVENTS_TO_QUEUE)
	Size of the KernelBG event storage, in bytes.
#define	HRM_MANAGER_ACCEL_MANAGER_SAMPLES_PER_UPDATE   4
	Accelerometer samples per accelerometer manager update.
#define	HRM_CHECK_SENSOR_DISABLE_COUNT   3
	Number of driver reports between checks for turning the sensor off.
#define	HRM_MAX_ENABLE_FAILURES   3
	Consecutive sensor enable failures after which retries stop until reboot.
#define	HRM_MAX_UNSERVED_TIME_SEC   120
	Sensor on-time after which a subscriber without a usable reading is deferred, in seconds.

Typedefs
typedef void(*	HRMSubscriberCallback) (PebbleHRMEvent *event, void *context)
	Callback receiving HRM events, for KernelBG and KernelMain subscribers.
typedef struct AccelServiceState	AccelServiceState
	Opaque accelerometer service state.

Functions
HRMSessionRef	hrm_manager_subscribe_with_callback (AppInstallId app_id, uint32_t update_interval_s, uint16_t expire_s, HRMFeature features, bool low_latency, HRMSubscriberCallback callback, void *context)
	Subscribe a KernelBG or KernelMain client to sensor updates.
void	hrm_manager_set_activity_scene (HRMActivityScene scene)
	Set the activity scene the heart rate algorithm optimizes for.

Detailed Description

Manager state, tuning constants and kernel subscriptions.

---

Data Structure Documentation

HRMSubscriberState

struct HRMSubscriberState

Subscriber state.

Data Fields
AppInstallId	app_id	App install id, INSTALL_ID_INVALID for system subscribers.
void *	callback_context	Callback context, only for KernelBG subscribers.
HRMSubscriberCallback	callback_handler	Callback, only for KernelBG subscribers.
time_t	expire_utc	Expiration time, UTC; 0 for never.
HRMFeature	features	Requested features.
RtcTicks	last_valid_bpm_ticks	Tick count of the last usable reading this subscriber received.
ListNode	list_node	Subscriber list node.
bool	low_latency	Needs the prompt FIFO cadence (a foreground app showing live readings), rather than the background one.
struct pbl_msgq *	queue	Queue events are sent to; NULL for KernelBG.
bool	sent_expiration_event	A HRMEvent_SubscriptionExpiring event was sent.
HRMSessionRef	session_ref	Session reference of this subscriber.
PebbleTask	task	Task of the subscriber.
uint32_t	update_interval_s	Requested update interval, in seconds.

HRMManagerState

struct HRMManagerState

HRM manager state.

Data Fields
HRMAccelData	accel_data	Accelerometer samples for the driver.
struct pbl_mutex	accel_data_lock	Lock protecting accel_data.
AccelRawData	accel_manager_buffer[HRM_MANAGER_ACCEL_MANAGER_SAMPLES_PER_UPDATE]	Accelerometer manager sample buffer.
AccelManagerState *	accel_state	Accelerometer manager subscription, while the sensor is on.
HRMFeature	active_features	Features being sampled, 0 when off. Only one optical path, green (BPM, HRV) or red/IR (SpO2), runs at a time.
HRMActivityScene	activity_scene	Activity scene for the heart rate algorithm, re-applied at every sensor power on.
EventServiceInfo	charger_subscription	Battery state subscription, to track the charger.
uint8_t	check_disable_counter	Driver reports since the last turn-off check, up to HRM_CHECK_SENSOR_DISABLE_COUNT.
uint32_t	dropped_events	Number of dropped events.
uint8_t	enable_failure_count	Consecutive enable failures, retries stop at HRM_MAX_ENABLE_FAILURES.
bool	enabled_charging_state	The watch is not charging.
HRMFeature	enabled_features	Features the sensor was last enabled with.
bool	enabled_run_level	The run level allows the sensor.
struct pbl_mutex	lock	Lock protecting the state.
HRMSessionRef	next_session_ref	Last session reference assigned.
RtcTicks	sensor_on_since_ticks	Tick count when the sensor, or the current optical path, was turned on; 0 while off.
ListNode *	subscribers	Subscriber list.
CircularBuffer	system_task_event_buffer	Events pending for KernelBG subscribers.
uint8_t	system_task_event_storage[EVENT_STORAGE_SIZE]	Storage of system_task_event_buffer.
bool	unserved_timeout_logged	The unserved timeout warning was logged during this on-time.
TimerID	update_enable_timer_id	Timer turning the sensor back on.

Macro Definition Documentation

EVENT_STORAGE_SIZE

#define EVENT_STORAGE_SIZE   (sizeof(PebbleHRMEvent) * NUM_EVENTS_TO_QUEUE)

Size of the KernelBG event storage, in bytes.

HRM_CHECK_SENSOR_DISABLE_COUNT

#define HRM_CHECK_SENSOR_DISABLE_COUNT   3

Number of driver reports between checks for turning the sensor off.

Kept low so a served subscriber does not keep the LED lit, and the other optical path blocked, for long.

HRM_LOW_LATENCY_MAX_INTERVAL_S

#define HRM_LOW_LATENCY_MAX_INTERVAL_S   2

Maximum interval of a foreground app getting the low latency FIFO cadence, in seconds.

Such an app shows live readings; slower subscribers get the default, cheaper cadence.

HRM_MANAGER_ACCEL_MANAGER_SAMPLES_PER_UPDATE

#define HRM_MANAGER_ACCEL_MANAGER_SAMPLES_PER_UPDATE   4

Accelerometer samples per accelerometer manager update.

HRM_MAX_ENABLE_FAILURES

#define HRM_MAX_ENABLE_FAILURES   3

Consecutive sensor enable failures after which retries stop until reboot.

HRM_MAX_UNSERVED_TIME_SEC

#define HRM_MAX_UNSERVED_TIME_SEC   120

Sensor on-time after which a subscriber without a usable reading is deferred, in seconds.

The subscriber then waits for its next interval instead of holding the sensor on. Well above a normal serve cycle (spin-up plus a few seconds), well below the battery impact threshold.

HRM_SENSOR_SPIN_UP_SEC

#define HRM_SENSOR_SPIN_UP_SEC   20

Time needed for a good reading after turning the sensor on, in seconds.

The sensor is turned on this early for a subscriber that becomes due, and it is subtracted from every subscriber's remaining time: a subscriber with an interval within it is always due and keeps the sensor on, rather than paying an algorithm restart every interval.

NUM_EVENTS_TO_QUEUE

#define NUM_EVENTS_TO_QUEUE   (8)

Number of events queued for KernelBG subscribers.

Updates come at about 1 Hz, with up to 2 events per second: 8 events allow a 4 s stall when subscribed to both BPM and another feature.

Typedef Documentation

AccelServiceState

typedef struct AccelServiceState AccelServiceState

Opaque accelerometer service state.

HRMSubscriberCallback

typedef void(* HRMSubscriberCallback) (PebbleHRMEvent *event, void *context)

Callback receiving HRM events, for KernelBG and KernelMain subscribers.

Called on KernelBG with the HRM manager lock held.

Parameters

event	Event.
context	Context given at subscription.

Function Documentation

hrm_manager_set_activity_scene()

void hrm_manager_set_activity_scene

(

HRMActivityScene

scene

)

Set the activity scene the heart rate algorithm optimizes for.

Applied immediately and again at every sensor power on. Callable from any task.

Parameters

scene

Activity scene.

hrm_manager_subscribe_with_callback()

HRMSessionRef hrm_manager_subscribe_with_callback	(	AppInstallId	app_id,
		uint32_t	update_interval_s,
		uint16_t	expire_s,
		HRMFeature	features,
		bool	low_latency,
		HRMSubscriberCallback	callback,
		void *	context
	)

Subscribe a KernelBG or KernelMain client to sensor updates.

KernelBG clients must pass a callback. KernelMain clients may instead receive events through the event service. Apps and workers use sys_hrm_manager_app_subscribe().

Parameters

app_id	App install id, INSTALL_ID_INVALID for system subscribers.
update_interval_s	Requested update interval, in seconds.
expire_s	Seconds after which the subscription expires, 0 for never.
features	Requested features.
low_latency	true for consumers showing live data that need prompt updates; false for background logging and streaming, letting the sensor drain its FIFO less often to save power.
callback	KernelBG callback.
context	Context passed to callback.

Returns

Session reference.