Hardware Abstraction Layer (HAL)
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

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
}
RTC object.
Definition: cyhal_hw_types.h:1164
cy_rslt_t cyhal_rtc_write(cyhal_rtc_t *obj, const struct tm *time)
Write the specified time and date to the RTC peripheral.
cy_rslt_t cyhal_rtc_read(cyhal_rtc_t *obj, struct tm *time)
Get the current time and date from the RTC peripheral.
cy_rslt_t cyhal_rtc_init(cyhal_rtc_t *obj)
Initialize the RTC peripheral.
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:426
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:453

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_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;
}
uint8_t en_sec
Enable match of seconds.
Definition: cyhal_rtc.h:103
void(* cyhal_rtc_event_callback_t)(void *callback_arg, cyhal_rtc_event_t event)
Handler for RTC events (eg: alarm)
Definition: cyhal_rtc.h:148
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.
void cyhal_rtc_register_callback(cyhal_rtc_t *obj, cyhal_rtc_event_callback_t callback, void *callback_arg)
Register a RTC event callback handler.
cyhal_rtc_event_t
RTC interrupt triggers.
Definition: cyhal_rtc.h:96
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.
@ CYHAL_RTC_ALARM
Alarm triggered event.
Definition: cyhal_rtc.h:97
Defines which fields should be active for the alarm.
Definition: cyhal_rtc.h:102

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

RTC interrupt triggers.

Enumerator
CYHAL_RTC_ALARM 

Alarm triggered event.

◆ 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]objPointer 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]objPointer to an RTC object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]cfgConfiguration 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]objRTC 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]objRTC 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]objRTC object
[out]timeThe 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]objRTC object
[in]timeThe 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]objRTC object
[in]secSecond to set (0-59)
[in]minMinute to set (0-59)
[in]hourHour to set (0-23)
[in]dayDay of month to set (1-31)
[in]monthMonth to set (1-12)
[in]year4-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]objRTC object
[in]startWhen Day Light Savings time should start
[in]stopWhen 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]objRTC 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]objRTC object
[in]timeThe alarm time to be set (see: https://en.cppreference.com/w/cpp/chrono/c/tm)
[in]activeThe 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]objRTC object
[in]secondsThe 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]objThe RTC object
[in]callbackThe callback handler which will be invoked when the alarm event fires
[in]callback_argGeneric 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]objThe RTC object
[in]eventThe RTC event type
[in]intr_priorityThe priority for NVIC interrupt events
[in]enableTrue to turn on interrupts, False to turn off