Activity algorithm interface

Interface between the activity service and the step/sleep algorithm. More...

Data Structures
struct	AlgMinuteFileSampleV5
	Minute file sample, version 5 fields. More...
struct	AlgMinuteFileSample
	Minute file sample. More...
struct	AlgMinuteDLSSample
	Data logging minute sample. More...
struct	AlgMinuteRecord
	Minute record in the circular buffer. More...
struct	AlgMinuteRecordHdr
	Header of minute file and data logging minute records. More...
struct	AlgMinuteDLSRecord
	Data logging minute record. More...
struct	AlgMinuteFileRecord
	Minute file record. More...
union	AlgMinuteFileSampleV5.__unnamed47__
	Minute flags. More...
struct	AlgMinuteFileSampleV5.__unnamed47__.__unnamed49__
	Individual flags. More...

Macros
#define	ALG_MINUTE_FILE_RECORD_VERSION   6
	Version of the minute file records.
#define	ALG_DLS_MINUTES_RECORD_VERSION   14
	Version of the data logging minute records.
#define	ALG_MINUTES_PER_DLS_RECORD   15
	Number of minutes in a data logging minute record.
#define	ALG_MINUTES_PER_FILE_RECORD   15
	Number of minutes in a minute file record.
#define	ALG_MINUTE_DATA_FILE_LEN   0x20000
	Size quota of the minute file, in bytes.
#define	ALG_MINUTE_FILE_MAX_ENTRIES   (ALG_MINUTE_DATA_FILE_LEN / sizeof(AlgMinuteFileRecord))
	Upper bound of the number of records in the minute file.

Functions
bool	activity_algorithm_init (AccelSamplingRate *sampling_rate)
	Initialize the algorithm.
void	activity_algorithm_early_deinit (void)
	Start tearing down: end all ongoing sessions.
bool	activity_algorithm_deinit (void)
	Deinitialize the algorithm.
bool	activity_algorithm_set_user (uint32_t height_mm, uint32_t weight_g, ActivityGender gender, uint32_t age_years)
	Set the user metrics used for the calorie computations.
void	activity_algorithm_handle_accel (AccelRawData *data, uint32_t num_samples, uint64_t timestamp_ms)
	Process accelerometer samples.
void	activity_algorithm_minute_handler (time_t utc_sec, AlgMinuteRecord *record_out)
	Collect and log the stats of the last minute.
bool	activity_algorithm_get_steps (uint32_t *steps)
	Get the number of steps counted today.
void	activity_algorithm_enable_activity_tracking (bool enable)
	Enable or disable automatic activity session detection.
bool	activity_algorithm_activity_hrm_is_active (void)
	Check whether a continuous heart rate session is active for a detected activity.
void	activity_algorithm_activity_hrm_set_paused (bool paused)
	Pause or resume the heart rate session of a detected activity.
bool	activity_algorithm_get_step_rate (uint16_t *steps, uint32_t *elapsed_ms, time_t *end_sec)
	Get the most recent stepping rate.
bool	activity_algorithm_metrics_changed_notification (void)
	Notify the algorithm that the metrics changed.
time_t	activity_algorithm_get_last_sleep_utc (void)
	Get the last minute processed by the sleep detector.
void	activity_algorithm_send_minutes (void)
	Send the buffered minute data to data logging now.
void	activity_algorithm_post_process_sleep_sessions (uint16_t num_sessions, ActivitySession *sessions)
	Relabel sleep sessions that should be naps.
bool	activity_algorithm_get_minute_history (HealthMinuteData *minute_data, uint32_t *num_records, time_t *utc_start)
	Get historical minute data.
bool	activity_algorithm_dump_minute_data_to_log (void)
	Dump the minute file base64-encoded with PBL_LOG.
bool	activity_algorithm_minute_file_info (bool compact_first, uint32_t *num_records, uint32_t *data_bytes, uint32_t *minutes)
	Get information on the minute file.
bool	activity_algorithm_test_fill_minute_file (void)
	Fill the minute file (test apps).
bool	activity_algorithm_test_send_fake_minute_data_dls_record (void)
	Send a fake minute record to data logging (mobile app testing).

Detailed Description

