RTC (Real-Time Clock)

General Description

High level interface for interacting with the real-time clock (RTC).

The real time clock provides tracking of the current time and date, as well as the ability to trigger a callback at a specific time in the future.

Features

• Configurable interrupt and callback assignment on RTC event cyhal_rtc_event_t
• Set alarm for a specific time and date cyhal_rtc_set_alarm

Quick Start

Initialise the RTC using cyhal_rtc_init. Set the current time and date using cyhal_rtc_write.
See Snippet 1: Initialize RTC, write and read current time and date to initialize RTC, read and write current date and time to the RTC peripheral. See Snippet 2: RTC Alarm using Callbacks to set an alarm event on a specific time and date.

Code snippets

Snippet 1: Initialize RTC, write and read current time and date

The following code snippet initialises the RTC using the cyhal_rtc_init. The current date and time are set using cyhal_rtc_write. The current date and time is read from the RTC using cyhal_rtc_read. The time structure tm , contains the calendar date and time which are broken down into its components. This structure is declared in standard C library time.h which is included by HAL.

    /* Structure tm stores years since 1900 */
    #define TM_YEAR_BASE (1900u)

    cy_rslt_t result;
    cyhal_rtc_t my_rtc;
    char buffer[80];

    int mday = 3, month = 3, year = 2020; /* Day of month, month and year */
    int hours = 8, minutes = 10, seconds = 10; /* Hours, minutes and seconds */
    int wday = 3; /* Days from Sunday. Sunday is 0, Monday is 1 and so on. */
    int dst = 0; /* Daylight Savings. 0 - Disabled, 1 - Enabled */

    /* Setting the tm structure as 08 HRS:10 MIN:10 SEC ; 3rd March 2020; Wednesday ; DST off */
    struct tm new_date_time =
    {
        .tm_sec = seconds,
        .tm_min = minutes,
        .tm_hour = hours,
        .tm_mday = mday,
        .tm_mon = month - 1,
        .tm_year = year - TM_YEAR_BASE,
        .tm_wday = wday,
        .tm_isdst = dst
    };
    struct tm current_date_time = {0};

    /* Initialize RTC */
    result = cyhal_rtc_init(&my_rtc);

    /* Update the current time and date to the RTC peripheral */
    result = cyhal_rtc_write(&my_rtc, &new_date_time);

    /* Get the current time and date from the RTC peripheral */
    result = cyhal_rtc_read(&my_rtc, &current_date_time);
    if (CY_RSLT_SUCCESS == result)
    {
       /* strftime() is a C library function which is used to format date and time into string.
        * It comes under the header file "time.h" which is included by HAL (See http://www.cplusplus.com/reference/ctime/strftime/)
        */
        strftime(buffer, sizeof(buffer), "%c", &current_date_time);
        /* Print the buffer in serial terminal to view the current date and time */
    }

Snippet 2: RTC Alarm using Callbacks

The following code snippet configures the RTC to trigger an alarm event on a specified date and time using cyhal_rtc_set_alarm. A callback is registered to handle the alarm event using cyhal_rtc_register_callback.

void cyhal_rtc_alarm_interrupt_handler(void *arg, cyhal_rtc_event_t event)
{
    (void)arg;
    if (event == CYHAL_RTC_ALARM )
    {
        /* ALARM HAS FIRED */
    }
}

