cy_rtc_8h

This file provides constants and parameter values for the APIs for the Real-Time Clock (RTC).

Version

2.50

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0
Copyright

Copyright 2016-2020 Cypress Semiconductor Corporation SPDX-License-Identifier: Apache-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Defines

CY_RTC_ID

RTC driver identifier.

CY_RTC_DRV_VERSION_MAJOR

Driver major version.

CY_RTC_DRV_VERSION_MINOR

Driver minor version.

CY_RTC_SUNDAY

Sequential number of Sunday in the week.

CY_RTC_MONDAY

Sequential number of Monday in the week.

CY_RTC_TUESDAY

Sequential number of Tuesday in the week.

CY_RTC_WEDNESDAY

Sequential number of Wednesday in the week.

CY_RTC_THURSDAY

Sequential number of Thursday in the week.

CY_RTC_FRIDAY

Sequential number of Friday in the week.

CY_RTC_SATURDAY

Sequential number of Saturday in the week.

CY_RTC_FIRST_WEEK_OF_MONTH

First week in the month.

CY_RTC_SECOND_WEEK_OF_MONTH

Second week in the month.

CY_RTC_THIRD_WEEK_OF_MONTH

Third week in the month.

CY_RTC_FOURTH_WEEK_OF_MONTH

Fourth week in the month.

CY_RTC_FIFTH_WEEK_OF_MONTH

Fifth week in the month.

CY_RTC_LAST_WEEK_OF_MONTH

Last week in the month.

CY_RTC_JANUARY

Sequential number of January in the year.

CY_RTC_FEBRUARY

Sequential number of February in the year.

CY_RTC_MARCH

Sequential number of March in the year.

CY_RTC_APRIL

Sequential number of April in the year.

CY_RTC_MAY

Sequential number of May in the year.

CY_RTC_JUNE

Sequential number of June in the year.

CY_RTC_JULY

Sequential number of July in the year.

CY_RTC_AUGUST

Sequential number of August in the year.

CY_RTC_SEPTEMBER

Sequential number of September in the year.

CY_RTC_OCTOBER

Sequential number of October in the year.

CY_RTC_NOVEMBER

Sequential number of November in the year.

CY_RTC_DECEMBER

Sequential number of December in the year.

CY_RTC_DAYS_IN_JANUARY

Number of days in January.

CY_RTC_DAYS_IN_FEBRUARY

Number of days in February.

CY_RTC_DAYS_IN_MARCH

Number of days in March.

CY_RTC_DAYS_IN_APRIL

Number of days in April.

CY_RTC_DAYS_IN_MAY

Number of days in May.

CY_RTC_DAYS_IN_JUNE

Number of days in June.

CY_RTC_DAYS_IN_JULY

Number of days in July.

CY_RTC_DAYS_IN_AUGUST

Number of days in August.

CY_RTC_DAYS_IN_SEPTEMBER

Number of days in September.

CY_RTC_DAYS_IN_OCTOBER

Number of days in October.

CY_RTC_DAYS_IN_NOVEMBER

Number of days in November.

CY_RTC_DAYS_IN_DECEMBER

Number of days in December.

CY_RTC_INTR_ALARM1

Alarm 1 status.

CY_RTC_INTR_ALARM2

Alarm 2 status.

CY_RTC_INTR_CENTURY

This interrupt occurs when the year is reached to 2100 which is rolling over the year field value from 99 to 0.

CY_RTC_BUSY

RTC Busy bit is set, RTC is pending.

CY_RTC_AVAILABLE

RTC Busy bit is cleared, RTC is available.

Enums

enum cy_en_rtc_status_t

cy_en_rtc_status_t: RTC status enumeration.

Values:

enumerator CY_RTC_SUCCESS

Successful.

enumerator CY_RTC_BAD_PARAM

One or more invalid parameters.

enumerator CY_RTC_TIMEOUT

Time-out occurs.

enumerator CY_RTC_INVALID_STATE