Interface between the activity service and the step/sleep algorithm.

The activity service calls these from KernelBG. The algorithm consumes accelerometer samples at the rate returned by activity_algorithm_init(), keeps the running step count, builds one minute record per minute, stores those in the minute file and sends them to data logging, and reports detected sessions to the service.

AccelSamplingRate rate;
 
activity_algorithm_init(&rate);
activity_algorithm_set_user(height_mm, weight_dag * 10, gender, age_years);
 
// For every batch of accelerometer samples
activity_algorithm_handle_accel(samples, num_samples, timestamp_ms);
 
// Once a minute
AlgMinuteRecord rec;
activity_algorithm_minute_handler(rtc_get_time(), &rec);
 
uint32_t steps;
activity_algorithm_get_steps(&steps);

---

Data Structure Documentation

AlgMinuteFileSampleV5

struct AlgMinuteFileSampleV5

Minute file sample, version 5 fields.

The minute file is a settings file holding the subset of the data logging minute data needed by the sleep algorithm and by minute history queries.

Data Fields
union AlgMinuteFileSampleV5.__unnamed47__	__unnamed__	Minute flags.
uint8_t	light	Light sensor reading divided by ALG_RAW_LIGHT_SENSOR_DIVIDE_BY.
uint8_t	orientation	Average orientation: upper 4 bits are the angle to the Z axis, lower 4 bits the angle in the X-Y plane, each quantized to 16 steps.
uint8_t	steps	Steps taken in this minute.
uint16_t	vmc	VMC (vector magnitude counts) of this minute.

AlgMinuteFileSample

struct AlgMinuteFileSample

Minute file sample.

Data Fields
uint8_t	heart_rate_bpm	Median heart rate, in beats per minute, 0 if none.
AlgMinuteFileSampleV5	v5_fields	Fields of versions up to 5.

AlgMinuteDLSSample

struct AlgMinuteDLSSample

Data logging minute sample.

Data Fields
uint16_t	active_calories	Active calories (1/1000 kcal) burned in this minute.
AlgMinuteFileSampleV5	base	Base fields, also stored in the minute file (versions 4 and 5).
uint16_t	distance_cm	Distance covered in this minute, in centimeters.
uint8_t	heart_rate_bpm	Weighted median heart rate of this minute, in beats per minute.
uint16_t	heart_rate_total_weight_x100	Total weight of the heart rate samples, multiplied by 100.
uint8_t	heart_rate_zone	Heart rate zone of this minute (HRZone).
uint16_t	resting_calories	Resting calories (1/1000 kcal) burned in this minute.
uint8_t	spo2_percent	Blood oxygen saturation (%) measured this minute, 0 if none.
uint8_t	spo2_quality	SpO2 signal quality (HeartRateQuality value), 0 if none.

AlgMinuteRecord

struct AlgMinuteRecord

Minute record in the circular buffer.

Records are batched there before being written to data logging and the minute file.

Data Fields
AlgMinuteDLSSample	data	Minute data.
time_t	utc_sec	UTC time of the minute.

AlgMinuteRecordHdr

struct AlgMinuteRecordHdr

Header of minute file and data logging minute records.

Data Fields
uint8_t	num_samples	Number of samples in the record.
uint8_t	sample_size	Size of each sample, in bytes.
int8_t	time_local_offset_15_min	Number of 15 minute intervals to add to UTC to get local time.
uint32_t	time_utc	UTC time of the first sample.
uint16_t	version	ALG_DLS_MINUTES_RECORD_VERSION or ALG_MINUTE_FILE_RECORD_VERSION.

AlgMinuteDLSRecord

struct AlgMinuteDLSRecord

Data logging minute record.

Data Fields
AlgMinuteRecordHdr	hdr	Header.
AlgMinuteDLSSample	samples[ALG_MINUTES_PER_DLS_RECORD]	One sample per minute.

AlgMinuteFileRecord

struct AlgMinuteFileRecord

Minute file record.

Data Fields
AlgMinuteRecordHdr	hdr	Header.
AlgMinuteFileSample	samples[ALG_MINUTES_PER_FILE_RECORD]	One sample per minute.

AlgMinuteFileSampleV5.__unnamed47__

