Alarms

User alarms, persisted across resets. More...

Modules
	Alarm pins
	Timeline pins showing alarms.

Data Structures
struct	AlarmInfo
	Alarm configuration. More...

Macros
#define	SMART_ALARM_RANGE_S   (30 * PBL_SEC_PER_MIN)
	How long before its time a smart alarm may go off, in seconds.
#define	SMART_ALARM_SNOOZE_DELAY_S   (1 * PBL_SEC_PER_MIN)
	Interval at which a smart alarm re-checks the sleep state, in seconds.
#define	SMART_ALARM_MAX_LIGHT_SLEEP_S   (30 * PBL_SEC_PER_MIN)
	Light sleep threshold for smart alarms, in seconds.
#define	SMART_ALARM_MAX_SMART_SNOOZE   (SMART_ALARM_RANGE_S / SMART_ALARM_SNOOZE_DELAY_S)
	Number of sleep state checks a smart alarm makes before firing unconditionally.
#define	ALARMS_APP_HIGHLIGHT_COLOR   PBL_IF_COLOR_ELSE(GColorJaegerGreen, GColorBlack)
	Highlight color of the alarms app.
#define	ALARM_INVALID_ID   (-1)
	Invalid alarm ID, returned on failure.

Typedefs
typedef int	AlarmId
	Unique ID of a configured alarm.
typedef void(*	AlarmForEach) (AlarmId id, const AlarmInfo *info, void *context)
	Callback for alarm_for_each().

Enumerations
enum	AlarmKind {   ALARM_KIND_EVERYDAY = 0 , ALARM_KIND_WEEKENDS , ALARM_KIND_WEEKDAYS , ALARM_KIND_JUST_ONCE ,   ALARM_KIND_CUSTOM }
	Recurrence of an alarm. More...
enum	AlarmType { AlarmType_Basic , AlarmType_Smart , AlarmTypeCount }
	Alarm type, as shown on its timeline pin. More...
enum	AlarmTone { AlarmTone_Reveille = 0 , AlarmTone_Beacon , AlarmTone_Bell , AlarmTone_Chime }
	Built-in alarm tones, played on speaker hardware when sound is enabled. More...

Functions
AlarmId	alarm_create (const AlarmInfo *info)
	Create and schedule an alarm.
void	alarm_set_time (AlarmId id, int hour, int minute)
	Set the time of an alarm.
void	alarm_set_kind (AlarmId id, AlarmKind kind)
	Set the recurrence of an alarm.
void	alarm_set_custom (AlarmId id, const bool scheduled_days[PBL_DAY_PER_WEEK])
	Make an alarm run on specific days of the week.
void	alarm_set_smart (AlarmId id, bool smart)
	Set whether an alarm is a smart alarm.
void	alarm_set_sound_enabled (AlarmId id, bool enabled)
	Set whether an alarm plays a tone.
void	alarm_set_vibrate_enabled (AlarmId id, bool enabled)
	Set whether an alarm vibrates.
void	alarm_set_tone (AlarmId id, AlarmTone tone)
	Set the tone of an alarm.
bool	alarm_get_info (AlarmId id, AlarmInfo *info_out)
	Get the configuration of an alarm.
AlarmId	alarm_get_most_recent_id (void)
	Get the most recently fired alarm.
bool	alarm_get_custom_days (AlarmId id, bool scheduled_days[PBL_DAY_PER_WEEK])
	Get the days of the week an alarm runs on.
void	alarm_set_enabled (AlarmId id, bool enable)
	Enable or disable an alarm.
void	alarm_delete (AlarmId id)
	Delete an alarm and its timeline pins.
bool	alarm_get_enabled (AlarmId id)
	Check whether an alarm is enabled.
bool	alarm_get_hours_minutes (AlarmId id, int *hour_out, int *minute_out)
	Get the time of an alarm.
bool	alarm_get_kind (AlarmId id, AlarmKind *kind_out)
	Get the recurrence of an alarm.
bool	alarm_get_next_enabled_alarm (time_t *next_alarm_time_out)
	Get the time of the next enabled alarm.
bool	alarm_is_next_enabled_alarm_smart (void)
	Check whether the next enabled alarm is a smart alarm.
bool	alarm_get_time_until (AlarmId id, time_t *time_out)
	Get the time until an alarm next goes off.
void	alarm_set_snooze_alarm (void)
	Snooze the most recently fired alarm for the current snooze delay.
uint16_t	alarm_get_snooze_delay (void)
	Get the snooze delay.
void	alarm_set_snooze_delay (uint16_t delay_m)
	Set and persist the snooze delay for all alarms.
