RTC (Real-Time Clock)

group group_hal_rtc

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 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);
}

Typedefs

typedef void (*cyhal_rtc_event_callback_t)(void *callback_arg, cyhal_rtc_event_t event)

Handler for RTC events (eg: alarm)

Enums

enum cyhal_rtc_event_t

cyhal_rtc_event_t: RTC interrupt triggers.

Values:

enumerator CYHAL_RTC_ALARM

Alarm triggered event.

enum cyhal_rtc_dst_format_t

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.

Values:

enumerator CYHAL_RTC_DST_RELATIVE

Relative DST format.

eg: Begins on the last Sunday of March and ends on the last Sunday of October.

enumerator CYHAL_RTC_DST_FIXED

Fixed DST format.

eg: Begins on 21st March and ends on 21st September.

Functions

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. NOTE: Previously set time configurations are retained. This will only reset the time if no prior configuration can be determined.

Parameters

obj – [out] 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

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

obj – [inout] RTC object

bool cyhal_rtc_is_enabled(cyhal_rtc_t *obj)

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

Parameters

obj – [in] RTC object

Returns

Whether the RTC is enabled or not

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

Get the current time and date from the RTC peripheral.

Parameters
Returns

The status of the read request

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
Returns

The status of the write request

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

  • obj – [in] RTC object

  • start – [in] When Day Light Savings time should start

  • stop – [in] When Day Light Savings time should end

Returns

The status of the set_dst request

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

obj – [in] RTC object

Returns

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

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
Returns

The status of the set_alarm request

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

  • obj – [in] RTC object

  • seconds – [in] 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

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

  • obj – [in] The RTC object

  • callback – [in] The callback handler which will be invoked when the alarm event fires

  • callback_arg – [in] Generic argument that will be provided to the callback when called

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

  • obj – [in] The RTC object

  • event – [in] The RTC event type

  • intr_priority – [in] The priority for NVIC interrupt events

  • enable – [in] True to turn on interrupts, False to turn off

struct cyhal_alarm_active_t
#include <>

Defines which fields should be active for the alarm.

Public Members

uint8_t en_sec

Enable match of seconds.

uint8_t en_min

Enable match of minutes.

uint8_t en_hour

Enable match of hours.

uint8_t en_day

Enable match of day of week.

uint8_t en_date

Enable match of date in month.

uint8_t en_month

Enable match of month.

struct cyhal_rtc_dst_t
#include <>

Day Light Savings Time (DST) structure for setting when to apply.

It allows to set the DST time and date using a fixed or relative time format.

Public Members

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::[anonymous] [anonymous]

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__

Public Members

uint32_t dayOfMonth

Day of Month, range[1-31].

struct cyhal_rtc_dst_t::[anonymous]::[anonymous] [anonymous]

Anonymous struct specifying the week number plus day of week.

cyhal_rtc_dst_t.__unnamed__.__unnamed__

Public Members

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