Operation not setup or is in an improper state.

enumerator CY_RTC_UNKNOWN

Unknown failure.

enum cy_en_rtc_clock_freq_t

cy_en_rtc_clock_freq_t: This enumeration is used to set frequency by changing the it pre-scaler.

Values:

enumerator CY_RTC_FREQ_WCO_32768_HZ

prescaler value for 32.768 kHz oscillator

enumerator CY_RTC_FREQ_60_HZ

prescaler value for 60 Hz source

enumerator CY_RTC_FREQ_50_HZ

prescaler value for 50 Hz source

enum cy_en_rtc_alarm_t

cy_en_rtc_alarm_t: This enumeration is used to set/get information for alarm 1 or alarm 2.

Values:

enumerator CY_RTC_ALARM_1

Alarm 1 enum.

enumerator CY_RTC_ALARM_2

Alarm 2 enum.

enum cy_en_rtc_hours_format_t

cy_en_rtc_hours_format_t: This enumeration is used to set/get hours format.

Values:

enumerator CY_RTC_24_HOURS

The 24 hour format.

enumerator CY_RTC_12_HOURS

The 12 hour (AM/PM) format.

enum cy_en_rtc_write_status_t

cy_en_rtc_write_status_t: Enumeration to configure the RTC Write register.

Values:

enumerator CY_RTC_WRITE_DISABLED

Writing the RTC is disabled.

enumerator CY_RTC_WRITE_ENABLED

Writing the RTC is enabled.

enum cy_en_rtc_dst_format_t

cy_en_rtc_dst_format_t: Enumeration used to set/get DST format.

Values:

enumerator CY_RTC_DST_RELATIVE

Relative DST format.

enumerator CY_RTC_DST_FIXED

Fixed DST format.

enum cy_en_rtc_am_pm_t

cy_en_rtc_am_pm_t: Enumeration to indicate the AM/PM period of day.

Values:

enumerator CY_RTC_AM

AM period of day.

enumerator CY_RTC_PM

PM period of day.

enum cy_en_rtc_alarm_enable_t

cy_en_rtc_alarm_enable_t: Enumeration to enable/disable the RTC alarm on match with required value.

Values:

enumerator CY_RTC_ALARM_DISABLE

Disable alarm on match with required value.

enumerator CY_RTC_ALARM_ENABLE

Enable alarm on match with required value.

enum cy_rtc_clk_select_sources_t

cy_rtc_clk_select_sources_t: Enumeration to list all the clock sources for RTC.

Values:

enumerator CY_RTC_CLK_SELECT_WCO

Select WCO as input to RTC.

enumerator CY_RTC_CLK_SELECT_ALTBAK

Select ALTBAK as input to RTC.

enumerator CY_RTC_CLK_SELECT_ILO

Select ILO as input to RTC.

enumerator CY_RTC_CLK_SELECT_LPECO_PRESCALER

Select LPECO_PRESCALER as input to RTC.

enumerator CY_RTC_CLK_SELECT_PILO

Select PILO as input to RTC.

Functions

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_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.

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.

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.

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.

Parameters

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

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.

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

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.

  • 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_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.

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.

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.

note

This API is available for CAT1A devices.

Parameters

clkSel – clock frequency, see cy_en_rtc_clock_freq_t.

void Cy_RTC_SelectClockSource(cy_rtc_clk_select_sources_t clkSel)

note

This API is available for CAT1B devices.

Parameters

clkSel – Source clock, see cy_rtc_clk_select_sources_t Selects the source clock for RTC.

cy_en_rtc_status_t Cy_RTC_SetAlarmDateAndTime(cy_stc_rtc_alarm_t const *alarmDateTime, cy_en_rtc_alarm_t alarmIndex)

Sets alarm time and date values into the ALMx_TIME and ALMx_DATE registers.

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.

Parameters
Returns

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

void Cy_RTC_GetAlarmDateAndTime(cy_stc_rtc_alarm_t *alarmDateTime, cy_en_rtc_alarm_t alarmIndex)