void	alarm_dismiss_alarm (void)
	Dismiss the most recently fired alarm, cancelling its snooze.
void	alarm_for_each (AlarmForEach cb, void *context)
	Call a function for each configured alarm.
bool	alarm_can_schedule (void)
	Check whether another alarm can be created.
void	alarm_handle_clock_change (void)
	Reschedule all alarms after the wall clock time changed.
void	alarm_init (void)
	Initialize the alarm service.
void	alarm_service_enable_alarms (bool enable)
	Enable or disable alarm events globally.
const char *	alarm_get_string_for_kind (AlarmKind kind, bool all_caps)
	Get the display string of an alarm recurrence, e.g.
void	alarm_get_string_for_custom (bool scheduled_days[PBL_DAY_PER_WEEK], char *alarm_day_text)
	Describe the days of a custom alarm.
void	alarm_prefs_set_alarms_app_opened (uint8_t version)
	Record the version of the alarms app that was last opened.
uint8_t	alarm_prefs_get_alarms_app_opened (void)
	Get the version of the alarms app that was last opened.

Detailed Description

User alarms, persisted across resets.

When an enabled alarm goes off, a PEBBLE_ALARM_CLOCK_EVENT is put and a pin is added to the timeline. Each scheduled alarm also keeps a pin for its next occurrence in the timeline. A smart alarm starts watching for light sleep or movement SMART_ALARM_RANGE_S before its time and fires as soon as the user is awake or moving, or at its time at the latest. Up to 10 alarms can be configured.

const AlarmInfo info = {
  .hour = 7,
  .minute = 30,
  .kind = ALARM_KIND_WEEKDAYS,
  .vibrate_enabled = true,
};
AlarmId id = alarm_create(&info);

---

Data Structure Documentation

AlarmInfo

struct AlarmInfo

Alarm configuration.

Data Fields
bool	enabled	Whether the alarm goes off at its time.
int	hour	Hour, 0-23, where 0 is 12am.
bool	is_smart	Whether the alarm is a smart alarm.
AlarmKind	kind	Recurrence of the alarm.
int	minute	Minute, 0-59.
bool(*	scheduled_days)[PBL_DAY_PER_WEEK]	Days the alarm runs on, one flag per weekday (Sunday = index 0), for ALARM_KIND_CUSTOM. May be NULL.
bool	sound_enabled	Whether the alarm plays a tone on speaker hardware.
AlarmTone	tone	Tone played when sound_enabled is set.
bool	vibrate_enabled	Whether the alarm vibrates.

Macro Definition Documentation

ALARM_INVALID_ID

#define ALARM_INVALID_ID   (-1)

Invalid alarm ID, returned on failure.

ALARMS_APP_HIGHLIGHT_COLOR

#define ALARMS_APP_HIGHLIGHT_COLOR   PBL_IF_COLOR_ELSE(GColorJaegerGreen, GColorBlack)

Highlight color of the alarms app.

SMART_ALARM_MAX_LIGHT_SLEEP_S

#define SMART_ALARM_MAX_LIGHT_SLEEP_S   (30 * PBL_SEC_PER_MIN)

Light sleep threshold for smart alarms, in seconds.

Currently only used by tests.

SMART_ALARM_MAX_SMART_SNOOZE

#define SMART_ALARM_MAX_SMART_SNOOZE   (SMART_ALARM_RANGE_S / SMART_ALARM_SNOOZE_DELAY_S)

Number of sleep state checks a smart alarm makes before firing unconditionally.

SMART_ALARM_RANGE_S

#define SMART_ALARM_RANGE_S   (30 * PBL_SEC_PER_MIN)

How long before its time a smart alarm may go off, in seconds.

SMART_ALARM_SNOOZE_DELAY_S

#define SMART_ALARM_SNOOZE_DELAY_S   (1 * PBL_SEC_PER_MIN)

Interval at which a smart alarm re-checks the sleep state, in seconds.

Typedef Documentation

AlarmForEach

typedef void(* AlarmForEach) (AlarmId id, const AlarmInfo *info, void *context)

Callback for alarm_for_each().

Parameters

id	Alarm ID.
info	Alarm configuration, valid during the call only.
context	Context passed to alarm_for_each().

AlarmId

typedef int AlarmId

Unique ID of a configured alarm.

Enumeration Type Documentation

AlarmKind

enum AlarmKind

Recurrence of an alarm.

Enumerator
ALARM_KIND_EVERYDAY	Every day.
ALARM_KIND_WEEKENDS	Saturday and Sunday.
ALARM_KIND_WEEKDAYS	Monday to Friday.
ALARM_KIND_JUST_ONCE	The next time the specified time occurs; the alarm is disabled once it fires.
ALARM_KIND_CUSTOM	The specified days of the week.

