RTC

Real-time clock: wall clock time, tick counter, wake-up alarm and timezone storage. More...

Macros
#define	RTC_TICKS_HZ   (1024u)
	Tick frequency in Hz.
#define	TIME_STRING_BUFFER_SIZE   26
	Size of the buffers passed to rtc_get_time_string() and time_t_to_string().

Typedefs
typedef uint64_t	RtcTicks
	RTC tick count.

Functions
void	rtc_init (void)
	Initialize the RTC.
void	rtc_calibrate_frequency (uint32_t frequency)
	Calibrate the RTC.
void	rtc_init_timers (void)
	Start the timers the RTC driver needs.
bool	rtc_sanitize_struct_tm (struct tm *t)
	Clamp the year of a broken-down time to 2000-2037.
bool	rtc_sanitize_time_t (time_t *t)
	Clamp the year of a time to 2000-2037, as rtc_sanitize_struct_tm().
void	rtc_set_time (time_t time)
	Set the current time.
time_t	rtc_get_time (void)
	Get the current time.
void	rtc_set_time_tm (struct tm *time_tm)
	Set the current time from a broken-down time.
void	rtc_get_time_tm (struct tm *time_tm)
	Get the current time as a broken-down local time.
void	rtc_get_time_ms (time_t *out_seconds, uint16_t *out_ms)
	Get the current time with millisecond resolution.
void	rtc_set_timezone (TimezoneInfo *tzinfo)
	Store the timezone in storage that survives reboots.
void	rtc_get_timezone (TimezoneInfo *tzinfo)
	Load the stored timezone.
uint16_t	rtc_get_timezone_id (void)
	Get the stored timezone region ID.
bool	rtc_is_timezone_set (void)
	Check whether a timezone is stored.
const char *	rtc_get_time_string (char *buffer)
	Format the current local time.
RtcTicks	rtc_get_ticks (void)
	Get the tick count.
void	rtc_alarm_init (void)
	Initialize the RTC alarm, used to wake from stop mode.
void	rtc_alarm_set (RtcTicks num_ticks)
	Arm the alarm.
void	rtc_timezone_clear (void)
	Clear the stored timezone, as part of a factory reset.
RtcTicks	rtc_alarm_get_elapsed_ticks (void)
	Get the ticks elapsed since the alarm was last set.
bool	rtc_alarm_is_initialized (void)
	Check whether the alarm is initialized.
const char *	time_t_to_string (char *buffer, time_t t)
	Format a time as local time.

Detailed Description

Real-time clock: wall clock time, tick counter, wake-up alarm and timezone storage.

Wall clock time is UTC, limited to years 2000 to 2037. Ticks count at RTC_TICKS_HZ since system start.

char buf[TIME_STRING_BUFFER_SIZE];
time_t now = rtc_get_time();
 
PBL_LOG_DBG("%s", time_t_to_string(buf, now));
 
RtcTicks start = rtc_get_ticks();
do_work();
uint32_t elapsed_ms = (rtc_get_ticks() - start) * 1000 / RTC_TICKS_HZ;

Macro Definition Documentation

RTC_TICKS_HZ

#define RTC_TICKS_HZ   (1024u)

Tick frequency in Hz.

TIME_STRING_BUFFER_SIZE

#define TIME_STRING_BUFFER_SIZE   26

Size of the buffers passed to rtc_get_time_string() and time_t_to_string().

Typedef Documentation

RtcTicks

typedef uint64_t RtcTicks

RTC tick count.

Function Documentation

rtc_alarm_get_elapsed_ticks()

RtcTicks rtc_alarm_get_elapsed_ticks

(

void

)

Get the ticks elapsed since the alarm was last set.

Returns

Ticks since the last rtc_alarm_set().

rtc_alarm_init()

void rtc_alarm_init

(

void

)

Initialize the RTC alarm, used to wake from stop mode.

rtc_alarm_is_initialized()

bool rtc_alarm_is_initialized

