gossamer 0.0.1
a very lightweight app framework for SAMD and SAML chips
Loading...
Searching...
No Matches
Real-Time Clock

Functions for configuring and using the Real-Time Clock peripheral. More...

Data Structures

union  rtc_date_time_t
 

Macros

#define RTC_REFERENCE_YEAR   (2020)
 

Typedefs

typedef enum rtc_alarm_match_t rtc_alarm_match_t
 
typedef void(* rtc_cb_t) (uint16_t intflag)
 

Enumerations

enum  rtc_alarm_match_t { ALARM_MATCH_DISABLED = 0 , ALARM_MATCH_SS , ALARM_MATCH_MMSS , ALARM_MATCH_HHMMSS }
 

Functions

void rtc_init (void)
 Initializes the RTC.
 
void rtc_enable (void)
 Enables the RTC.
 
bool rtc_is_enabled (void)
 Checks if the RTC is enabled.
 
void rtc_set_date_time (rtc_date_time_t date_time)
 Sets the date and time.
 
rtc_date_time_t rtc_get_date_time (void)
 Returns the date and time.
 
void rtc_enable_alarm_interrupt (rtc_date_time_t alarm_time, rtc_alarm_match_t mask)
 Enables the alarm interrupt.
 
void rtc_disable_alarm_interrupt (void)
 Disables the alarm callback.
 
void rtc_enable_periodic_interrupt (uint8_t index)
 Enables a periodic interval interrupt.
 
void rtc_disable_periodic_interrupt (uint8_t index)
 Disables a periodic interval interrupt.
 
void rtc_enable_overflow_interrupt (void)
 Enables the overflow interrupt.
 
void rtc_disable_overflow_interrupt (void)
 Disables the overflow interrupt.
 
void rtc_configure_callback (rtc_cb_t callback)
 Configures the RTC alarm callback.
 
void rtc_enable_periodic_event_output (uint8_t index, bool enabled)
 Enables or disables a periodic interval event output.
 
void rtc_enable_alarm_event_output (bool enabled)
 Enables or disables the alarm event output.
 
void rtc_enable_overflow_event_output (bool enabled)
 Enables or disables the overflow event output.
 

Detailed Description

Functions for configuring and using the Real-Time Clock peripheral.

Gossamer supports use of the RTC peripheral in MODE2 (calendar) mode only.

Function Documentation

◆ rtc_configure_callback()

void rtc_configure_callback ( rtc_cb_t callback)

Configures the RTC alarm callback.

Parameters
callbackThe function to call when an RTC interrupt occurs. The callback will be passed a bitmask of the interrupt flags, the full contents of the RTC peripheral's INTFLAG register.

◆ rtc_disable_periodic_interrupt()

void rtc_disable_periodic_interrupt ( uint8_t index)

Disables a periodic interval interrupt.

Parameters
indexThe periodic interval (0-7).

◆ rtc_enable_alarm_event_output()

void rtc_enable_alarm_event_output ( bool enabled)

Enables or disables the alarm event output.

Parameters
enabledtrue to enable, false to disable.

◆ rtc_enable_alarm_interrupt()

void rtc_enable_alarm_interrupt ( rtc_date_time_t alarm_time,
rtc_alarm_match_t mask )

Enables the alarm interrupt.

Parameters
alarm_timeThe time that you wish to match. The date is currently ignored.
maskOne of the values in rtc_alarm_match_t indicating which values to check.

◆ rtc_enable_overflow_event_output()

void rtc_enable_overflow_event_output ( bool enabled)

Enables or disables the overflow event output.

Parameters
enabledtrue to enable, false to disable.

◆ rtc_enable_periodic_event_output()

void rtc_enable_periodic_event_output ( uint8_t index,
bool enabled )

Enables or disables a periodic interval event output.

The RTC prescaler generates events on the 0-to-1 transition of its upper eight bits (bits 2-9), producing a periodic event at:

f = fGCLK_RTC / 2^(n+3)

where n is the index (0-7) and fGCLK_RTC is the RTC clock frequency.

With the common gossamer configuration of fGCLK_RTC = 1024 Hz:

  • index 7: 1024 / 1024 = 1 Hz
  • index 6: 1024 / 512 = 2 Hz
  • index 5: 1024 / 256 = 4 Hz
  • index 4: 1024 / 128 = 8 Hz
  • index 3: 1024 / 64 = 16 Hz
  • index 2: 1024 / 32 = 32 Hz
  • index 1: 1024 / 16 = 64 Hz
  • index 0: 1024 / 8 = 128 Hz

Periodic events are available on all chips, but periodic interrupts are only available on L21/L22/D51 (see rtc_enable_periodic_interrupt).

Parameters
indexThe periodic interval (0-7).
enabledtrue to enable, false to disable.

◆ rtc_enable_periodic_interrupt()

void rtc_enable_periodic_interrupt ( uint8_t index)

Enables a periodic interval interrupt.

The callback registered via rtc_configure_callback() will fire with the corresponding PER bit set in the intflag parameter.

Parameters
indexThe periodic interval (0-7).
Note
Only available on SAM L21, L22, and D51. The SAM D11 and D21 support periodic events (via rtc_enable_periodic_event_output) but not periodic interrupts.

◆ rtc_get_date_time()

rtc_date_time_t rtc_get_date_time ( void )

Returns the date and time.

Returns
A rtc_date_time_t with the current date and time, with a year value from 0-63 representing 2020-2083.
See also
rtc_set_date_time for notes about how the year is stored.

◆ rtc_init()

void rtc_init ( void )

Initializes the RTC.

Configures the RTC for 24-hour clock / calendar mode, with a 1 Hz tick derived from the 1024 Hz clock on GCLK3 (for SAM D devices) or OSC32KCTRL's most accurate 1024 Hz output (for SAM L devices).

◆ rtc_is_enabled()

bool rtc_is_enabled ( void )

Checks if the RTC is enabled.

Returns
true if the RTC is enabled; false if not.

◆ rtc_set_date_time()

void rtc_set_date_time ( rtc_date_time_t date_time)

Sets the date and time.

Parameters
date_timeThe date and time you wish to set, with a year value from 0-63 representing 2020-2083.
Note
The RTC stores the year as six bits representing a value from 0 to 63. It treats this as a year offset from a reference year, which must be a leap year. Since 2020 was a leap year, and it allows useful dates through 2083, it is assumed that apps will use 2020 as the reference year; thus 1 means 2021, 2 means 2022, etc. You will be responsible for handling this offset in your code, if the calendar year is needed for timestamp calculation logic or display purposes.