AlarmTone

enum AlarmTone

Built-in alarm tones, played on speaker hardware when sound is enabled.

Enumerator
AlarmTone_Reveille	Reveille.
AlarmTone_Beacon	Beacon.
AlarmTone_Bell	Bell.
AlarmTone_Chime	Chime.

AlarmType

enum AlarmType

Alarm type, as shown on its timeline pin.

Enumerator
AlarmType_Basic	Regular alarm.
AlarmType_Smart	Smart alarm.
AlarmTypeCount	Number of alarm types.

Function Documentation

alarm_can_schedule()

bool alarm_can_schedule

(

void

)

Check whether another alarm can be created.

Returns

true if the maximum number of alarms has not been reached.

alarm_create()

AlarmId alarm_create

(

const AlarmInfo *

info

)

Create and schedule an alarm.

The alarm is created enabled, whatever AlarmInfo::enabled says.

Parameters

info	Alarm configuration. scheduled_days is used for ALARM_KIND_CUSTOM.

Returns

ID of the new alarm, or ALARM_INVALID_ID on failure.

alarm_delete()

void alarm_delete

(

AlarmId

id

)

Delete an alarm and its timeline pins.

Parameters

id	Alarm to delete.

alarm_dismiss_alarm()

void alarm_dismiss_alarm

(

void

)

Dismiss the most recently fired alarm, cancelling its snooze.

alarm_for_each()

void alarm_for_each	(	AlarmForEach	cb,
		void *	context
	)

Call a function for each configured alarm.

Parameters

cb	Callback, called with the alarm settings file locked.
context	Passed to cb.

alarm_get_custom_days()

bool alarm_get_custom_days	(	AlarmId	id,
		bool	scheduled_days[PBL_DAY_PER_WEEK]
	)

Get the days of the week an alarm runs on.

Parameters

	id	Alarm to look up.
[out]	scheduled_days	One flag per weekday (Sunday = index 0), set for each day the alarm runs on.

Returns

true if the alarm exists.

alarm_get_enabled()

bool alarm_get_enabled

(

AlarmId

id

)

Check whether an alarm is enabled.

Parameters

id	Alarm to query.

Returns

true if the alarm exists and is enabled.

alarm_get_hours_minutes()

bool alarm_get_hours_minutes	(	AlarmId	id,
		int *	hour_out,
		int *	minute_out
	)

Get the time of an alarm.

Parameters

	id	Alarm to query.
[out]	hour_out	Hour of the alarm, may be NULL.
[out]	minute_out	Minute of the alarm, may be NULL.

Returns

true if the alarm exists.

alarm_get_info()

bool alarm_get_info	(	AlarmId	id,
		AlarmInfo *	info_out
	)

Get the configuration of an alarm.

Parameters

	id	Alarm to look up.
[out]	info_out	Configuration. Its scheduled_days is set to NULL; use alarm_get_custom_days() for the per-weekday flags.

Returns

true if the alarm exists.

alarm_get_kind()

bool alarm_get_kind	(	AlarmId	id,
		AlarmKind *	kind_out
	)

Get the recurrence of an alarm.

Parameters

	id	Alarm to query.
[out]	kind_out	Recurrence of the alarm, may be NULL.

Returns

true if the alarm exists.

alarm_get_most_recent_id()

AlarmId alarm_get_most_recent_id

(

void

)

Get the most recently fired alarm.

Used by the alarm popup to look up the settings of the firing alarm.

Returns

ID of the most recently fired alarm, or ALARM_INVALID_ID if none fired since boot (or it was since disabled or deleted).

alarm_get_next_enabled_alarm()

bool alarm_get_next_enabled_alarm

(

time_t *

next_alarm_time_out

)

Get the time of the next enabled alarm.

Parameters

[out]

next_alarm_time_out

Time of the next alarm, may be NULL.

Returns

true if at least one alarm is scheduled.

alarm_get_snooze_delay()

uint16_t alarm_get_snooze_delay

(

void

)

Get the snooze delay.

Returns

Snooze delay in minutes.

alarm_get_string_for_custom()

void alarm_get_string_for_custom	(	bool	scheduled_days[PBL_DAY_PER_WEEK],
		char *	alarm_day_text
	)

Describe the days of a custom alarm.

For example "Mondays" for one day, or "Mon,Sat,Sun" for several, translated and starting on Monday.

Parameters

	scheduled_days	One flag per weekday (Sunday = index 0).