void snippet_cyhal_set_alarm_callback(void)
{
     /* Structure tm stores years since 1900 */
    #define TM_YEAR_BASE (1900u)
    #define RTC_CALLBACK_ARG (NULL)
    #define RTC_INTERRUPT_PRIORITY (3u)

    cy_rslt_t result;
    cyhal_rtc_t my_rtc;

    /* Setting the tm structure as 08 HRS:10 MIN:10 SEC ; 3rd March 2020; Wednesday ; DST off */
    struct tm new_date_time =
    {
        .tm_sec = 10,
        .tm_min = 10,
        .tm_hour = 8,
        .tm_mday = 3,
        .tm_mon = 3 - 1,
        .tm_year = 2020 - TM_YEAR_BASE,
        .tm_wday = 3,
        .tm_yday = 61,
        .tm_isdst = 0,
    };
    /* Initialize RTC */
    result = cyhal_rtc_init(&my_rtc);
    CY_ASSERT(CY_RSLT_SUCCESS == result);

    /* Update the current time and date to the RTC peripheral */
    result = cyhal_rtc_write(&my_rtc, &new_date_time);

    /* Setting the tm structure to set alarm for 08 HRS:10 MIN:15 SEC ; 3rd March 2020; Wednesday ; DST off */
    struct tm alarm_date_time =
    {
        .tm_sec = 15,
        .tm_min = 10,
        .tm_hour = 8,
        .tm_mday = 3,
        .tm_mon = 3 - 1,
        .tm_year = 2020 - TM_YEAR_BASE,
        .tm_wday = 3,
        .tm_yday = 61,
        .tm_isdst = 0,
    };

    /* Set which fields should match to trigger an alarm event. The fields are set to trigger an alarm event on the
     * date and time specified using alarm_date_time structure.
     */
    cyhal_alarm_active_t alarm_active =
    {
        .en_sec = 1,
        .en_min = 1,
        .en_hour = 1,
        .en_day =  1,
        .en_date = 1,
        .en_month = 1,
    };

    cyhal_rtc_set_alarm(&my_rtc, &alarm_date_time,  alarm_active);
    /* Register a callback function to handle the alarm event */
    cyhal_rtc_register_callback(&my_rtc, (cyhal_rtc_event_callback_t)cyhal_rtc_alarm_interrupt_handler, RTC_CALLBACK_ARG);
    /* Enable the alarm event to trigger an interrupt */
    cyhal_rtc_enable_event(&my_rtc, CYHAL_RTC_ALARM, RTC_INTERRUPT_PRIORITY, true);
}

API Reference
	RTC HAL Results
	RTC specific return codes.

Data Structures
struct	cyhal_alarm_active_t
	Defines which fields should be active for the alarm. More...
struct	cyhal_rtc_dst_t
	Day Light Savings Time (DST) structure for setting when to apply. More...
union	cyhal_rtc_dst_t.__unnamed__
struct	cyhal_rtc_dst_t.__unnamed__.__unnamed__

Typedefs
typedef void(*	cyhal_rtc_event_callback_t) (void *callback_arg, cyhal_rtc_event_t event)
	Handler for RTC events (eg: alarm)

Enumerations
enum	cyhal_rtc_event_t { CYHAL_RTC_ALARM }
	RTC interrupt triggers. More...
enum	cyhal_rtc_dst_format_t {   CYHAL_RTC_DST_RELATIVE,   CYHAL_RTC_DST_FIXED }
	Enumeration used to configure the DST format. More...

Functions
cy_rslt_t	cyhal_rtc_init (cyhal_rtc_t *obj)
	Initialize the RTC peripheral. More...
void	cyhal_rtc_free (cyhal_rtc_t *obj)
	Deinitialize RTC. More...
bool	cyhal_rtc_is_enabled (cyhal_rtc_t *obj)
	Check if the RTC has the time set and is counting. More...
cy_rslt_t	cyhal_rtc_read (cyhal_rtc_t *obj, struct tm *time)
	Get the current time and date from the RTC peripheral. More...
cy_rslt_t	cyhal_rtc_write (cyhal_rtc_t *obj, const struct tm *time)
	Write the specified time and date to the RTC peripheral. More...
cy_rslt_t	cyhal_rtc_set_dst (cyhal_rtc_t *obj, const cyhal_rtc_dst_t *start, const cyhal_rtc_dst_t *stop)
	Set the start and end time for Day Light Savings. More...
bool	cyhal_rtc_is_dst (cyhal_rtc_t *obj)
	Checks to see if Day Light Savings Time is currently active. More...
cy_rslt_t	cyhal_rtc_set_alarm (cyhal_rtc_t *obj, const struct tm *time, cyhal_alarm_active_t active)
	Set an alarm (interrupt) for the specified time and date using the RTC peripheral. More...
