PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference
RTC (Real-Time Clock)
PDL API Reference

## 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

Depending on the available clocks 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:

1. 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.
2. Implement an RTC interrupt handler and call Cy_RTC_Interrupt() from there.
3. 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:

1. Initialize the RTC interrupt by setting priority and the RTC interrupt vector using Cy_SysInt_Init().
2. 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.

# Secure Aware RTC

Some RTC APIs are marked as Secure Aware. This means that if the RTC is marked as a secure resource in the Peripheral Protection Controller (PPC) and these APIs are called from a non-secure CPU state, the PDL will submit a request to the Secure Request Framework (SRF) middleware to transition to a secure CPU state to perform the operation. From the application's perspective, the API will behave the same whether it is called from a secure or non-secure CPU state albeit slower.

This functionality is automatically enabled on devices with ARM TrustZone processors. To disable, set the DEFINE+=CY_PDL_ENABLE_SECURE_AWARE_RTC=0 in the application Makefile.

For more information on Secure Aware PDL behavior, see Secure Aware PDL.

# More Information

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

## API Reference
| Macros
| Functions
| Data Structures
| Enumerated Types