Kraepelin

Step counting, sleep and activity session detection. More...

Data Structures
struct	pbl_kraepelin_sample
	Accelerometer sample, in mG. More...
struct	pbl_kraepelin_sleep_stats
	Ongoing sleep statistics, returned by pbl_kraepelin_get_sleep_stats(). More...
struct	pbl_kraepelin_step_activity
	Walk or run in progress, returned by pbl_kraepelin_get_step_activity(). More...
struct	pbl_kraepelin_params
	Detection parameters that depend on the accelerometer, passed to pbl_kraepelin_init(). More...

Macros
#define	PBL_KRAEPELIN_SAMPLE_HZ   25
	Accelerometer sampling rate expected by the algorithm, in Hz.
#define	PBL_KRAEPELIN_MAX_UNCERTAIN_SLEEP_M   19
	Maximum delay, in minutes, for the sleep algorithm to detect that the user woke up.
#define	PBL_KRAEPELIN_PARAMS_DEFAULT
	Default pbl_kraepelin_params initializer.

Typedefs
typedef void(*	pbl_kraepelin_session_cb_t) (void *context, enum pbl_kraepelin_activity activity_type, time_t start_utc, uint32_t len_sec, bool ongoing, bool delete, uint32_t steps, uint32_t resting_calories, uint32_t active_calories, uint32_t distance_mm)
	Callback reporting activity sessions, called by pbl_kraepelin_activities_update().
typedef void(*	pbl_kraepelin_stats_cb_t) (uint32_t num_stats, const char **names, int32_t *stats)
	Callback receiving algorithm statistics.

Enumerations
enum	pbl_kraepelin_activity {   PBL_KRAEPELIN_ACTIVITY_SLEEP , PBL_KRAEPELIN_ACTIVITY_RESTFUL_SLEEP , PBL_KRAEPELIN_ACTIVITY_WALK , PBL_KRAEPELIN_ACTIVITY_RUN ,   PBL_KRAEPELIN_ACTIVITY_COUNT }
	Activity types reported to pbl_kraepelin_session_cb_t. More...

Functions
uint32_t	pbl_kraepelin_state_size (void)
	Get the size of the algorithm state.
bool	pbl_kraepelin_init (struct pbl_kraepelin *state, const struct pbl_kraepelin_params *params, pbl_kraepelin_stats_cb_t stats_cb)
	Initialize the algorithm state.
uint32_t	pbl_kraepelin_analyze_samples (struct pbl_kraepelin *state, const struct pbl_kraepelin_sample *samples, uint32_t num_samples, uint32_t *consumed_samples)
	Analyze accelerometer samples.
void	pbl_kraepelin_minute_stats (struct pbl_kraepelin *state, uint16_t *vmc, uint8_t *orientation, bool *still)
	Get the last minute's stats and reset them for the next minute.
uint32_t	pbl_kraepelin_analyze_finish_epoch (struct pbl_kraepelin *state)
	Process the partial epoch not yet processed by pbl_kraepelin_analyze_samples() (unit tests).
void	pbl_kraepelin_activities_update (struct pbl_kraepelin *state, time_t utc_now, uint16_t steps, uint16_t vmc, uint8_t orientation, bool definitely_not_worn, uint32_t resting_calories, uint32_t active_calories, uint32_t distance_mm, bool shutting_down, pbl_kraepelin_session_cb_t sessions_cb, void *context)
	Feed a minute of data to the walk, run and sleep detectors.
time_t	pbl_kraepelin_activity_last_processed_time (struct pbl_kraepelin *state, enum pbl_kraepelin_activity activity)
	Get the last minute processed for an activity type.
void	pbl_kraepelin_get_step_activity (struct pbl_kraepelin *state, enum pbl_kraepelin_activity activity, struct pbl_kraepelin_step_activity *step_activity)
	Get the walk or run in progress.
void	pbl_kraepelin_get_sleep_stats (struct pbl_kraepelin *state, struct pbl_kraepelin_sleep_stats *stats)
	Get the ongoing sleep statistics.
