RTC

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.

Modules
	Low-Power RTC Memory
	Low-level RTC Memory peripheral driver.
	RTC emulation on top of a RTT

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

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

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

Functions
void	rtc_init (void)
	Initialize RTC module.
int	rtc_set_time (struct tm *time)
	Set RTC to given time.
int	rtc_get_time (struct tm *time)
	Get current RTC time.
int	rtc_get_time_ms (struct tm *time, uint16_t *ms)
	Get current RTC time with sub-second component.
int	rtc_set_alarm (struct tm *time, rtc_alarm_cb_t cb, void *arg)
	Set an alarm for RTC to the specified value.
int	rtc_get_alarm (struct tm *time)
	Gets the current alarm setting.
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.

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 59 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 67 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_get_time_ms()

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

Get current RTC time with sub-second component.

Requires the periph_rtc_ms feature.

Parameters

[out]	time	Pointer to the struct to write the time to.
[out]	ms	Pointer to a variable to hold the microsecond component of the current RTC time.

Returns

0 for success

-1 an error occurred

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.

Note

The driver must be prepared to work with denormalized time values (e.g. seconds > 60). The driver may normalize the value, or just keep it denormalized. In either case, the timeout should occur at the equivalent normalized time.

Return values

0

success

Returns

-EINVAL time was invalid (e.g. in the past, out of range)

<0 other error (negative errno code to indicate cause)

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