32-bit Real Time Counter (RTC32)

See Quick start guide for RTC32 driver.

This is a driver implementation for the XMEGA RTC32.

This driver can be used to keep track of time; setting alarms, with or without function callbacks; initializing and checking the battery backup system.

Minimum allowed alarm time

Due to the RTC32 clock synchronization, there is a minimum alarm time that will generate a interrupt. This minimum time is 2 RTC32 clock cycles.

Also, if a new RTC32 clock cycle is imminent at the time of setting the alarm, there is a risk that it will be missed even with the value 2. If there is a risk that this may occur, it is recommended to use a minimum alarm time of 3.

Modules
	Related Project(s)
	In this section you can find all the projects related to the 32-bit Real Time Counter (RTC32).
	Quick Start Guide(s)
	In this section you can find a list of all Quick Start guides related to the 32-bit Real Time Counter (RTC32).

Macros
#define	CONFIG_RTC32_CLOCK_1024HZ
	Configuration symbol for selecting 1024Hz clock instead of 1Hz. More...
#define	CONFIG_RTC32_COMPARE_INT_LEVEL
	Configuration symbol for interrupt level to use on alarm. More...

Typedefs
typedef void(*	rtc_callback_t )(uint32_t time)
	Callback definition for alarm callback. More...

Enumerations
enum	vbat_status_code {   VBAT_STATUS_OK,   VBAT_STATUS_NO_POWER,   VBAT_STATUS_INIT,   VBAT_STATUS_BBPOR,   VBAT_STATUS_BBBOD,   VBAT_STATUS_XOSCFAIL }
	Battery backup system status codes. More...

Functions
bool	rtc_alarm_has_triggered (void)
	Check if pending alarm has triggered. More...
uint32_t	rtc_get_time (void)
	Get current time. More...
void	rtc_init (void)
	Initialize the 32kHz oscillator and RTC32. More...
void	rtc_set_alarm (uint32_t time)
	Set alarm time. More...
static void	rtc_set_alarm_relative (uint32_t offset)
	Set alarm relative to current time. More...
void	rtc_set_callback (rtc_callback_t callback)
	Set callback to call on alarm. More...
void	rtc_set_time (uint32_t time)
	Set current time. More...
enum vbat_status_code	rtc_vbat_system_check (bool first_time_init)
	Checks battery backup system status. More...

#define CONFIG_RTC32_CLOCK_1024HZ

Configuration symbol for selecting 1024Hz clock instead of 1Hz.

Define this in conf_rtc32.h if 1024Hz clock is desired. Otherwise, leave it undefined.

#define CONFIG_RTC32_COMPARE_INT_LEVEL

Configuration symbol for interrupt level to use on alarm.

Define this in conf_rtc32.h as the desired interrupt level, or leave it undefined to use the default.

typedef void(* rtc_callback_t)(uint32_t time)

Callback definition for alarm callback.

Parameters

time	The time of the alarm

enum vbat_status_code

Battery backup system status codes.

Enumerator
VBAT_STATUS_OK	Backup system is operating and no errors were detected. The backup system is configured and had no issues while main power was lost. Hence, all data stored in the backup domain is valid.
VBAT_STATUS_NO_POWER	No power detected on VBAT. No power was detected on the VBAT pin and therefore all data within the backup system is invalid. The voltage on the VBAT pin is only sampled after a POR of the device, therefore it is not possible to detect any voltage loss on the VBAT pin during normal operation of the device.
VBAT_STATUS_INIT	The backup system must be initialized. A POR was detected on VBAT input, indicating that a supply was connected to the VBAT pin. Since this is also the first start-up of the device, it is necessary to initialize the RTC32.
VBAT_STATUS_BBPOR	A POR was detected on the VBAT input. POR detection also works while the VBAT system is powered from main power, but the detection flag is only latched after a POR of the main system. A POR can happen when the power is lost and restored again on the VBAT pin while main power was also not present, or even when main power was present, but in this case the flag will only be latched after the next POR of the main system. If a POR is detected on VBAT, it should always be treated as if the backup system is in an unknown state, i.e., that all data is invalid.
VBAT_STATUS_BBBOD	A brown-out was detected on the VBAT input. The backup system is in an unknown state and therefore the time in the RTC32 is invalid. This can happen when the voltage on VBAT drops below the brown-out detection level while main power is absent.
VBAT_STATUS_XOSCFAIL	A failure was detected on the oscillator. The oscillator stopped for at least TBD period of time and because of that we can not rely on the RTC time any more. Todo: Determine minimum period for detection of oscillator outage.