union AlgMinuteFileSampleV5.__unnamed47__

Minute flags.

Data Fields
struct AlgMinuteFileSampleV5.__unnamed47__.__unnamed49__	__unnamed__	Individual flags.
uint8_t	flags	All flags.

AlgMinuteFileSampleV5.__unnamed47__.__unnamed49__

struct AlgMinuteFileSampleV5.__unnamed47__.__unnamed49__

Individual flags.

Data Fields
uint8_t	active: 1	Active minute.
uint8_t	plugged_in: 1	Watch was plugged into a charger.
uint8_t	reserved: 6	Reserved.

Macro Definition Documentation

ALG_DLS_MINUTES_RECORD_VERSION

#define ALG_DLS_MINUTES_RECORD_VERSION   14

Version of the data logging minute records.

Fields may only be appended: the mobile apps keep parsing the known prefix. Android 3.10-4.0 requires bit 2 to be set and iOS requires a value below 255, so valid versions are 4, 5, 6, 7, 12, 13, 14, 15, 20, ...

• 4: initial version;
• 5: added base flags;
• 6: added the active flag, resting and active calories, and distance;
• 7: added heart rate;
• 12: added total heart rate weight;
• 13: added heart rate zone;
• 14: added SpO2 percent and quality.

ALG_MINUTE_DATA_FILE_LEN

#define ALG_MINUTE_DATA_FILE_LEN   0x20000

Size quota of the minute file, in bytes.

ALG_MINUTE_FILE_MAX_ENTRIES

#define ALG_MINUTE_FILE_MAX_ENTRIES   (ALG_MINUTE_DATA_FILE_LEN / sizeof(AlgMinuteFileRecord))

Upper bound of the number of records in the minute file.

Ignores the settings file overhead, so the actual number is lower.

ALG_MINUTE_FILE_RECORD_VERSION

#define ALG_MINUTE_FILE_RECORD_VERSION   6

Version of the minute file records.

• 4: initial version;
• 5: added flags with the plugged_in and active bits;
• 6: added heart rate.

ALG_MINUTES_PER_DLS_RECORD

#define ALG_MINUTES_PER_DLS_RECORD   15

Number of minutes in a data logging minute record.

ALG_MINUTES_PER_FILE_RECORD

#define ALG_MINUTES_PER_FILE_RECORD   15

Number of minutes in a minute file record.

Function Documentation

activity_algorithm_activity_hrm_is_active()

bool activity_algorithm_activity_hrm_is_active

(

void

)

Check whether a continuous heart rate session is active for a detected activity.

Drives SpO2 sampling during activities.

Returns

true if heart rate is being sampled for a detected walk or run.

activity_algorithm_activity_hrm_set_paused()

void activity_algorithm_activity_hrm_set_paused

(

bool

paused

)

Pause or resume the heart rate session of a detected activity.

Frees the optical path for a SpO2 reading. No-op without an activity heart rate session.

Parameters

paused

true to pause, false to resume.

activity_algorithm_deinit()

bool activity_algorithm_deinit

(

void

)

Deinitialize the algorithm.

Returns

true on success.

activity_algorithm_dump_minute_data_to_log()

bool activity_algorithm_dump_minute_data_to_log

(

void

)

Dump the minute file base64-encoded with PBL_LOG.

Used to extract it through a support request.

Returns

true on success.

activity_algorithm_early_deinit()

void activity_algorithm_early_deinit

(

void

)

Start tearing down: end all ongoing sessions.

activity_algorithm_enable_activity_tracking()

void activity_algorithm_enable_activity_tracking

(

bool

enable

)

Enable or disable automatic activity session detection.

Disabled while a workout is running.

Parameters

enable

true to detect sessions, false to stop.

activity_algorithm_get_last_sleep_utc()

time_t activity_algorithm_get_last_sleep_utc

(

void

)

Get the last minute processed by the sleep detector.

Returns

UTC time of the minute.

activity_algorithm_get_minute_history()

bool activity_algorithm_get_minute_history	(	HealthMinuteData *	minute_data,
		uint32_t *	num_records,
		time_t *	utc_start
	)

Get historical minute data.

Parameters

