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
• Daylight Savings Time adjustment

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 can be used to format date and time
        // into string. It comes under the header file "time.h".
        // (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
    }
}
 
 
cy_rslt_t 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,
    };
 
    // 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,
    };
 
    // Initialize RTC
    result = cyhal_rtc_init(&my_rtc);
 
    // Update the current time and date to the RTC peripheral
    if (CY_RSLT_SUCCESS == result)
    {
        result = cyhal_rtc_write(&my_rtc, &new_date_time);
    }
 
    if (CY_RSLT_SUCCESS == result)
    {
        // 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);
 
        result = cyhal_rtc_set_alarm(&my_rtc, &alarm_date_time, alarm_active);
    }
 
    return result;
}
 
 

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.__unnamed6__
struct	cyhal_rtc_dst_t.__unnamed6__.__unnamed8__

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...
cy_rslt_t	cyhal_rtc_init_cfg (cyhal_rtc_t *obj, const cyhal_rtc_configurator_t *cfg)
	Initialize the RTC peripheral using a configurator generated configuration struct. 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_write_direct (cyhal_rtc_t *obj, uint32_t sec, uint32_t min, uint32_t hour, uint32_t day, uint32_t month, uint32_t year)
	Write the specified time and date values 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.__unnamed6__	__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.__unnamed6__

union cyhal_rtc_dst_t.__unnamed6__

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

cyhal_rtc_dst_t.__unnamed6__.__unnamed8__

struct cyhal_rtc_dst_t.__unnamed6__.__unnamed8__

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.

Note

In areas of the world that practice DST, when it should begin and end is not unique. It can either be in fixed DST format or in relative DST format.

Enumerator
CYHAL_RTC_DST_RELATIVE	Relative DST format. eg: Begins on the last Sunday of March and ends on the last Sunday of October.
CYHAL_RTC_DST_FIXED	Fixed DST format. eg: Begins on 21st March and ends on 21st September.

Function Documentation

cyhal_rtc_init()

cy_rslt_t cyhal_rtc_init

(

cyhal_rtc_t *

obj

)

Initialize the RTC peripheral.

Power up 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.

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_init_cfg()

cy_rslt_t cyhal_rtc_init_cfg	(	cyhal_rtc_t *	obj,
		const cyhal_rtc_configurator_t *	cfg
	)

Initialize the RTC peripheral using a configurator generated configuration struct.

Power up 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.
[in]	cfg	Configuration structure generated by a configurator.

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_write_direct()

cy_rslt_t cyhal_rtc_write_direct	(	cyhal_rtc_t *	obj,
		uint32_t	sec,
		uint32_t	min,
		uint32_t	hour,
		uint32_t	day,
		uint32_t	month,
		uint32_t	year
	)

Write the specified time and date values to the RTC peripheral.

Parameters

[in]	obj	RTC object
[in]	sec	Second to set (0-59)
[in]	min	Minute to set (0-59)
[in]	hour	Hour to set (0-23)
[in]	day	Day of month to set (1-31)
[in]	month	Month to set (1-12)
[in]	year	4-digit year to set

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.

Calling this function will allow alarms to account for daylight saving time. This means that the RTC will be adjusted when a daylight saving time transition occurs, meaning times passed to cyhal_rtc_set_alarm() will be interpreted as being in DST/not in DST as appropriate.

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