PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

Functions
General
PDL API Reference » RTC (Real-Time Clock) » Functions

## General Description

## Functions
cy_en_rtc_status_t | Cy_RTC_Init (cy_stc_rtc_config_t const *config)
| Initializes the RTC driver. More...
cy_en_rtc_status_t | Cy_RTC_SetDateAndTime (cy_stc_rtc_config_t const *dateTime)
| Sets the time and date values into the RTC_TIME and RTC_DATE registers. More...
void | Cy_RTC_GetDateAndTime (cy_stc_rtc_config_t *dateTime)
| Gets the current RTC time and date. More...
cy_en_rtc_status_t | Cy_RTC_SetDateAndTimeDirect (uint32_t sec, uint32_t min, uint32_t hour, uint32_t date, uint32_t month, uint32_t year)
| Sets the time and date values into the RTC_TIME and RTC_DATE registers using direct time parameters. More...
cy_en_rtc_status_t | Cy_RTC_SetHoursFormat (cy_en_rtc_hours_format_t hoursFormat)
| Sets the 12/24-hour mode. More...
void | Cy_RTC_SelectFrequencyPrescaler (cy_en_rtc_clock_freq_t clkSel)
| Selects the RTC pre-scaler value and changes its clock frequency. More...
void | Cy_RTC_SelectClockSource (cy_en_rtc_clk_select_sources_t clkSel)
cy_en_rtc_status_t | Cy_RTC_CalibrationControlEnable (uint8_t calib_val, cy_en_rtc_calib_sign_t calib_sign, cy_en_rtc_calib_sel_t calib_sel)
| This function writes calibration control register. More...
cy_en_rtc_status_t | Cy_RTC_CalibrationControlDisable (void)
| This function disables the calibration control. More...

## Function Documentation

## ◆ Cy_RTC_Init()

cy_en_rtc_status_t Cy_RTC_Init | ( | cy_stc_rtc_config_t const * | config | ) |

Initializes the RTC driver.

Parameters

  *config | The pointer to the RTC configuration structure, see cy_stc_rtc_config_t.

Returns
  Checking result. If the pointer is NULL, returns an error. See cy_en_rtc_status_t.

## ◆ Cy_RTC_SetDateAndTime()

cy_en_rtc_status_t Cy_RTC_SetDateAndTime | ( | cy_stc_rtc_config_t const * | dateTime | ) |

Sets the time and date values into the RTC_TIME and RTC_DATE registers.

Parameters

  dateTime | The pointer to the RTC configuration structure, see cy_stc_rtc_config_t.

Returns
  A validation check result of date and month. Returns an error, if the date range is invalid. See cy_en_rtc_status_t.

Note
  The function may return CY_RTC_INVALID_STATE if the RTC is busy with previous update. In such situation, user should call this function repetitively with appropriate parameters to ensure that RTC is updated with provided arguments.
  Refresh ALARM using Cy_RTC_SetAlarmDateAndTime if it is already enabled before calling this API.

## ◆ Cy_RTC_GetDateAndTime()

void Cy_RTC_GetDateAndTime | ( | cy_stc_rtc_config_t * | dateTime | ) |

Gets the current RTC time and date.

The AHB RTC Time and Date register values are stored into the *dateTime structure.

Note
  This API is Secure Aware. On devices with ARM TrustZone enabled, it is safe to call on a Secure hardware resource from a Non-Secure CPU state. The involved PPC region is PROT_PERI0_RTC_BACKUP. See Secure Aware RTC for further details.
  Ensure that dataTime argument is DCache aligned when calling from a non-secured Core onto a secured hardware resource. This is only relevent for cross-core calls, not calls between security contexts on the same core.

Parameters

  dateTime | The RTC time and date structure. See Data Structures.

## ◆ Cy_RTC_SetDateAndTimeDirect()

cy_en_rtc_status_t Cy_RTC_SetDateAndTimeDirect | ( | uint32_t | sec,
|  | uint32_t | min,
|  | uint32_t | hour,
|  | uint32_t | date,
|  | uint32_t | month,
|  | uint32_t | year
| ) |  |

Sets the time and date values into the RTC_TIME and RTC_DATE registers using direct time parameters.

Parameters

  sec | The second valid range is [0-59].
  min | The minute valid range is [0-59].
  hour | The hour valid range is [0-23]. This parameter should be presented in the 24-hour format.

The function reads the current 12/24-hour mode, then converts the hour value properly as the mode.

Parameters

  date | The date valid range is [1-31], if the month of February is selected as the Month parameter, then the valid range is [0-29].
  month | The month valid range is [1-12].
  year | The year valid range is [0-99].