void	pbl_kraepelin_enable_activity_tracking (struct pbl_kraepelin *kalg_state, bool enable, pbl_kraepelin_session_cb_t sessions_cb, void *context)
	Enable or disable automatic activity session detection.

Detailed Description

Step counting, sleep and activity session detection.

The algorithm processes accelerometer samples at PBL_KRAEPELIN_SAMPLE_HZ in 5 second epochs (125 samples). For each epoch it computes the FFT and the VMC (vector magnitude counts, a measure of movement calibrated against the Actigraph) and identifies the stepping frequency, giving the steps of the epoch. Once a minute, the minute stats (VMC, orientation) are fed with the minute's steps, calories and distance to state machines that detect walks, runs, sleep and restful sleep. See the health algorithms page of the architecture documentation for details.

The caller owns the state, of size pbl_kraepelin_state_size():

struct pbl_kraepelin *state = malloc(pbl_kraepelin_state_size());
pbl_kraepelin_init(state, nullptr, nullptr);
 
// For every batch of 25 Hz samples
uint32_t consumed;
steps += pbl_kraepelin_analyze_samples(state, samples, num_samples, &consumed);
 
// Once a minute
uint16_t vmc;
uint8_t orientation;
bool still;
pbl_kraepelin_minute_stats(state, &vmc, &orientation, &still);
pbl_kraepelin_activities_update(state, time(NULL), minute_steps, vmc, orientation, not_worn,
                       resting_cal, active_cal, distance_mm, false, session_cb, ctx);
 
free(state);

---

Data Structure Documentation

pbl_kraepelin_sample

struct pbl_kraepelin_sample

Accelerometer sample, in mG.

Data Fields
int16_t	x
int16_t	y
int16_t	z

pbl_kraepelin_sleep_stats

struct pbl_kraepelin_sleep_stats

Ongoing sleep statistics, returned by pbl_kraepelin_get_sleep_stats().

Data Fields
uint16_t	sleep_len_m	Minutes of that sleep that are certain, 0 if none.
time_t	sleep_start_utc	Start time of a recent sleep session, UTC; 0 if none was detected in the last 60 minutes (minimum sleep session length).
time_t	uncertain_start_utc	Start of the uncertain part of the session, which lasts until now, UTC; 0 if none.

pbl_kraepelin_step_activity

struct pbl_kraepelin_step_activity

Walk or run in progress, returned by pbl_kraepelin_get_step_activity().

Data Fields
bool	active	true if the last minute processed was an active minute of the activity.
uint32_t	len_sec	Time since the start as of the last minute processed, in seconds.
time_t	start_utc	Start time, UTC; 0 if no activity is in progress.

pbl_kraepelin_params

struct pbl_kraepelin_params

Detection parameters that depend on the accelerometer, passed to pbl_kraepelin_init().

Accelerometers with a higher noise floor need higher VMC thresholds.

Data Fields
uint16_t	not_worn_max_low_vmc_run_m	A run of possibly not-worn minutes at least this long, in minutes, is not worn.
uint16_t	not_worn_min_worn_vmc	A minute whose VMC is below this may be a not-worn minute.
uint16_t	sleep_max_avg_vmc	A sleep session whose average VMC is above this is rejected.
uint16_t	sleep_max_minute_score	A minute whose weighted VMC score is at most this is a sleep minute.
uint16_t	sleep_min_valid_vmc	A minute whose VMC is above this counts as an active minute of a sleep session.

Macro Definition Documentation

PBL_KRAEPELIN_MAX_UNCERTAIN_SLEEP_M

#define PBL_KRAEPELIN_MAX_UNCERTAIN_SLEEP_M   19

Maximum delay, in minutes, for the sleep algorithm to detect that the user woke up.

Needed at compile time by the activity algorithm glue, so it is hard-coded; pbl_kraepelin_init() asserts it matches the sleep parameters.

PBL_KRAEPELIN_PARAMS_DEFAULT

#define PBL_KRAEPELIN_PARAMS_DEFAULT