Returns the current alarm time and date values from the ALMx_TIME and ALMx_DATE registers.

Parameters
cy_en_rtc_status_t Cy_RTC_SetAlarmDateAndTimeDirect(uint32_t sec, uint32_t min, uint32_t hour, uint32_t date, uint32_t month, cy_en_rtc_alarm_t alarmIndex)

Sets alarm time and date values into the ALMx_TIME and ALMx_DATE registers using direct time parameters.

ALM_DAY_EN is default 0 (=ignore) for this function.

Parameters

  • sec – The alarm second valid range is [0-59].

  • min – The alarm minute valid range is [0-59].

  • hour – The valid range is [0-23]. This parameter type is always in the 24-hour type. This function reads the current 12/24-hour mode, then converts the hour value properly as the mode.

  • date – The 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 alarm month valid range is [1-12].

  • alarmIndex – The alarm index to be configured, see cy_en_rtc_alarm_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.

cy_en_rtc_status_t Cy_RTC_EnableDstTime(cy_stc_rtc_dst_t const *dstTime, cy_stc_rtc_config_t const *timeDate)

The function sets the DST time and configures the ALARM2 interrupt register with the appropriate DST time.

This function sets the DST stop time if the current time is already in the DST period. The DST period is a period of time between the DST start time and DST stop time. The DST start time and DST stop time is presented in the DST configuration structure, see cy_stc_rtc_dst_t.

Parameters

  • dstTime – The DST configuration structure, see cy_stc_rtc_dst_t.

  • timeDate – The time and date structure. The the appropriate DST time is set based on this time and date, see cy_stc_rtc_config_t.

Returns

cy_en_rtc_status_t A validation check result of RTC register update.

cy_en_rtc_status_t Cy_RTC_SetNextDstTime(cy_stc_rtc_dst_format_t const *nextDst)

A low-level DST function sets ALARM2 for a next DST event.

If Cy_RTC_GetDSTStatus() is true(=1), the next DST event should be the DST stop, then this function should be called with the DST stop time. Used by the Cy_RTC_EnableDstTime and Cy_RTC_DstInterrupt functions.

If the time format(.format) is relative option(=0), the RelativeToFixed() is called to convert to a fixed date.

Parameters

nextDst – The structure with time at which a next DST event should occur (ALARM2 interrupt should occur). See cy_stc_rtc_config_t.

Returns

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

bool Cy_RTC_GetDstStatus(cy_stc_rtc_dst_t const *dstTime, cy_stc_rtc_config_t const *timeDate)

A low-level DST function returns the current DST status using given time information.

This function is used in the initial state of a system. If the DST is enabled, the system sets the DST start or stop as a result of this function. Used by the Cy_RTC_EnableDstTime and Cy_RTC_DstInterrupt functions.

Parameters

  • dstTime – The DST configuration structure, see cy_stc_rtc_dst_t.

  • timeDate – The time and date structure. The the appropriate DST time is set based on this time and date, see cy_stc_rtc_config_t.

Returns

False - The current date and time is out of the DST period. True - The current date and time is in the DST period.

void Cy_RTC_Interrupt(cy_stc_rtc_dst_t const *dstTime, bool mode)

The interrupt handler function which should be called in user provided RTC interrupt function.

This is the handler of the RTC interrupt in CPU NVIC. The handler checks which RTC interrupt was asserted and calls the respective RTC interrupt handler functions: Cy_RTC_Alarm1Interrupt(), Cy_RTC_Alarm2Interrupt() or Cy_RTC_DstInterrupt(), and Cy_RTC_CenturyInterrupt().

The order of the RTC handler functions execution is incremental. Cy_RTC_Alarm1Interrupt() is run as the first one and Cy_RTC_CenturyInterrupt() is called as the last one.

This function clears the RTC interrupt every time when it is called.

