Wall-Clock Time Helper Functions

Common functions to access the wall-clock / real time clock. More...

Detailed Description

Common functions to access the wall-clock / real time clock.

         Use these functions to access system time, don't directly use the
         `periph_rtc` API.
         This allows to write applications that are independent of the RTC
         peripheral and allows the implementation of on-time change callbacks.

Note

The values used for setting and getting the time/alarm should conform to the struct tm specification. Compare: http://pubs.opengroup.org/onlinepubs/7908799/xsh/time.h.html

Files
file	walltime.h

Data Structures
struct	walltime_change_sub_t
	Time change notification subscription. More...

Typedefs
typedef void(*	walltime_change_cb_t) (void *ctx, int32_t diff_sec, int16_t diff_ms)
	Time change notification callback.

Functions
void	walltime_change_subscribe (walltime_change_sub_t *sub)
	Add a time change notification subscription This will be called whenever the system time changes.
bool	walltime_change_unsubscribe (walltime_change_sub_t *sub)
	Remove a time change notification subscription.
int	walltime_set (struct tm *time)
	Set the system date / time.
int	walltime_get (struct tm *time, uint16_t *ms)
	Get the system date / time.
uint32_t	walltime_get_riot (uint16_t *ms)
	Get the current system time in seconds since RIOT_EPOCH.
time_t	walltime_get_unix (uint16_t *ms)
	Get the current system time in seconds since 01.01.1970.
uint32_t	walltime_uptime (bool full)
	Get seconds elapsed since last reset.
void	walltime_impl_init (void)
	Backend implementation init, only implement when necessary.
int	walltime_impl_set (struct tm *time)
	Backend implementation to set the system time.
int	walltime_impl_get (struct tm *time, uint16_t *ms)
	Backend implementation to get the system time.

Typedef Documentation

walltime_change_cb_t

typedef void(* walltime_change_cb_t) (void *ctx, int32_t diff_sec, int16_t diff_ms)

Time change notification callback.

Parameters

[in,out]	ctx	User supplied context
[in]	diff_sec	seconds portion of the time change
[in]	diff_ms	millisecond portion of the time change

Definition at line 43 of file walltime.h.

Function Documentation

walltime_change_subscribe()

void walltime_change_subscribe

(

walltime_change_sub_t *

sub

)

Add a time change notification subscription This will be called whenever the system time changes.

Note

sub must remain valid as long as the subscription is active.

Parameters

[in]

sub

The time change notify subscription to add

walltime_change_unsubscribe()

bool walltime_change_unsubscribe

(

walltime_change_sub_t *

sub

)

Remove a time change notification subscription.

Parameters

[in]

sub

The time change notify subscription to remove

Return values

true	The subscription was removed
false	The subscription could not be found

walltime_get()

int walltime_get	(	struct tm *	time,
		uint16_t *	ms )

Get the system date / time.

Parameters

[out]	time	current time output
[out]	ms	current milliseconds output, may be NULL always returns 0 if the backend supports no millisecond resolution

Returns

0 on success

-ERANGE if the difference to the current time is too large

walltime_get_riot()

uint32_t walltime_get_riot

(

uint16_t *

ms

)

Get the current system time in seconds since RIOT_EPOCH.

Parameters

[out]

ms

current milliseconds output, may be NULL always returns 0 if the backend supports no millisecond resolution

Returns

seconds since RIOT_EPOCH

walltime_get_unix()

time_t walltime_get_unix

(

uint16_t *

ms

)

Get the current system time in seconds since 01.01.1970.

Parameters

[out]

ms

current milliseconds output, may be NULL always returns 0 if the backend supports no millisecond resolution

Returns

seconds since 01.01.1970

walltime_impl_get()

int walltime_impl_get	(	struct tm *	time,
		uint16_t *	ms )

Backend implementation to get the system time.

Parameters

[out]	time	current time output
[out]	ms	current milliseconds output (will never be NULL)

Returns

0 on success

walltime_impl_set()

int walltime_impl_set

(

struct tm *

time

)

Backend implementation to set the system time.

Parameters

[in]

time

The current data / time to set

Returns

0 on success

walltime_set()

int walltime_set

(

struct tm *

time

)

Set the system date / time.

Parameters

[in]

time

The current data / time to set

Returns

0 on success

-ERANGE if the difference to the current time is too large

walltime_uptime()

uint32_t walltime_uptime

(

bool

full

)

Get seconds elapsed since last reset.

Note

The full option will only have an effect if BACKUP_RAM is available.

Parameters

[in]

full

set to false to get seconds since last (warm) boot / wake-up set to true to get seconds since last cold boot / full reset