Value:

  {                                    \
    .sleep_max_minute_score = 330,     \
    .sleep_min_valid_vmc = 20,         \
    .sleep_max_avg_vmc = 180,          \
    .not_worn_min_worn_vmc = 4,        \
    .not_worn_max_low_vmc_run_m = 180, \
  }

Default pbl_kraepelin_params initializer.

PBL_KRAEPELIN_SAMPLE_HZ

#define PBL_KRAEPELIN_SAMPLE_HZ   25

Accelerometer sampling rate expected by the algorithm, in Hz.

Typedef Documentation

pbl_kraepelin_session_cb_t

typedef void(* pbl_kraepelin_session_cb_t) (void *context, enum pbl_kraepelin_activity activity_type, time_t start_utc, uint32_t len_sec, bool ongoing, bool delete, uint32_t steps, uint32_t resting_calories, uint32_t active_calories, uint32_t distance_mm)

Callback reporting activity sessions, called by pbl_kraepelin_activities_update().

A session may be reported several times while ongoing, and deleted later.

Parameters

context	Context passed to pbl_kraepelin_activities_update().
activity_type	Activity type.
start_utc	Start time, UTC.
len_sec	Length, in seconds.
ongoing	true if the activity is still ongoing.
delete	true to delete this previously reported session.
steps	Steps taken.
resting_calories	Resting calories (1/1000 kcal) burned.
active_calories	Active calories (1/1000 kcal) burned.
distance_mm	Distance covered, in millimeters.

pbl_kraepelin_stats_cb_t

typedef void(* pbl_kraepelin_stats_cb_t) (uint32_t num_stats, const char **names, int32_t *stats)

Callback receiving algorithm statistics.

Only used during algorithm development, to collect and summarize named statistics.

Parameters

num_stats	Number of elements in names and stats.
names	Statistic names.
stats	Statistic values.

Enumeration Type Documentation

pbl_kraepelin_activity

enum pbl_kraepelin_activity

Activity types reported to pbl_kraepelin_session_cb_t.

Enumerator
PBL_KRAEPELIN_ACTIVITY_SLEEP	Entire sleep session from falling asleep to waking up, containing both light and restful periods.
PBL_KRAEPELIN_ACTIVITY_RESTFUL_SLEEP	Restful period, always inside a PBL_KRAEPELIN_ACTIVITY_SLEEP session.
PBL_KRAEPELIN_ACTIVITY_WALK	Walk of significant length.
PBL_KRAEPELIN_ACTIVITY_RUN	Run.
PBL_KRAEPELIN_ACTIVITY_COUNT	Number of activity types.

Function Documentation

pbl_kraepelin_activities_update()

void pbl_kraepelin_activities_update	(	struct pbl_kraepelin *	state,
		time_t	utc_now,
		uint16_t	steps,
		uint16_t	vmc,
		uint8_t	orientation,
		bool	definitely_not_worn,
		uint32_t	resting_calories,
		uint32_t	active_calories,
		uint32_t	distance_mm,
		bool	shutting_down,
		pbl_kraepelin_session_cb_t	sessions_cb,
		void *	context
	)

Feed a minute of data to the walk, run and sleep detectors.

Does nothing while activity tracking is disabled. A UTC time jump (backwards, or more than 5 minutes forward) resets the detectors.

Parameters

state	State passed to pbl_kraepelin_init().
utc_now	Current UTC time.
steps	Steps taken in the last minute.
vmc	VMC of the last minute.
orientation	Average orientation of the last minute.
definitely_not_worn	true if the watch is definitely not worn this minute (on the charger, or a recent off-wrist heart rate reading); a hard not-worn signal for sleep detection.
resting_calories	Resting calories (1/1000 kcal) burned in the last minute.
active_calories	Active calories (1/1000 kcal) burned in the last minute.
distance_mm	Distance covered in the last minute, in millimeters.
shutting_down	true to force all ongoing activities to end.
sessions_cb	Called for every session found.
context	Passed to sessions_cb.

pbl_kraepelin_activity_last_processed_time()

time_t pbl_kraepelin_activity_last_processed_time	(	struct pbl_kraepelin *	state,
		enum pbl_kraepelin_activity	activity
	)