Cy_RTC_DstInterrupt() function is called instead of Cy_RTC_Alarm2Interrupt() in condition that the mode parameter is true.

note

This function is required to be called in user interrupt handler.

Parameters

  • dstTime – The daylight saving time configuration structure, see cy_stc_rtc_dst_t.

  • mode – False - if the DST is disabled. True - if DST is enabled.

void Cy_RTC_Alarm1Interrupt(void)

A blank weak interrupt handler function which indicates assert of the RTC alarm 1 interrupt.

Function implementation should be defined in user source code in condition that such event handler is required. If such event is not required user should not do any actions.

This function is called in the general RTC interrupt handler Cy_RTC_Interrupt() function.

void Cy_RTC_Alarm2Interrupt(void)

A blank weak interrupt handler function which indicates assert of the RTC alarm 2 interrupt.

Function implementation should be defined in user source code in condition that such event handler is required. If such event is not required user should not do any actions.

This function is called in the general RTC interrupt handler Cy_RTC_Interrupt() function. Cy_RTC_Alarm2Interrupt() function is ignored in Cy_RTC_Interrupt() function if DST is enabled. Refer to Cy_RTC_Interrupt() description.

void Cy_RTC_DstInterrupt(cy_stc_rtc_dst_t const *dstTime)

This is a processing handler against the DST event.

It adjusts the current time using the DST start/stop parameters and registers the next DST event time into the ALARM2 interrupt.

Parameters

dstTime – The DST configuration structure, see cy_stc_rtc_dst_t.

void Cy_RTC_CenturyInterrupt(void)

This is a weak function and it should be redefined in user source code in condition that such event handler is required.

By calling this function, it indicates the year reached 2100. It should add an adjustment to avoid the Y2K problem.

Function implementation should be defined in user source code in condition that such event handler is required. If such event is not required user should not do any actions.

uint32_t Cy_RTC_GetInterruptStatus(void)

Returns a status of RTC interrupt requests.

Returns

Bit mapping information, see RTC Interrupt sources.

uint32_t Cy_RTC_GetInterruptStatusMasked(void)

Returns an interrupt request register masked by the interrupt mask.

Returns a result of the bitwise AND operation between the corresponding interrupt request and mask bits.

Returns

Bit mapping information, see RTC Interrupt sources.

uint32_t Cy_RTC_GetInterruptMask(void)

Returns an interrupt mask.

Returns

Bit mapping information, see RTC Interrupt sources.

void Cy_RTC_ClearInterrupt(uint32_t interruptMask)

Clears RTC interrupts by setting each bit.

Parameters

interruptMask – The bit mask of interrupts to set, see RTC Interrupt sources.

void Cy_RTC_SetInterrupt(uint32_t interruptMask)

Sets a software interrupt request.

Parameters

interruptMask – Bit mask, see RTC Interrupt sources.

void Cy_RTC_SetInterruptMask(uint32_t interruptMask)

Configures which bits of the interrupt request register that triggers an interrupt event.

Parameters

interruptMask – The bit mask of interrupts to set, see RTC Interrupt sources.

cy_en_syspm_status_t Cy_RTC_DeepSleepCallback(const cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)

This function checks the RTC_BUSY bit to avoid data corruption before enters the Deep Sleep mode.

note

The *base and *context elements are required to be present in the parameter structure because this function uses the SysPm driver callback type. The SysPm driver callback function type requires implementing the function with next parameters and return value:

cy_en_syspm_status_t (*Cy_SysPmCallback) (

cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode);

Parameters
Returns

The SysPm return status, see cy_en_syspm_status_t.

cy_en_syspm_status_t Cy_RTC_HibernateCallback(const cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode)

This function checks the RTC_BUSY bit to avoid data corruption before enters the Hibernate mode.

note

The *base and *context elements are required to be present in the parameter structure because this function uses the SysPm driver callback type. The SysPm driver callback function type requires implementing the function with next parameters and return value:

cy_en_syspm_status_t (*Cy_SysPmCallback) (

cy_stc_syspm_callback_params_t *callbackParams, cy_en_syspm_callback_mode_t mode);

Parameters
Returns

The syspm return status, see cy_en_syspm_status_t

__STATIC_INLINE uint32_t Cy_RTC_ConvertDayOfWeek (uint32_t day, uint32_t month, uint32_t year)

Returns a day of the week for a year, month, and day of month that are passed through parameters.

Zeller’s congruence is used to calculate the day of the week. RTC HW block does not provide the converting function for day of week. This function should be called before Cy_RTC_SetDateAndTime() to get the day of week.

For the Georgian calendar, Zeller’s congruence is: h = (q + [13 * (m + 1)] + K + [K/4] + [J/4] - 2J) mod 7

h - The day of the week (0 = Saturday, 1 = Sunday, 2 = Monday, ., 6 = Friday). q - The day of the month. m - The month (3 = March, 4 = April, 5 = May, …, 14 = February) K - The year of the century (year mod 100). J - The zero-based century (actually [year/100]) For example, the zero-based centuries for 1995 and 2000 are 19 and 20 respectively (not to be confused with the common ordinal century enumeration which indicates 20th for both cases).

note

In this algorithm January and February are counted as months 13 and 14 of the previous year.

Parameters

  • day – The day of the month, Valid range 1..31.

  • month – The month of the year, see Month definitions.

  • year – The year value. Valid range non-zero value.

Returns

Returns a day of the week, see Day of the week definitions.

__STATIC_INLINE bool Cy_RTC_IsLeapYear (uint32_t year)

Checks whether the year passed through the parameter is leap or not.

This API is for checking an invalid value input for leap year. RTC HW block does not provide a validation checker against time/date values, the valid range of days in Month should be checked before SetDateAndTime() function call. Leap year is identified as a year that is a multiple of 4 or 400 but not 100.

Parameters

year – The year to be checked. Valid range non-zero value.

Returns

False - The year is not leap. True - The year is leap.

__STATIC_INLINE uint32_t Cy_RTC_DaysInMonth (uint32_t month, uint32_t year)

Returns a number of days in a month passed through the parameters.

This API is for checking an invalid value input for days. RTC HW block does not provide a validation checker against time/date values, the valid range of days in Month should be checked before SetDateAndTime() function call.

Parameters

  • month – The month of the year, see Month definitions.

  • year – A year value. Valid range non-zero value.

Returns

A number of days in a month in the year passed through the parameters.

__STATIC_INLINE void Cy_RTC_SyncFromRtc (void)

The Synchronizer updates RTC values into AHB RTC user registers from the actual RTC.

By calling this function, the actual RTC register values is copied to AHB user registers.

note

Only after calling Cy_RTC_SyncFromRtc(), the RTC time values can be read. After Cy_RTC_SyncFromRtc() calling the snapshot of the actual RTC registers are copied to the user registers. Meanwhile the RTC continues to clock.

__STATIC_INLINE cy_en_rtc_status_t Cy_RTC_WriteEnable (cy_en_rtc_write_status_t writeEnable)

Set/Clear writeable option for RTC user registers.

When the Write bit is set, data can be written into the RTC user registers. After all the RTC writes are done, the firmware must clear (call Cy_RTC_WriteEnable(RTC_WRITE_DISABLED)) the Write bit for the RTC update to take effect.

Set/Clear cannot be done if the RTC is still busy with a previous update (CY_RTC_BUSY = 1) or RTC Reading is executing.

Parameters

writeEnable – Write status, see cy_en_rtc_write_status_t.

Returns

CY_RTC_SUCCESS - Set/Clear Write bit was successful. CY_RTC_INVALID_STATE - RTC is busy with a previous update. See cy_en_rtc_status_t.

__STATIC_INLINE uint32_t Cy_RTC_GetSyncStatus (void)

Return current status of CY_RTC_BUSY.