Returns
  A validation check result of date and month. Returns an error, if the date range is invalid or the RTC time and date set was cancelled: the RTC Write bit was not set, the RTC was synchronizing. See cy_en_rtc_status_t.

## ◆ Cy_RTC_SetHoursFormat()

cy_en_rtc_status_t Cy_RTC_SetHoursFormat | ( | cy_en_rtc_hours_format_t | hoursFormat | ) |

Sets the 12/24-hour mode.

Parameters

  hoursFormat | The current hour format, see cy_en_rtc_hours_format_t.

Returns
  A validation check result of RTC register update. See cy_en_rtc_status_t.

Note
  Refresh ALARM using Cy_RTC_SetAlarmDateAndTime if it is already enabled before calling this API.

## ◆ Cy_RTC_SelectFrequencyPrescaler()

void Cy_RTC_SelectFrequencyPrescaler | ( | cy_en_rtc_clock_freq_t | clkSel | ) |

Selects the RTC pre-scaler value and changes its clock frequency.

If the external 32.768 kHz WCO is absent on the board, the RTC can be driven by a 32.768kHz square clock source or an external 50-Hz or 60-Hz sine-wave clock source, for example the wall AC frequency.

Parameters

  clkSel | clock frequency, see cy_en_rtc_clock_freq_t.

In addition to generating the 32.768 kHz clock from external crystals, the WCO can be sourced by an external clock source (50 Hz or 60Hz), even the wall AC frequency as a timebase. The API helps select between the RTC sources:

- A 32.768 kHz digital clock source.
- An external 50-Hz or 60-Hz sine-wave clock source.

If you want to use an external 50-Hz or 60-Hz sine-wave clock source to drive the RTC, the next procedure is required:

1. Disable the WCO
2. Bypass the WCO using the Cy_SysClk_WcoBypass() function.
3. Configure both wco_out and wco_in pins. Note that only one of the wco pins should be driven and the other wco pin should be floating, which depends on the source that drives the RTC (*1).
4. Call Cy_RTC_SelectFrequencyPrescaler(CY_RTC_FREQ_60_HZ), if you want to drive the WCO, for example, with a 60 Hz source.
5. Enable the WCO.

If you want to use the WCO after using an external 50-Hz or 60-Hz sine-wave clock source:

1. Disable the WCO.
2. Switch-off the WCO bypass using the Cy_SysClk_WcoBypass() function.
3. Drive off the wco pin with an external signal source.
4. Call Cy_RTC_SelectFrequencyPrescaler(CY_RTC_FREQ_WCO_32768_HZ).
5. Enable the WCO.

(1) - Refer to the device TRM to know how to configure the wco pins properly and which wco pin should be driven/floating.

Warning
  There is a limitation to the external clock source frequencies. Only two frequencies are allowed - 50 Hz or 60 Hz. Note that this limitation is related to the RTC pre-scaling feature presented in this function. This limitation is not related to WCO external clock sources which can drive the WCO in Bypass mode.

## ◆ Cy_RTC_SelectClockSource()

void Cy_RTC_SelectClockSource | ( | cy_en_rtc_clk_select_sources_t | clkSel | ) |

Parameters

  clkSel | Source clock, see cy_en_rtc_clk_select_sources_t Selects the source clock for RTC.

Changing clock selection is not guaranteed to be glitch free, thus alarms should be deactivated before changing the selected clock. Afterwards the RTC time should also be reconfigured.

Returns
  Result of RTC clock source update. See cy_en_rtc_status_t.

## ◆ Cy_RTC_CalibrationControlEnable()

cy_en_rtc_status_t Cy_RTC_CalibrationControlEnable | ( | uint8_t | calib_val,
|  | cy_en_rtc_calib_sign_t | calib_sign,
|  | cy_en_rtc_calib_sel_t | calib_sel
| ) |  |

This function writes calibration control register.

Parameters

  calib_val | Calibration value for absolute frequency (at a fixed temperature). Each step causes 128 ticks to be added or removed each hour.
  calib_sign | Remove or Add ticks, see cy_en_rtc_calib_sign_t
  calib_sel | Select calibration wave output signal, see cy_en_rtc_calib_sel_t

Returns
  The RTC return status, see cy_en_rtc_status_t

## ◆ Cy_RTC_CalibrationControlDisable()

cy_en_rtc_status_t Cy_RTC_CalibrationControlDisable | ( | void |  | ) |

This function disables the calibration control.

Returns
  The RTC return status, see cy_en_rtc_status_t