Get the last minute processed for an activity type.

Parameters

state	State passed to pbl_kraepelin_init().
activity	Activity type.

Returns

UTC time of the minute.

pbl_kraepelin_analyze_finish_epoch()

uint32_t pbl_kraepelin_analyze_finish_epoch

(

struct pbl_kraepelin *

state

)

Process the partial epoch not yet processed by pbl_kraepelin_analyze_samples() (unit tests).

Parameters

state

State passed to pbl_kraepelin_init().

Returns

Steps counted.

pbl_kraepelin_analyze_samples()

uint32_t pbl_kraepelin_analyze_samples	(	struct pbl_kraepelin *	state,
		const struct pbl_kraepelin_sample *	samples,
		uint32_t	num_samples,
		uint32_t *	consumed_samples
	)

Analyze accelerometer samples.

Samples are buffered until a full epoch is available.

Parameters

	state	State passed to pbl_kraepelin_init().
	samples	Samples, in mG, at PBL_KRAEPELIN_SAMPLE_HZ.
	num_samples	Number of samples in samples.
[out]	consumed_samples	Number of samples just processed to compute steps: an epoch (125) when one completed, 0 otherwise.

Returns

Steps counted.

pbl_kraepelin_enable_activity_tracking()

void pbl_kraepelin_enable_activity_tracking	(	struct pbl_kraepelin *	kalg_state,
		bool	enable,
		pbl_kraepelin_session_cb_t	sessions_cb,
		void *	context
	)

Enable or disable automatic activity session detection.

Ends the step activities in progress and resets the detectors.

Parameters

kalg_state	State passed to pbl_kraepelin_init().
enable	true to detect sessions, false to stop.
sessions_cb	Called for each step activity ended.
context	Passed to sessions_cb.

pbl_kraepelin_get_sleep_stats()

void pbl_kraepelin_get_sleep_stats	(	struct pbl_kraepelin *	state,
		struct pbl_kraepelin_sleep_stats *	stats
	)

Get the ongoing sleep statistics.

Parameters

	state	State passed to pbl_kraepelin_init().
[out]	stats	Sleep statistics.

pbl_kraepelin_get_step_activity()

void pbl_kraepelin_get_step_activity	(	struct pbl_kraepelin *	state,
		enum pbl_kraepelin_activity	activity,
		struct pbl_kraepelin_step_activity *	step_activity
	)

Get the walk or run in progress.

An activity is in progress from its first active minute, before it is long enough to be reported to pbl_kraepelin_session_cb_t, until it ends.

Parameters

	state	State passed to pbl_kraepelin_init().
	activity	PBL_KRAEPELIN_ACTIVITY_WALK or PBL_KRAEPELIN_ACTIVITY_RUN.
[out]	step_activity	Activity in progress.

pbl_kraepelin_init()

bool pbl_kraepelin_init	(	struct pbl_kraepelin *	state,
		const struct pbl_kraepelin_params *	params,
		pbl_kraepelin_stats_cb_t	stats_cb
	)

Initialize the algorithm state.

Parameters

state	State, of pbl_kraepelin_state_size() bytes.
params	Detection parameters, copied; NULL for PBL_KRAEPELIN_PARAMS_DEFAULT.
stats_cb	If not NULL, called with statistics while analyzing samples.

Returns

true on success.

pbl_kraepelin_minute_stats()

void pbl_kraepelin_minute_stats	(	struct pbl_kraepelin *	state,
		uint16_t *	vmc,
		uint8_t *	orientation,
		bool *	still
	)

Get the last minute's stats and reset them for the next minute.

The minute stats are logged and used to compute sleep.

Parameters

	state	State passed to pbl_kraepelin_init().
[out]	vmc	VMC (vector magnitude counts) of the minute.
[out]	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.
[out]	still	true if no movement above the noise threshold was detected (currently always false).

pbl_kraepelin_state_size()

uint32_t pbl_kraepelin_state_size

(

void

)

Get the size of the algorithm state.

Returns

Size of the state, in bytes.