The status indicates synchronization between the RTC user register and the actual RTC register. CY_RTC_BUSY bit is set if it is synchronizing. It is not possible to set the Read or Write bit until CY_RTC_BUSY clears.

Returns

The status of RTC user register synchronization. See RTC Status definitions

__STATIC_INLINE cy_en_rtc_hours_format_t Cy_RTC_GetHoursFormat (void)

Returns current 12/24 hours format.

note

Before getting the RTC current hours format, the Cy_RTC_SyncFromRtc() function should be called.

Returns

The current RTC hours format. See cy_en_rtc_hours_format_t.

__STATIC_INLINE bool Cy_RTC_IsExternalResetOccurred (void)

The function checks the reset cause and returns the Boolean result.

note

Based on a return value the RTC time and date can be updated or skipped after the device reset. For example, you should skip the Cy_RTC_SetAlarmDateAndTime() call function if internal WDT reset occurs.

Returns

True if the reset reason is the power cycle and the XRES (external reset). False if the reset reason is other than power cycle and the XRES.

__STATIC_INLINE void Cy_RTC_SyncToRtcAhbDateAndTime (uint32_t timeBcd, uint32_t dateBcd)

This function updates new time and date into the time and date RTC AHB registers.

[0:6] - Calendar seconds in BCD, the range 0-59.

[14:8] - Calendar minutes in BCD, the range 0-59.

[21:16] - Calendar hours in BCD, value depends on the 12/24-hour mode.

12HR: [21]:0 = AM, 1 = PM, [20:16] = 1 - 12;

24HR: [21:16] = 0-23.

[22] - Selects the 12/24-hour mode: 1 - 12-hour, 0 - 24-hour.

[26:24] - A calendar day of the week, the range 1 - 7, where 1 - Sunday.

[5:0] - A calendar day of a month in BCD, the range 1-31.

[12:8] - A calendar month in BCD, the range 1-12.

[23:16] - A calendar year in BCD, the range 0-99.

note

Ensure that the parameters are presented in the BCD format. Use the ConstructTimeDate() function to construct BCD time and date values. Refer to ConstructTimeDate() function description for more details about the RTC_TIME and RTC_DATE bit fields format.

The RTC AHB registers can be updated only under condition that the Write bit is set and the RTC busy bit is cleared (RTC_BUSY = 0). Call the Cy_RTC_WriteEnable(CY_RTC_WRITE_ENABLED) and ensure that

Cy_RTC_WriteEnable() returned CY_RTC_SUCCESS. Then you can call Cy_RTC_SyncToRtcAhbDateAndTime(). Do not forget to clear the RTC Write bit to finish an RTC register update by calling Cy_RTC_WriteEnable(CY_RTC_WRITE_DISABLED) after you executed Cy_RTC_SyncToRtcAhbDateAndTime(). Ensure that Cy_RTC_WriteEnable() returned CY_RTC_SUCCESS.

Parameters

  • timeBcd – The BCD-formatted time variable which has the same bit masks as the RTC_TIME register:

  • dateBcd – The BCD-formatted time variable which has the same bit masks as the RTC_DATE register:

__STATIC_INLINE void Cy_RTC_SyncToRtcAhbAlarm (uint32_t alarmTimeBcd, uint32_t alarmDateBcd, cy_en_rtc_alarm_t alarmIndex)

This function updates new alarm time and date into the alarm tire and date RTC AHB registers.

[0:6] - Alarm seconds in BCD, the range 0-59.

[7] - Alarm seconds Enable: 0 - ignore, 1 - match.

[14:8] - Alarm minutes in BCD, the range 0-59.

[15] - Alarm minutes Enable: 0 - ignore, 1 - match.

[21:16] - Alarm hours in BCD, value depending on the 12/24-hour mode (RTC_CTRL_12HR)

12HR: [21]:0 = AM, 1 = PM, [20:16] = 1 - 12;

24HR: [21:16] = the range 0-23.

[23] - Alarm hours Enable: 0 - ignore, 1 - match.

