1.8.17 Real-time Clock (RTC)

The Real-time Clock (RTC) peripheral is designed for very low power consumption. For optimal functionality, the RTC requires an accurate external 32.768 kHz clock, which can be provided by a crystal oscillator.

It combines a complete time-of-day clock with alarm and a Gregorian or Persian calendar, complemented by a programmable periodic interrupt. The alarm and calendar registers are accessed by a 32-bit data bus.

The time and calendar values are coded in binary-coded decimal (BCD) format. The time format can be 24-hour mode or 12-hour mode with an AM/PM indicator.

Updating time and calendar fields and configuring the alarm fields are performed by a parallel capture on the 32-bit data bus. An entry control is performed to avoid loading registers with incompatible BCD format data or with an incompatible date according to the current month/year/century.

A clock divider calibration circuitry can be used to compensate for crystal oscillator frequency variations.

Two RTC output can be programmed to generate several waveforms, including a prescaled clock derived from 32.768 kHz.

Timestamping capability reports the first and last occurrences for each tamper event detected on TMPx pins.

Using The Library

The RTC keeps track of the current time and generates an alarm at the desired time. The RTC Alarm has five programmable fields: month, day, hours, minutes, and seconds.

Each of these fields can be enabled or disabled individually to match the alarm condition:

  • If all the fields are enabled, an alarm flag is generated (the corresponding flag is asserted and an interrupt generated if enabled) at a given month, date, hour, minute, and second

  • If only the "seconds" field is enabled, then an alarm is generated every minute

Depending on the combination of fields enabled, a large number of possibilities are available to the user application ranging from minutes to 365/366 days.

To avoid unwanted side effects, verification is performed on century, year, month, day, hours, minutes and seconds when the user sets up the time and alarm. If any field fails its check, the new data is not loaded into the destination register (or counter) and returns a "false" status. When the user programs acceptable time/date fields, the time set and alarm set API returns "true".

This example demonstrates how to set the RTC time, and alarm time to generate an alarm interrupt at the desired time of the day.

void RTC_Callback( uintptr_t context, uint32_t int_cause )
{
    if (int_cause & RTC_INT_ALARM)
    {
        /* Alarm has Occurred */
    }
}

int main ( void )
{
    /* Initialize System Time and Alarm Time */
    struct tm sys_time;
    struct tm alarm_time;

    /* Register Callback */
    RTC_CallbackRegister(RTC_Callback, (uintptr_t) NULL);


    /* Set Time and date
      <b>15&#45;01&#45;2018 12:00:00 Monday</b> */
    sys_time.tm_hour = 12;
    sys_time.tm_sec = 00;
    sys_time.tm_min = 00;
    sys_time.tm_mon = 0;
    sys_time.tm_year = 118;
    sys_time.tm_mday = 15;
    sys_time.tm_wday = 1;

    if (RTC_TimeSet(&amp;sys_time) == false)
    {
        // Invalid time and/or data input
    }

    /* Set Alarm Time and date. Generate alarm every day when Hour, Minute and Seconds match.
       <b>15&#45;01&#45;2018 12:00:20 Monday</b> */
    alarm_time.tm_hour = 12;
    alarm_time.tm_sec = 20;
    alarm_time.tm_min = 00;
    alarm_time.tm_mon = 0;
    alarm_time.tm_year = 118;
    alarm_time.tm_mday = 15;
    alarm_time.tm_wday = 1;

    if (RTC_AlarmSet(&amp;alarm_time, RTC_ALARM_MASK_HHMISS) == false)
    {
        // Invalid Alarm Time and/or data input
    }

    /* Get System Time */
    while ( true )
    {
        RTC_TimeGet(&amp;sys_time);
        printf("System time is:   %02d:%02d:%02d\\r",sys_time.tm_hour, sys_time.tm_min, sys_time.tm_sec);
    }

}

Library Interface

Real-time Clock peripheral library provides the following interfaces:

Functions

Name Description
RTC_Initialize Initializes given instance of the RTC peripheral
RTC_TimeSet Sets the Time for the RTC peripheral
RTC_TimeGet Reads the current time
RTC_AlarmSet Sets up the Alarm
RTC_FirstTimeStampGet Reads the timestamp for first occurrence of given tamper input
RTC_LastTimeStampGet Reads the timestamp for last occurrence of given tamper input
RTC_InterruptDisable Disables the specified RTC interrupt
RTC_InterruptEnable Enables the specified RTC interrupt
RTC_CallbackRegister Sets the pointer to the function (and it's context) to be called when the Timeout events occur

Data types and constants

Name Type Description
RTC_ALARM_MASK Enum Defines the data type for the RTC Alarm Mask
RTC_INT_MASK Enum Defines the Interrupt mask for RTC events
RTC_TAMP_INPUT Enum Defines the Tamper input
RTC_CALLBACK Typedef Defines the data type and function signature for the RTC peripheral callback function