Low-level RTC (Real Time Clock) peripheral driver. More...

Detailed Description

Low-level RTC (Real Time Clock) peripheral driver.

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

(Low-) Power Implications

After the RTC has been initialized (i.e. after calling rtc_init()), the RTC should be powered on and running. The RTC can then be powered off manually at a later point in time by calling the rtc_poweroff() function. When the RTC is powered back on using the rtc_poweron() function, it should transparently continue its previously configured operation.

On many CPUs, certain power states might need to be blocked in rtc_init(), so that it is ensured that the RTC will function properly while it is enabled.

Files
file	rtc.h
	Low-level RTC peripheral driver interface definitions.

Macros
#define	RIOT_EPOCH (2020)
	Earliest year of the RTC. More...

Typedefs
typedef void(*	rtc_alarm_cb_t) (void *arg)
	Signature for alarm Callback. More...

Functions
void	rtc_init (void)
	Initialize RTC module.

int	rtc_set_time (struct tm *time)
	Set RTC to given time. More...

int	rtc_get_time (struct tm *time)
	Get current RTC time. More...

int	rtc_set_alarm (struct tm time, rtc_alarm_cb_t cb, void arg)
	Set an alarm for RTC to the specified value. More...

int	rtc_get_alarm (struct tm *time)
	Gets the current alarm setting. More...

void	rtc_clear_alarm (void)
	Clear any set alarm, do nothing if nothing set.

void	rtc_poweron (void)
	Turns the RTC hardware module on.

void	rtc_poweroff (void)
	Turns the RTC hardware module off.

void	rtc_tm_normalize (struct tm *time)
	Normalize the time struct. More...

int	rtc_tm_compare (const struct tm a, const struct tm b)
	Compare two time structs. More...

uint32_t	rtc_mktime (struct tm *t)
	Convert time struct into timestamp. More...

void	rtc_localtime (uint32_t time, struct tm *t)
	Converts an RTC timestamp into a time struct. More...

bool	rtc_tm_valid (const struct tm *t)
	Verify that a time struct `t` contains valid data. More...

Macro Definition Documentation

◆ RIOT_EPOCH

#define RIOT_EPOCH (2020)

Earliest year of the RTC.

01.01.$RIOT_EPOCH will be the reset value of the RTC if supported.

Internal RTC helper functions such as rtc_mktime and rtc_localtime will not work on dates earlier than that.

Definition at line 58 of file rtc.h.

Typedef Documentation

◆ rtc_alarm_cb_t

typedef void(* rtc_alarm_cb_t) (void *arg)

Signature for alarm Callback.

Parameters

[in] arg optional argument to put the callback in the right context

Definition at line 66 of file rtc.h.

Function Documentation

◆ rtc_get_alarm()

int rtc_get_alarm ( struct tm * time )

Gets the current alarm setting.

Parameters

[out] time Pointer to structure to receive alarm time

Returns: 0 for success; -1 an error occurred

◆ rtc_get_time()

int rtc_get_time ( struct tm * time )

Get current RTC time.

Parameters

[out] time Pointer to the struct to write the time to.

Returns: 0 for success; -1 an error occurred

◆ rtc_localtime()

void rtc_localtime	(	uint32_t	time,
		struct tm *	t
	)

Converts an RTC timestamp into a time struct.

Parameters

[in]	time	elapsed seconds since `RIOT_EPOCH`
[out]	t	the corresponding timestamp

◆ rtc_mktime()

uint32_t rtc_mktime ( struct tm * t )

Convert time struct into timestamp.

Precondition: The time structs a and b are assumed to be normalized. Use rtc_tm_normalize to normalize a struct tm that has been manually edited.

Parameters

[in] t The time struct to convert

Returns: elapsed seconds since RIOT_EPOCH

◆ rtc_set_alarm()

int rtc_set_alarm	(	struct tm *	time,
		rtc_alarm_cb_t	cb,
		void *	arg
	)

Set an alarm for RTC to the specified value.

Note: Any already set alarm will be overwritten.

Parameters

[in]	time	The value to trigger an alarm when hit.
[in]	cb	Callback executed when alarm is hit.
[in]	arg	Argument passed to callback when alarm is hit.

Returns: 0 for success; -2 invalid time parameter; -1 other errors

◆ rtc_set_time()

int rtc_set_time ( struct tm * time )

Set RTC to given time.

Parameters

[in] time Pointer to the struct holding the time to set.

Returns: 0 for success; -1 an error occurred

◆ rtc_tm_compare()

int rtc_tm_compare	(	const struct tm *	a,
		const struct tm *	b
	)

Compare two time structs.

Precondition: The time structs a and b are assumed to be normalized. Use rtc_tm_normalize to normalize a struct tm that has been manually edited.

Parameters

[in]	a	The first time struct.
[in]	b	The second time struct.

Returns: an integer < 0 if a is earlier than b; an integer > 0 if a is later than b; 0 if a and b are equal

◆ rtc_tm_normalize()

void rtc_tm_normalize ( struct tm * time )

Normalize the time struct.

Note: The function modifies the fields of the tm structure as follows: If structure members are outside their valid interval, they will be normalized. So that, for example, 40 October is changed into 9 November.

If RTC_NORMALIZE_COMPAT is 1 tm_wday and tm_yday are set to values determined from the contents of the other fields.

Parameters

time	Pointer to the struct to normalize.

◆ rtc_tm_valid()

bool rtc_tm_valid ( const struct tm * t )

Verify that a time struct t contains valid data.

Note: This function checks whether the fields of the struct t are positive and within the bounds set by rtc_tm_normalize.

Parameters

[in] t The struct to be checked.

Returns: true when valid, false if not

Detailed Description

(Low-) Power Implications

Files

Macros

Typedefs

Functions

Macro Definition Documentation

◆ RIOT_EPOCH

Typedef Documentation

◆ rtc_alarm_cb_t

Function Documentation

◆ rtc_get_alarm()

◆ rtc_get_time()

◆ rtc_localtime()

◆ rtc_mktime()

◆ rtc_set_alarm()

◆ rtc_set_time()

◆ rtc_tm_compare()

◆ rtc_tm_normalize()

◆ rtc_tm_valid()