Loading...
Searching...
No Matches

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]argoptional 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]timePointer 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]timePointer 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]timePointer to the struct to write the time to.
[out]msPointer 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]timeThe value to trigger an alarm when hit.
[in]cbCallback executed when alarm is hit.
[in]argArgument 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
0success
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]timePointer to the struct holding the time to set.
Returns
0 for success
-1 an error occurred