[out]	minute_data	Array filled with one record per minute.
[in,out]	num_records	On entry, capacity of minute_data. On exit, number of records written, missing minutes included (marked with is_invalid).
[in,out]	utc_start	On entry, UTC time of the first requested minute. On exit, UTC time of the first returned minute.

Returns

true on success.

activity_algorithm_get_step_rate()

bool activity_algorithm_get_step_rate	(	uint16_t *	steps,
		uint32_t *	elapsed_ms,
		time_t *	end_sec
	)

Get the most recent stepping rate.

Parameters

[out]	steps	Steps taken during elapsed_ms.
[out]	elapsed_ms	Duration over which the rate was computed, in milliseconds.
[out]	end_sec	UTC time at which the rate was last computed.

Returns

true on success.

activity_algorithm_get_steps()

bool activity_algorithm_get_steps

(

uint32_t *

steps

)

Get the number of steps counted today.

Parameters

[out]

steps

Steps.

Returns

true on success.

activity_algorithm_handle_accel()

void activity_algorithm_handle_accel	(	AccelRawData *	data,
		uint32_t	num_samples,
		uint64_t	timestamp_ms
	)

Process accelerometer samples.

Parameters

data	Samples, in mG.
num_samples	Number of samples in data.
timestamp_ms	Timestamp of the first sample, in milliseconds.

activity_algorithm_init()

bool activity_algorithm_init

(

AccelSamplingRate *

sampling_rate

)

Initialize the algorithm.

Parameters

[out]

sampling_rate

Required accelerometer sampling rate.

Returns

true on success.

activity_algorithm_metrics_changed_notification()

bool activity_algorithm_metrics_changed_notification

(

void

)

Notify the algorithm that the metrics changed.

The algorithm reloads its running steps, calories and distance from the service. Called at midnight to start a new day and whenever new values are written into the health database.

Returns

true on success.

activity_algorithm_minute_file_info()

bool activity_algorithm_minute_file_info	(	bool	compact_first,
		uint32_t *	num_records,
		uint32_t *	data_bytes,
		uint32_t *	minutes
	)

Get information on the minute file.

Parameters

	compact_first	If true, compact the file first.
[out]	num_records	Number of records in the file.
[out]	data_bytes	Bytes of data in the file.
[out]	minutes	Minutes of data in the file.

Returns

true on success.

activity_algorithm_minute_handler()

void activity_algorithm_minute_handler	(	time_t	utc_sec,
		AlgMinuteRecord *	record_out
	)

Collect and log the stats of the last minute.

Called once per minute. The minute data is mostly used to compute sleep.

Parameters

	utc_sec	UTC time at which the minute handler was triggered.
[out]	record_out	Minute record.

activity_algorithm_post_process_sleep_sessions()

void activity_algorithm_post_process_sleep_sessions	(	uint16_t	num_sessions,
		ActivitySession *	sessions
	)

Relabel sleep sessions that should be naps.

A sleep session is a nap when it is at most ALG_MAX_NAP_MINUTES long and lies entirely between ALG_PRIMARY_MORNING_MINUTE and ALG_PRIMARY_EVENING_MINUTE.

Parameters

	num_sessions	Number of sessions in sessions.
[in,out]	sessions	Sessions.

activity_algorithm_send_minutes()

void activity_algorithm_send_minutes

(

void

)

Send the buffered minute data to data logging now.

activity_algorithm_set_user()

bool activity_algorithm_set_user	(	uint32_t	height_mm,
		uint32_t	weight_g,
		ActivityGender	gender,
		uint32_t	age_years
	)

Set the user metrics used for the calorie computations.

Parameters

height_mm	Height, in millimeters.
weight_g	Weight, in grams.
gender	Gender.
age_years	Age, in years.

Returns

true on success.

activity_algorithm_test_fill_minute_file()

bool activity_algorithm_test_fill_minute_file

(

void

)

Fill the minute file (test apps).

Returns

true on success.

activity_algorithm_test_send_fake_minute_data_dls_record()

bool activity_algorithm_test_send_fake_minute_data_dls_record

(

void

)

Send a fake minute record to data logging (mobile app testing).

Returns

true on success.