[in,out]	alarm_day_text	Buffer of at least 28 bytes holding an empty string; the text is appended to it.

alarm_get_string_for_kind()

const char * alarm_get_string_for_kind	(	AlarmKind	kind,
		bool	all_caps
	)

Get the display string of an alarm recurrence, e.g.

"Weekends".

Parameters

kind	Recurrence.
all_caps	Whether to return the all-caps variant.

Returns

Untranslated string, to be passed through i18n.

alarm_get_time_until()

bool alarm_get_time_until	(	AlarmId	id,
		time_t *	time_out
	)

Get the time until an alarm next goes off.

Parameters

	id	Alarm to query.
[out]	time_out	Seconds until the next occurrence of the alarm, may be NULL.

Returns

true if the alarm exists.

alarm_handle_clock_change()

void alarm_handle_clock_change

(

void

)

Reschedule all alarms after the wall clock time changed.

Required because alarm timers count seconds rather than absolute times. A smart alarm near its deadline is fired; other snoozes are left running.

alarm_init()

void alarm_init

(

void

)

Initialize the alarm service.

Loads the alarms and the snooze delay, and detects an alarm missed while the watch was down.

alarm_is_next_enabled_alarm_smart()

bool alarm_is_next_enabled_alarm_smart

(

void

)

Check whether the next enabled alarm is a smart alarm.

Returns

true if an alarm is scheduled and the next one is smart.

alarm_prefs_get_alarms_app_opened()

uint8_t alarm_prefs_get_alarms_app_opened

(

void

)

Get the version of the alarms app that was last opened.

Returns

Alarms app version.

alarm_prefs_set_alarms_app_opened()

void alarm_prefs_set_alarms_app_opened

(

uint8_t

version

)

Record the version of the alarms app that was last opened.

Parameters

version

Alarms app version.

alarm_service_enable_alarms()

void alarm_service_enable_alarms

(

bool

enable

)

Enable or disable alarm events globally.

While disabled, alarms are still scheduled but put no events. Enabling fires an alarm missed while the watch was down, if it is at most a few minutes late.

Parameters

enable

Whether alarms may go off.

alarm_set_custom()

void alarm_set_custom	(	AlarmId	id,
		const bool	scheduled_days[PBL_DAY_PER_WEEK]
	)

Make an alarm run on specific days of the week.

Sets the kind to ALARM_KIND_CUSTOM.

Parameters

id	Alarm to update.
scheduled_days	One flag per weekday (Sunday = index 0); the alarm runs on each day set.

alarm_set_enabled()

void alarm_set_enabled	(	AlarmId	id,
		bool	enable
	)

Enable or disable an alarm.

Disabling the most recently fired alarm cancels its snooze.

Parameters

id	Alarm to update.
enable	Whether to enable the alarm.

alarm_set_kind()

void alarm_set_kind	(	AlarmId	id,
		AlarmKind	kind
	)

Set the recurrence of an alarm.

Parameters

id	Alarm to update.
kind	New recurrence. ALARM_KIND_CUSTOM is ignored, use alarm_set_custom().

alarm_set_smart()

void alarm_set_smart	(	AlarmId	id,
		bool	smart
	)

Set whether an alarm is a smart alarm.

Parameters

id	Alarm to update.
smart	Whether the alarm is a smart alarm.

alarm_set_snooze_alarm()

void alarm_set_snooze_alarm

(

void

)

Snooze the most recently fired alarm for the current snooze delay.

alarm_set_snooze_delay()

void alarm_set_snooze_delay

(

uint16_t

delay_m

)

Set and persist the snooze delay for all alarms.

Parameters

delay_m

Snooze delay in minutes.

alarm_set_sound_enabled()

void alarm_set_sound_enabled	(	AlarmId	id,
		bool	enabled
	)

Set whether an alarm plays a tone.

Parameters

id	Alarm to update.
enabled	Whether the alarm plays a tone on speaker hardware.

alarm_set_time()

void alarm_set_time	(	AlarmId	id,
		int	hour,
		int	minute
	)

Set the time of an alarm.

Parameters

id	Alarm to update.
hour	Hour, 0-23, where 0 is 12am.
minute	Minute, 0-59.

alarm_set_tone()

void alarm_set_tone	(	AlarmId	id,
		AlarmTone	tone
	)

Set the tone of an alarm.

Parameters

id	Alarm to update.
tone	Tone to play when sound is enabled.

alarm_set_vibrate_enabled()

void alarm_set_vibrate_enabled	(	AlarmId	id,
		bool	enabled
	)

Set whether an alarm vibrates.

Parameters

id	Alarm to update.
enabled	Whether the alarm vibrates.