[26:24] - An alarm day of the week, the range 1 - 7, where 1 - Monday.

[31] - An alarm day of the week Enable: 0 - ignore, 1 - match.

note

Ensure that the parameters are presented in the BCD format. Use the ConstructTimeDate() function to construct BCD time and date values. Refer to ConstructTimeDate() function description for more details about the RTC ALMx_TIME and ALMx_DATE bit-fields format.

The RTC AHB registers can be updated only under condition that the Write bit is set and the RTC busy bit is cleared (RTC_BUSY = 0). Call the Cy_RTC_WriteEnable(CY_RTC_WRITE_ENABLED) and ensure that

Cy_RTC_WriteEnable() returned CY_RTC_SUCCESS. Then you can call Cy_RTC_SyncToRtcAhbDateAndTime(). Do not forget to clear the RTC Write bit to finish an RTC register update by calling the Cy_RTC_WriteEnable(CY_RTC_WRITE_DISABLED) after you executed Cy_RTC_SyncToRtcAhbDateAndTime(). Ensure that Cy_RTC_WriteEnable() returned CY_RTC_SUCCESS.

Parameters

  • alarmTimeBcd – The BCD-formatted time variable which has the same bit masks as the ALMx_TIME register time fields:

  • alarmDateBcd –

    The BCD-formatted date variable which has the same bit masks as the ALMx_DATE register date fields:

    [5:0] - An alarm day of a month in BCD, the range 1-31.

    [7] - An alarm day of a month Enable: 0 - ignore, 1 - match.

    [12:8] - An alarm month in BCD, the range 1-12.

    [15] - An alarm month Enable: 0 - ignore, 1 - match.

    [31] - The Enable alarm: 0 - Alarm is disabled, 1 - Alarm is enabled.

  • alarmIndex – The alarm index to be configured, see cy_en_rtc_alarm_t.

__STATIC_INLINE uint32_t Cy_RTC_ConvertBcdToDec (uint32_t bcdNum)

Converts an 8-bit BCD number into an 8-bit hexadecimal number.

Each byte is converted individually and returned as an individual byte in the 32-bit variable.

For example, for 0x11223344 BCD number, the function returns 0x2C in hexadecimal format.

note

This API is available for CAT1A devices.

Parameters

bcdNum – An 8-bit BCD number. Each byte represents BCD.

Returns

decNum An 8-bit hexadecimal equivalent number of the BCD number.

__STATIC_INLINE uint32_t Cy_RTC_ConvertDecToBcd (uint32_t decNum)

Converts an 8-bit hexadecimal number into an 8-bit BCD number.

Each byte is converted individually and returned as an individual byte in the 32-bit variable.

For example, for 0x11223344 hexadecimal number, the function returns 0x20 BCD number.

note

This API is available for CAT1A devices.

Parameters

decNum – An 8-bit hexadecimal number. Each byte is represented in hex. 0x11223344 -> 0x20 hex format.

Returns

An 8-bit BCD equivalent of the passed hexadecimal number.

struct cy_stc_rtc_config_t
#include <>

This is the data structure that is used to configure the rtc time and date values.

Public Members

uint32_t sec

Seconds value, range [0-59].

uint32_t min

Minutes value, range [0-59].

uint32_t hour

Hour, range depends on hrFormat, if hrFormat = CY_RTC_24_HOURS, range [0-23]; If hrFormat = CY_RTC_12_HOURS, range [1-12] and appropriate AM/PM day period should be set (amPm)

cy_en_rtc_am_pm_t amPm

AM/PM hour period, see cy_en_rtc_am_pm_t.

This element is actual when hrFormat = CY_RTC_12_HOURS. The firmware ignores this element if hrFormat = CY_RTC_24_HOURS

cy_en_rtc_hours_format_t hrFormat

Hours format, see cy_en_rtc_hours_format_t.

uint32_t dayOfWeek

Day of the week, range [1-7], see Day of the week definitions.