bool rtc_alarm_has_triggered

(

void

)

Check if pending alarm has triggered.

Return values

true	Alarm has triggered
false	Alarm is pending

Check if pending alarm has triggered.

Return values

true	Alarm have triggered
false	Alarm is pending

uint32_t rtc_get_time

(

void

)

Get current time.

Returns

Current time value

Current time value

Note

For devices with the errata "RTC Counter value not correctly read after sleep", this can return old values shortly after waking up from sleep.

Without this errata this function can block for up to 1 RTC clock source cycle after waking up from sleep.

void rtc_init

(

void

)

Initialize the 32kHz oscillator and RTC32.

Starts up the 32kHz oscillator in the backup system and initializes the RTC32.

Note

When the backup system is used, the function rtc_vbat_system_check should be called to determine if a re-initialization must be done.

Initialize the 32kHz oscillator and RTC32.

Start up the RTC and start counting from 0

Note

The RTC clock source used by the RTC module should be set up before calling this function.

void rtc_set_alarm

(

uint32_t

time

)

Set alarm time.

Will set absolute time of the alarm that will call the callback function specified by rtc_set_callback on expiration. Alternatively, you may use rtc_alarm_has_triggered to check if the alarm has expired.

Any pending alarm will be overwritten with this function.

Parameters

time	Absolute time value. See also Minimum allowed alarm time

Precondition

Needs interrupts disabled if used from several contexts

Will set absolute alarm time that will call the callback specified by rtc_set_callback on completion. Or possibly use rtc_alarm_has_triggered to check for it.

Any pending alarm will be overwritten with this function.

Parameters

time	Absolute time value. See also Minimum allowed alarm time

Precondition

Needs interrupts disabled if used from several contexts

static void rtc_set_alarm_relative ( uint32_t  offset )

inlinestatic

Set alarm relative to current time.

Parameters

offset

Offset to current time. This is minimum value, so the alarm might happen at up to one time unit later. See also Minimum allowed alarm time

References Assert, rtc_get_time(), and rtc_set_alarm().

Referenced by alarm(), and main().

void rtc_set_callback

(

rtc_callback_t

callback

)

Set callback to call on alarm.

Parameters

callback

Callback function pointer

void rtc_set_time

(

uint32_t

time

)

Set current time.

Parameters

time	Time value to set

enum vbat_status_code rtc_vbat_system_check

(

bool

first_time_startup

)

Checks battery backup system status.

This function should be called once after each reset of the device in order to determine the current battery backup status. This function can not be used to continuously poll the status of the backup system during normal operation since most status flags are only latched during the power up sequence of the device.

Parameters

first_time_startup

Indicates whether or not the VBAT system has been started previously. This should be set to true upon the first call to this function, and false upon later calls. Typically, the value for this parameter should be stored in, e.g., EEPROM, in order to preserve the value when main system power is lost.

Returns

Battery backup system status.

References sysclk_enable_module(), SYSCLK_PORT_GEN, SYSCLK_RTC, VBAT_STATUS_BBBOD, VBAT_STATUS_BBPOR, VBAT_STATUS_INIT, VBAT_STATUS_NO_POWER, VBAT_STATUS_OK, and VBAT_STATUS_XOSCFAIL.