General Description

The Real-Time Clock (RTC) driver provides an application interface for keeping track of time and date.

The functions and other declarations used in this driver are in cy_rtc.h. You can include cy_pdl.h to get access to all functions and declarations in the PDL.

Use the RTC driver when the system requires the current time or date. You can also use the RTC when you do not need the current time and date but you do need accurate timing of events with one-second resolution.

The RTC driver provides these features:

Different hour format support.
Multiple alarm function (two-alarms).
Daylight Savings Time (DST) support.
Automatic leap year compensation.
Option to drive the RTC by an external 50 Hz or 60 Hz clock source

The RTC driver provides access to the HW real-time clock. The HW RTC is located in the Backup domain. You need to choose the clock source for the Backup domain using the Cy_SysClk_ClkBakSetSource() function. If the clock for the Backup domain is set and enabled, the RTC automatically starts counting.

The RTC driver keeps track of second, minute, hour, day of the week, day of the month, month, and year.

DST may be enabled and supports any start and end date. The start and end dates can be a fixed date (like 24 March) or a relative date (like the second Sunday in March).

The RTC has two alarms that you can configure to generate an interrupt. You specify the match value for the time when you want the alarm to occur. Your interrupt handler then handles the response. The alarm flexibility supports periodic alarms (such as every minute), or a single alarm (13:45 on 28 September, 2043).

Clock Source

The Backup domain can be driven by:

Watch-crystal oscillator (WCO). This is a high-accuracy oscillator that is suitable for RTC applications and requires a 32.768 kHz external crystal populated on the application board. The WCO can be supplied by Backup domain and therefore can run without Vddd/Vccd present. This can be used to wake the chip from Hibernate mode.
The Internal Low-speed Oscillator (ILO) routed from Clk_LF or directly (as alternate backup domain clock source). Depending on the device power mode the alternate backup domain clock source is set. For example, for Deep Sleep mode the ILO is routed through Clk_LF. But for Hibernate power mode the ILO is set directly. Note that, the ILO should be configured to work in the Hibernate mode. For more info refer to the SysClk (System Clock) driver. The ILO is a low-accuracy RC-oscillator that does not require any external elements on the board. Its poor accuracy (+/- 30%) means it is less useful for the RTC. However, current can be supplied by an internal power supply (Vback) and therefore it can run without Vddd/Vccd present. This also can be used to wake the chip from Hibernate mode using RTC alarm interrupt. For more details refer to SysPm (System Power Management) driver description.
The Precision Internal Low-speed Oscillator (PILO), routed from Clk_LF (alternate backup domain clock source). This is an RC-oscillator (ILO) that can achieve accuracy of +/- 2% with periodic calibration. It is not expected to be accurate enough for good RTC capability. The PILO requires Vddd/Vccd present. It can be used in modes down to Deep Sleep, but ceases to function in Hibernate mode.
External 50 Hz or 60 Hz sine-wave clock source or 32.768 kHz square clock source. For example, the wall AC frequency can be the clock source. Such a clock source can be used if the external 32.768 kHz WCO is absent from the board. For more details, refer to the Cy_RTC_SelectFrequencyPrescaler() function description.

The WCO is the recommended clock source for the RTC, if it is present in design. For setting the Backup domain clock source, refer to the SysClk (System Clock) driver.

Note: If the WCO is enabled, it should source the Backup domain directly. Do not route the WCO through the Clk_LF. This is because Clk_LF is not available in all low-power modes.

Configuration Considerations

Before RTC set up, ensure that the Backup domain is clocked with the desired clock source.

To set up an RTC, provide the configuration parameters in the cy_stc_rtc_config_t structure. Then call Cy_RTC_Init(). You can also set the date and time at runtime. Call Cy_RTC_SetDateAndTime() using the filled cy_stc_rtc_config_t structure, or call Cy_RTC_SetDateAndTimeDirect() with valid time and date values.

RTC Interrupt Handling

The RTC driver provides three interrupt handler functions: Cy_RTC_Alarm1Interrupt(), Cy_RTC_Alarm2Interrupt(), and Cy_RTC_CenturyInterrupt(). All three functions are blank functions with the WEAK attribute. For any interrupt you use, redefine the interrupt handler in your source code.

When an interrupt occurs, call the Cy_RTC_Interrupt() function. The RTC hardware provides a single interrupt line to the NVIC for the three RTC interrupts. This function checks the interrupt register to determine which interrupt (out of the three) was generated. It then calls the appropriate handler.

Warning: The Cy_RTC_Alarm2Interrupt() is not called if the DST feature is enabled. If DST is enabled, the Cy_RTC_Interrupt() function redirects that interrupt to manage daylight savings time using Cy_RTC_DstInterrupt(). In general, the RTC interrupt handler function the Cy_RTC_DstInterrupt() function is called instead of Cy_RTC_Alarm2Interrupt().

For RTC interrupt handling, the user should:

Implement strong interrupt handling function(s) for the required events (see above). If DST is enabled, then Alarm2 is not available. The DST handler is built into the PDL.
Implement an RTC interrupt handler and call Cy_RTC_Interrupt() from there.
Configure the RTC interrupt:
- Set the mask for RTC required interrupt using Cy_RTC_SetInterruptMask().
- Initialize the RTC interrupt by setting priority and the RTC interrupt vector using the Cy_SysInt_Init() function.
- Enable the RTC interrupt using the CMSIS core function NVIC_EnableIRQ().

Alarm functionality

To set up an alarm, enable the required RTC interrupt. Then provide the configuration parameters in the cy_stc_rtc_alarm_t structure. You enable any item you want matched, and provide a match value. You disable any other. You do not need to set match values for disabled elements, as they are ignored.

Note: The alarm itself must be enabled in this structure. When a match occurs, the alarm is triggered and your interrupt handler is called.

An example is the best way to explain how this works. If you want an alarm on every hour, then in the cy_stc_rtc_alarm_t structure, you provide these values:

Alarm_1.sec = 0u
Alarm_1.secEn = CY_RTC_ALARM_ENABLE
Alarm_1.min = 0u
Alarm_1.minEn = CY_RTC_ALARM_ENABLE
Alarm_1.hourEn = CY_RTC_ALARM_DISABLE
Alarm_1.dayOfWeekEn = CY_RTC_ALARM_DISABLE
Alarm_1.dateEn = CY_RTC_ALARM_DISABLE
Alarm_1.monthEn = CY_RTC_ALARM_DISABLE
Alarm_1.almEn = CY_RTC_ALARM_ENABLE
With this setup, every time both the second and minute are zero, Alarm1 is asserted. That happens once per hour. Note that, counterintuitively, to have an alarm every hour, Alarm_1.hourEn is disabled. This is disabled because for an hourly alarm you do not match the value of the hour.

After cy_stc_rtc_alarm_t structure is filled, call the Cy_RTC_SetAlarmDateAndTime(). The alarm can also be set without using the cy_stc_rtc_alarm_t structure. Call Cy_RTC_SetAlarmDateAndTimeDirect() with valid values.

The DST Feature

The DST feature is managed by the PDL using the RTC Alarm2 interrupt. Therefore, you cannot have both DST enabled and use the Alarm2 interrupt.

To set up the DST, route the RTC interrupt to NVIC:

Initialize the RTC interrupt by setting priority and the RTC interrupt vector using Cy_SysInt_Init().
Enable the RTC interrupt using the CMSIS core function NVIC_EnableIRQ().

After this, provide the configuration parameters in the cy_stc_rtc_dst_t structure. This structure consists of two cy_stc_rtc_dst_format_t structures, one for DST Start time and one for DST Stop time. You also specify whether these times are absolute or relative.

After the cy_stc_rtc_dst_t structure is filled, call Cy_RTC_EnableDstTime()

Low Power Support

The RTC provides the callback functions to facilitate the low-power mode transition. The callback Cy_RTC_DeepSleepCallback must be called during execution of Cy_SysPm_CpuEnterDeepSleep, Cy_RTC_HibernateCallback must be called during execution of Cy_SysPm_SystemEnterHibernate. To trigger the callback execution, the callback must be registered before calling the mode transition function. Refer to SysPm (System Power Management) driver for more information about low-power mode transitions.

More Information

For more information on the RTC peripheral, refer to the technical reference manual (TRM).

MISRA-C Compliance

The RTC driver does not have any specific deviations.

Changelog

Version	Changes	Reason for Change
2.30.1	Minor documentation updates.	Documentation enhancement.
2.30	Corrected the Cy_RTC_GetDstStatus() and Cy_RTC_SetNextDstTime() documentation. Fixed the Cy_RTC_GetDstStatus() behaviour in the 'an hour before/after the DST stop event' period.	Collateral Review: user experience enhancement. Bug fix.
2.20.1	Modified header guard CY_IP_MXS40SRSS_RTC.	To enable the PDL compilation with wounded out IP blocks.
2.20	Flattened the organization of the driver source code into the single source directory and the single include directory.	Driver library directory-structure simplification.
	Added register access layer. Use register access macros instead of direct register access using dereferenced pointers.	Makes register access device-independent, so that the PDL does not need to be recompiled for each supported part number.
	Documentation update.	Documentation enhancement.
2.10	Corrected Cy_RTC_SetDateAndTimeDirect(), Cy_RTC_SetNextDstTime() function. Corrected internal macro. Documentation updates.	Incorrect behavior of Cy_RTC_SetDateAndTimeDirect() and Cy_RTC_SetNextDstTime() work in debug mode. Debug assert correction in Cy_RTC_ConvertDayOfWeek, Cy_RTC_IsLeapYear, Cy_RTC_DaysInMonth.
2.0	Enhancement and defect fixes: Added input parameter(s) validation to all public functions. Removed "Cy_RTC_" prefixes from the internal functions names. Renamed the elements in the cy_stc_rtc_alarm structure. Changed the type of elements with limited set of values, from uint32_t to enumeration.
1.0	Initial version