uint32_t date

Date of month, range [1-31].

uint32_t month

Month, range [1-12].

See Month definitions

uint32_t year

Year, range [0-99].

struct cy_stc_rtc_alarm_t
#include <>

Decimal data structure that is used to save the Alarms.

Public Members

uint32_t sec

Alarm seconds, range [0-59].

The appropriate ALARMX interrupt is be asserted on matching with this value if secEn is previous enabled (secEn = 1)

cy_en_rtc_alarm_enable_t secEn

Enable alarm on seconds matching, see cy_en_rtc_alarm_enable_t.

uint32_t min

Alarm minutes, range [0-59].

The appropriate ALARMX interrupt is be asserted on matching with this value if minEn is previous enabled (minEn = 1)

cy_en_rtc_alarm_enable_t minEn

Enable alarm on minutes matching, see cy_en_rtc_alarm_enable_t.

uint32_t hour

Alarm hours, range [0-23] The appropriate ALARMX interrupt is be asserted on matching with this value if hourEn is previous enabled (hourEn = 1)

cy_en_rtc_alarm_enable_t hourEn

Enable alarm on hours matching, see cy_en_rtc_alarm_enable_t.

uint32_t dayOfWeek

Alarm day of the week, range [1-7] The appropriate ALARMX interrupt is be asserted on matching with this value if dayOfWeek is previous enabled (dayOfWeekEn = 1)

cy_en_rtc_alarm_enable_t dayOfWeekEn

Enable alarm on day of the week matching, see cy_en_rtc_alarm_enable_t.

uint32_t date

Alarm date, range [1-31].

The appropriate ALARMX interrupt is be asserted on matching with this value if dateEn is previous enabled (dateEn = 1)

cy_en_rtc_alarm_enable_t dateEn

Enable alarm on date matching, see cy_en_rtc_alarm_enable_t.

uint32_t month

Alarm Month, range [1-12].

The appropriate ALARMX interrupt is be asserted on matching with this value if dateEn is previous enabled (dateEn = 1)

cy_en_rtc_alarm_enable_t monthEn

Enable alarm on month matching, see cy_en_rtc_alarm_enable_t.

cy_en_rtc_alarm_enable_t almEn

Enable Alarm for appropriate ALARMX, see cy_en_rtc_alarm_enable_t.

If all alarm structure elements are enabled (almEn = CY_RTC_ALARM_ENABLE) the alarm interrupt is be asserted every second.

struct cy_stc_rtc_dst_format_t
#include <>

This is DST structure for DST feature setting.

Structure is combined with the fixed format and the relative format. It is used to save the DST time and date fixed or relative time format.

Public Members

cy_en_rtc_dst_format_t format

DST format.

See /ref cy_en_rtc_dst_format_t. Based on this value other structure elements should be filled or could be ignored

uint32_t hour

Should be filled for both format types.

Hour is always presented in 24hour format, range[0-23]

uint32_t dayOfMonth

Day of Month, range[1-31].

This element should be filled if format = CY_RTC_DST_FIXED. Firmware calculates this value in condition that format = CY_RTC_DST_RELATIVE is selected

uint32_t weekOfMonth

Week of month, range[1-6].

This element should be filled if format = CY_RTC_DST_RELATIVE. Firmware calculates dayOfMonth value based on weekOfMonth and dayOfWeek values

uint32_t dayOfWeek

Day of the week, this element should be filled in condition that format = CY_RTC_DST_RELATIVE.

Range[1- 7], see Day of the week definitions. Firmware calculates dayOfMonth value based on dayOfWeek and weekOfMonth values

uint32_t month

Month value, range[1-12], see Month definitions.

This value should be filled for both format types

struct cy_stc_rtc_dst_t
#include <>

This is the DST structure to handle start DST and stop DST.

Public Members

cy_stc_rtc_dst_format_t startDst

DST start time structure.

cy_stc_rtc_dst_format_t stopDst

DST stop time structure.