cy_rslt_t	cyhal_rtc_set_alarm_by_seconds (cyhal_rtc_t *obj, const uint32_t seconds)
	Set an alarm (interrupt) at a specified number of seconds in the future. More...
void	cyhal_rtc_register_callback (cyhal_rtc_t *obj, cyhal_rtc_event_callback_t callback, void *callback_arg)
	Register a RTC event callback handler. More...
void	cyhal_rtc_enable_event (cyhal_rtc_t *obj, cyhal_rtc_event_t event, uint8_t intr_priority, bool enable)
	Configure RTC event (eg: alarm) enablement. More...

---

Data Structure Documentation

cyhal_alarm_active_t

struct cyhal_alarm_active_t

Data Fields
uint8_t	en_sec: 1	Enable match of seconds.
uint8_t	en_min: 1	Enable match of minutes.
uint8_t	en_hour: 1	Enable match of hours.
uint8_t	en_day: 1	Enable match of day of week.
uint8_t	en_date: 1	Enable match of date in month.
uint8_t	en_month: 1	Enable match of month.

cyhal_rtc_dst_t

struct cyhal_rtc_dst_t

Data Fields
cyhal_rtc_dst_format_t	format	DST format. See /ref cyhal_rtc_dst_format_t. Based on this value other structure elements should be filled or could be ignored
uint32_t	hour	Hour in 24hour format, range[0-23].
union cyhal_rtc_dst_t	__unnamed__	Anonymous union for the day as either a specific day (dayOfMonth) or as a week number (weekOfMonth) plus day of week (dayOfWeek)
uint32_t	month	Month value, range[1-12].

cyhal_rtc_dst_t.__unnamed__

union cyhal_rtc_dst_t.__unnamed__

Data Fields
uint32_t	dayOfMonth	Day of Month, range[1-31].
__unnamed__	__unnamed__	Anonymous struct specifying the week number plus day of week.

cyhal_rtc_dst_t.__unnamed__.__unnamed__

struct cyhal_rtc_dst_t.__unnamed__.__unnamed__

Data Fields
uint32_t	dayOfWeek	Day of the week, starting on Sunday, range[0-6].
uint32_t	weekOfMonth	Week of month, range[0-5]. Where 5 => Last week of month

Enumeration Type Documentation

cyhal_rtc_event_t

enum cyhal_rtc_event_t

RTC interrupt triggers.

Enumerator
CYHAL_RTC_ALARM	Alarm triggered event.

cyhal_rtc_dst_format_t

enum cyhal_rtc_dst_format_t

Enumeration used to configure the DST format.

Enumerator
CYHAL_RTC_DST_RELATIVE	Relative DST format.
CYHAL_RTC_DST_FIXED	Fixed DST format.

Function Documentation

cyhal_rtc_init()

cy_rslt_t cyhal_rtc_init

(

cyhal_rtc_t *

obj

)

Initialize the RTC peripheral.

Powerup the RTC in preparation for access. This function must be called before any other RTC functions are called. This does not change the state of the RTC. It just enables access to it. NOTE: Before calling this, make sure all necessary System Clocks are setup correctly. Generally this means making sure the RTC has access to a crystal oscillator for optimal accuracy and operation in low power. NOTE: Previously set time configurations are retained. This will only reset the time if no prior configuration can be determined.

Parameters

[out]

obj

Pointer to an RTC object. The caller must allocate the memory for this object but the init function will initialize its contents.

Returns

The status of the init request

cyhal_rtc_free()

void cyhal_rtc_free

(

cyhal_rtc_t *

obj

)

Deinitialize RTC.

Frees resources associated with the RTC and disables CPU access. This only affects the CPU domain and not the time keeping logic. After this function is called no other RTC functions should be called except for rtc_init.

Parameters

[in,out]

obj

RTC object

cyhal_rtc_is_enabled()

bool cyhal_rtc_is_enabled

(

cyhal_rtc_t *

obj

)

Check if the RTC has the time set and is counting.

Parameters

[in]

obj

RTC object

