Quick Start Guide for RTC (CAL) - Callback

In this use case, the RTC is set up in calendar mode.

The time is set and an alarm is enabled, as well as a callback for when the alarm time is hit. Each time the callback fires, the alarm time is reset to five seconds in the future and the board LED toggled.

Prerequisites

The Generic Clock Generator for the RTC should be configured and enabled; if you are using the System Clock driver, this may be done via conf_clocks.h.

Clocks and Oscillators

The conf_clock.h file needs to be changed with the different values to configure the clocks and oscillators for the module according to the used device.

For example, the following oscillator settings are needed for SAMD21:

/* SYSTEM_CLOCK_SOURCE_OSC32K configuration - Internal 32KHz oscillator */
#  define CONF_CLOCK_OSC32K_ENABLE                true
#  define CONF_CLOCK_OSC32K_STARTUP_TIME          SYSTEM_OSC32K_STARTUP_130
#  define CONF_CLOCK_OSC32K_ENABLE_1KHZ_OUTPUT    true
#  define CONF_CLOCK_OSC32K_ENABLE_32KHZ_OUTPUT   true
#  define CONF_CLOCK_OSC32K_ON_DEMAND             true
#  define CONF_CLOCK_OSC32K_RUN_IN_STANDBY        false

The following generic clock settings are needed for SAMD21:

/* Configure GCLK generator 2 (RTC) */
#  define CONF_CLOCK_GCLK_2_ENABLE                true
#  define CONF_CLOCK_GCLK_2_RUN_IN_STANDBY        false
#  define CONF_CLOCK_GCLK_2_CLOCK_SOURCE          SYSTEM_CLOCK_SOURCE_OSC32K
#  define CONF_CLOCK_GCLK_2_PRESCALER             32
#  define CONF_CLOCK_GCLK_2_OUTPUT_ENABLE         false

Setup

Code

Create an rtc_module struct and add to the main application source file, outside of any functions:

struct rtc_module rtc_instance;

The following must be added to the user application:

Function for setting up the module:

void configure_rtc_calendar(void)
{
    /* Initialize RTC in calendar mode. */
    struct rtc_calendar_config config_rtc_calendar;
    rtc_calendar_get_config_defaults(&config_rtc_calendar);

    alarm.time.year      = 2013;
    alarm.time.month     = 1;
    alarm.time.day       = 1;
    alarm.time.hour      = 0;
    alarm.time.minute    = 0;
    alarm.time.second    = 4;

    config_rtc_calendar.clock_24h = true;
    config_rtc_calendar.alarm[0].time = alarm.time;
    config_rtc_calendar.alarm[0].mask = RTC_CALENDAR_ALARM_MASK_YEAR;

    rtc_calendar_init(&rtc_instance, RTC, &config_rtc_calendar);

    rtc_calendar_enable(&rtc_instance);
}

Callback function:

void rtc_match_callback(void)
{
    /* Do something on RTC alarm match here */
    port_pin_toggle_output_level(LED_0_PIN);

    /* Set new alarm in 5 seconds */
    alarm.mask = RTC_CALENDAR_ALARM_MASK_SEC;

    alarm.time.second += 5;
    alarm.time.second = alarm.time.second % 60;

    rtc_calendar_set_alarm(&rtc_instance, &alarm, RTC_CALENDAR_ALARM_0);
}

Function for setting up the callback functionality of the driver:

void configure_rtc_callbacks(void)
{
    rtc_calendar_register_callback(
            &rtc_instance, rtc_match_callback, RTC_CALENDAR_CALLBACK_ALARM_0);
    rtc_calendar_enable_callback(&rtc_instance, RTC_CALENDAR_CALLBACK_ALARM_0);
}

Add to user application main():

    system_init();

    struct rtc_calendar_time time;
    rtc_calendar_get_time_defaults(&time);
    time.year   = 2012;
    time.month  = 12;
    time.day    = 31;
    time.hour   = 23;
    time.minute = 59;
    time.second = 59;

    /* Configure and enable RTC */
    configure_rtc_calendar();

    /* Configure and enable callback */
    configure_rtc_callbacks();

    /* Set current time. */
    rtc_calendar_set_time(&rtc_instance, &time);

Workflow

1. Initialize system.

       system_init();

2. Create and initialize a time structure.

       struct rtc_calendar_time time;
       rtc_calendar_get_time_defaults(&time);
       time.year   = 2012;
       time.month  = 12;
       time.day    = 31;
       time.hour   = 23;
       time.minute = 59;
       time.second = 59;

3. Configure and enable module.

       configure_rtc_calendar();

   1. Create an RTC configuration structure to hold the desired RTC driver settings and fill it with the default driver configuration values.

          struct rtc_calendar_config config_rtc_calendar;
          rtc_calendar_get_config_defaults(&config_rtc_calendar);

      Note

      This should always be performed before using the configuration struct to ensure that all values are initialized to known default settings.

   2. Create and initialize an alarm.

          alarm.time.year      = 2013;
          alarm.time.month     = 1;
          alarm.time.day       = 1;
          alarm.time.hour      = 0;
          alarm.time.minute    = 0;
          alarm.time.second    = 4;

   3. Change settings in the configuration and set alarm.

          config_rtc_calendar.clock_24h = true;
          config_rtc_calendar.alarm[0].time = alarm.time;
          config_rtc_calendar.alarm[0].mask = RTC_CALENDAR_ALARM_MASK_YEAR;

   4. Initialize the module with the set configurations.

          rtc_calendar_init(&rtc_instance, RTC, &config_rtc_calendar);

   5. Enable the module.

          rtc_calendar_enable(&rtc_instance);

4. Configure callback functionality.

       configure_rtc_callbacks();

   1. Register overflow callback.

          rtc_calendar_register_callback(
                  &rtc_instance, rtc_match_callback, RTC_CALENDAR_CALLBACK_ALARM_0);

   2. Enable overflow callback.

          rtc_calendar_enable_callback(&rtc_instance, RTC_CALENDAR_CALLBACK_ALARM_0);

5. Set time of the RTC calendar.

       rtc_calendar_set_time(&rtc_instance, &time);

Implementation

Code

Add to user application main:

    while (true) {
        /* Infinite loop */
    }

Workflow

1. Infinite while loop while waiting for callbacks.

       while (true) {

Callback

Each time the RTC time matches the configured alarm, the callback function will be called.

Workflow

1. Create alarm struct and initialize the time with current time.

   struct rtc_calendar_alarm_time alarm;

2. Set alarm to trigger on seconds only.

       alarm.mask = RTC_CALENDAR_ALARM_MASK_SEC;

3. Add one second to the current time and set new alarm.

       alarm.time.second += 5;
       alarm.time.second = alarm.time.second % 60;
   
       rtc_calendar_set_alarm(&rtc_instance, &alarm, RTC_CALENDAR_ALARM_0);