3. Demonstration Example - RTC Description

This section analyzes an application example which demonstrates using the RTC functionality. The application also demonstrates alerts based on freeRTOS Timers functionality. The example uses the freertos_retarget sample code, found in the SDK, as its framework. Two additional tasks have been created: one task performs RTC measurements and, based on the results, computes the current date and time in standard format; the second task performs alert operations based on freeRTOS events. The code also enables the wake-up timer for handling external events. To aid readability, using the alert functionality is described in the next section.

3.1. Application Structure of RTC Functionality

Fig. 6 Application SW RTC FSM - Initialization Process

Fig. 7 Application SW RTC FSM - Main Execution Path

1. The key goal of this task is for the device to calculate the current time and date following an event. For demonstration purposes, the button K1 (P1.6) on the Pro DevKit has been configured as a wake-up pin. For more information on how to configure and set a pin to handle external events, please read the External Interruption tutorial. At each external event (produced at every button press - K1 on Pro Devkit) a dedicated callback function named wkup_cb() is triggered. This callback executes many operations including the activation of prvRTC_Task().

2. In this freeRTOS task, the current date and time is read through the RTC functionality. Depending on the value of SW_RTC_DBG_MESSAGES_CONSOLE, the current date and time are printed out on the serial console.

3.2. Time Related APIs and Macros

The sample code has a set of APIs that can be used to perform time measurements. Table 3 briefly explains the most useful APIs that should be used for time measurement operations.

Table 3 APIs for the RTC Functionality

API Name	Description
sw_rtc_init()	This function initializes all the resources required for the SW RTC mechanism. It should be the first invoked API before any other SW RTC related operation.
sw_rtc_date_time_read()	This function reads the current date and time. It should be considered as a shortcut function since it combines both sw_rtc_date_read() and sw_rtc_time_read(). Note: This function can be called at any time from any task without overlap issues.
sw_rtc_date_read()	This function reads the current date only. Note: This function can be called at any time from any task without overlap issues.
sw_rtc_time_read()	This function reads the current time only. Note: This function can be called at any time from any task without overlap issues.
sw_rtc_date_write()	This function sets the current date and time. It should be considered as a shortcut function since it combines both sw_rtc_date_write() and sw_rtc_time_write(). Sanity checks are performed to check the validity of the assigned values (values out of the allowable boundaries). Note: This function can be called at any time from any task without overlap issues. Note: The weekday is calculated automatically by the code.
sw_rtc_date_write()	This function sets the current date only. Sanity checks are performed to check the validity of the assigned values (values out of the allowable boundaries). Note: This function can be called at any time from any task without overlap issues. Note: The weekday is calculated automatically by the code.
sw_rtc_time_write()	This function sets the current time only. Sanity checks are performed to check the validity of the assigned values (values out of the allowable boundaries). Note: This function can be called at any time from any task without overlap issues.

Table 4 briefly explains the most useful structures for SW RTC related measurements.

Table 4 Structures for the RTC Functionality

Structure Name	Description
sw_rtc_date_time_t	This structure contains parameters both for setting/reading the current date and time.
sw_rtc_date_t	This structure contains parameters for setting/reading the current date only.
sw_rtc_time_t	This structure contains parameters for setting/reading the current time only.