(

void

)

Check whether the alarm is initialized.

Used to avoid entering stop mode before the alarm can wake the system.

Returns

true if initialized.

rtc_alarm_set()

void rtc_alarm_set

(

RtcTicks

num_ticks

)

Arm the alarm.

Parameters

num_ticks

Ticks from now until the alarm fires.

rtc_calibrate_frequency()

void rtc_calibrate_frequency

(

uint32_t

frequency

)

Calibrate the RTC.

Separate from rtc_init() because the manufacturing registry is not available that early.

Parameters

frequency

Measured crystal frequency in mHz.

rtc_get_ticks()

RtcTicks rtc_get_ticks

(

void

)

Get the tick count.

Returns

Ticks since system start.

rtc_get_time()

time_t rtc_get_time

(

void

)

Get the current time.

Returns

UTC time in seconds since the epoch.

rtc_get_time_ms()

void rtc_get_time_ms	(	time_t *	out_seconds,
		uint16_t *	out_ms
	)

Get the current time with millisecond resolution.

Parameters

[out]	out_seconds	Current time in seconds.
[out]	out_ms	Millisecond part of the current second.

rtc_get_time_string()

const char * rtc_get_time_string

(

char *

buffer

)

Format the current local time.

Parameters

[out]

buffer

Buffer of at least TIME_STRING_BUFFER_SIZE bytes.

Returns

buffer.

rtc_get_time_tm()

void rtc_get_time_tm

(

struct tm *

time_tm

)

Get the current time as a broken-down local time.

Parameters

[out]

time_tm

Current time.

rtc_get_timezone()

void rtc_get_timezone

(

TimezoneInfo *

tzinfo

)

Load the stored timezone.

Parameters

[out]

tzinfo

Timezone.

rtc_get_timezone_id()

uint16_t rtc_get_timezone_id

(

void

)

Get the stored timezone region ID.

Returns

Timezone region (Olson) index.

rtc_init()

void rtc_init

(

void

)

Initialize the RTC.

Runs very early during startup, when few other systems are available.

rtc_init_timers()

void rtc_init_timers

(

void

)

Start the timers the RTC driver needs.

Separate from rtc_init() because the timer system is not available that early.

rtc_is_timezone_set()

bool rtc_is_timezone_set

(

void

)

Check whether a timezone is stored.

Without one, the RTC runs in UTC.

Returns

true if a timezone is set.

rtc_sanitize_struct_tm()

bool rtc_sanitize_struct_tm

(

struct tm *

t

)

Clamp the year of a broken-down time to 2000-2037.

Other fields are left untouched.

Parameters

[in,out]

t

Time to clamp.

Returns

true if t was changed.

rtc_sanitize_time_t()

bool rtc_sanitize_time_t

(

time_t *

t

)

Clamp the year of a time to 2000-2037, as rtc_sanitize_struct_tm().

Parameters

[in,out]

t

Time to clamp.

Returns

true if t was changed.

rtc_set_time()

void rtc_set_time

(

time_t

time

)

Set the current time.

Times outside the years 2000 to 2037 are not supported.

Parameters

time	UTC time in seconds since the epoch.

rtc_set_time_tm()

void rtc_set_time_tm

(

struct tm *

time_tm

)

Set the current time from a broken-down time.

Parameters

time_tm

Time to set.

rtc_set_timezone()

void rtc_set_timezone

(

TimezoneInfo *

tzinfo

)

Store the timezone in storage that survives reboots.

Parameters

tzinfo

Timezone.

rtc_timezone_clear()

void rtc_timezone_clear

(

void

)

Clear the stored timezone, as part of a factory reset.

time_t_to_string()

const char * time_t_to_string	(	char *	buffer,
		time_t	t
	)

Format a time as local time.

Parameters

[out]	buffer	Buffer of at least TIME_STRING_BUFFER_SIZE bytes.
	t	Time to format.

Returns

buffer.