Returns

Whether the RTC is enabled or not

cyhal_rtc_read()

cy_rslt_t cyhal_rtc_read	(	cyhal_rtc_t *	obj,
		struct tm *	time
	)

Get the current time and date from the RTC peripheral.

Parameters

[in]	obj	RTC object
[out]	time	The current time (see: https://en.cppreference.com/w/cpp/chrono/c/tm)

Returns

The status of the read request

cyhal_rtc_write()

cy_rslt_t cyhal_rtc_write	(	cyhal_rtc_t *	obj,
		const struct tm *	time
	)

Write the specified time and date to the RTC peripheral.

Parameters

[in]	obj	RTC object
[in]	time	The time to be set (see: https://en.cppreference.com/w/cpp/chrono/c/tm)

Returns

The status of the write request

cyhal_rtc_set_dst()

cy_rslt_t cyhal_rtc_set_dst	(	cyhal_rtc_t *	obj,
		const cyhal_rtc_dst_t *	start,
		const cyhal_rtc_dst_t *	stop
	)

Set the start and end time for Day Light Savings.

Parameters

[in]	obj	RTC object
[in]	start	When Day Light Savings time should start
[in]	stop	When Day Light Savings time should end

Returns

The status of the set_dst request

cyhal_rtc_is_dst()

bool cyhal_rtc_is_dst

(

cyhal_rtc_t *

obj

)

Checks to see if Day Light Savings Time is currently active.

This should only be called after cyhal_rtc_set_dst().

Parameters

[in]

obj

RTC object

Returns

Boolean indicating whether the current date/time is within the specified DST start/stop window.

cyhal_rtc_set_alarm()

cy_rslt_t cyhal_rtc_set_alarm	(	cyhal_rtc_t *	obj,
		const struct tm *	time,
		cyhal_alarm_active_t	active
	)

Set an alarm (interrupt) for the specified time and date using the RTC peripheral.

This requires that a callback handler is registered by cyhal_rtc_register_callback and that the CYHAL_RTC_ALARM event is enabled by cyhal_rtc_enable_event.

Parameters

[in]	obj	RTC object
[in]	time	The alarm time to be set (see: https://en.cppreference.com/w/cpp/chrono/c/tm)
[in]	active	The set of fields that are checked to trigger the alarm

Returns

The status of the set_alarm request

cyhal_rtc_set_alarm_by_seconds()

cy_rslt_t cyhal_rtc_set_alarm_by_seconds	(	cyhal_rtc_t *	obj,
		const uint32_t	seconds
	)

Set an alarm (interrupt) at a specified number of seconds in the future.

This requires that a callback handler is registered by cyhal_rtc_register_callback and that the CYHAL_RTC_ALARM event is enabled by cyhal_rtc_enable_event.

Parameters

[in]	obj	RTC object
[in]	seconds	The number of seconds in the future for the alarm to be set to. Because alarms cannot match the year (see cyhal_alarm_active_t) the maximum number of seconds allowed is 365d*24h*60m*60s == 31,536,000s

Returns

The status of the set_alarm_by_seconds request

cyhal_rtc_register_callback()

void cyhal_rtc_register_callback	(	cyhal_rtc_t *	obj,
		cyhal_rtc_event_callback_t	callback,
		void *	callback_arg
	)

Register a RTC event callback handler.

This function will be called when one of the events enabled by cyhal_rtc_enable_event occurs.

Parameters

[in]	obj	The RTC object
[in]	callback	The callback handler which will be invoked when the alarm event fires
[in]	callback_arg	Generic argument that will be provided to the callback when called

cyhal_rtc_enable_event()

void cyhal_rtc_enable_event	(	cyhal_rtc_t *	obj,
		cyhal_rtc_event_t	event,
		uint8_t	intr_priority,
		bool	enable
	)

Configure RTC event (eg: alarm) enablement.

When an enabled event occurs, the function specified by cyhal_rtc_register_callback will be called.

Parameters

[in]	obj	The RTC object
[in]	event	The RTC event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True to turn on interrupts, False to turn off