4. Demonstration Example - Alert Description¶

This section demonstrates a possible implementation of an alert mechanism. In such cases, time accuracy is not as critical as in RTC operations and therefore SW timers, like the ones offered by freeRTOS, can be used for triggering alerts.

Fig. 8 Application Alerts SW FSM - Initialization Process

Fig. 9 Application Alerts SW FSM - Main Execution Path

Fig. 10 Application Alerts SW FSM - Main Execution Path Continued

4.1. Application Structure of Alert Functionality¶

The key goal of this task is for the device to trigger alerts following a freeRTOS event. The code features three different alert classes: Seconds Class, Minutes Class and Hours Class. Depending on the preferred time resolution, the developer is free to choose any of the classes or a combination or all of them at the same time.

So far, the provided demonstration example features two different types of alert:
- One type of alert uses the breath timer and the white led of the chip to blink led D1 on Pro DevKit at a constant frequency. At any time, alerts can be disabled by pressing the K1 button on Pro DevKit. To enable blinking alerts, the developer should set TIME_ALERT_BREATH_TIMER_EN to ‘1’. Please note that blinking functionality is not standard feature of the alert mechanism.
- The second type of alert, which is enabled by default, uses callback functions. The developer can define a function that is called automatically at each alert event. Please note that this callback function is the same regardless of the alert class that has been configured to trigger alerts. For this reason, the callback function passes a dedicated variable that should be used by the developer to determine the source of the alert event. For user’s convenience, the sample code exhibits macros that should be used to determine the alert source.

Code snippet of the user-defined callback function:

/*
 * User-defined callback function that is called upon an alert event.
 * Note that all alert classes will call the same function. Thus, it
 * is recommended that the developer will use \p [source] to determine
 * the source of the alert.
 */
void my_alert_cb(uint8_t source)
{

        /*
         * Check whether [Hours Class] triggered an alert.
         * Then notify [prvALERT_Task] task accordingly.
         */
        if (source & ALERT_SOURCE_HOURS_Msk) {

                // Do something...
        }

        /*
         * Check whether [Minutes Class] triggered an alert.
         * Then notify [prvALERT_Task] task accordingly.
         */
        if (source & ALERT_SOURCE_MINUTES_Msk) {

                // Do something...
        }

        /*
         * Check whether [Seconds Class] triggered an alert.
         * Then notify [prvALERT_Task] task accordingly.
         */
        if (source & ALERT_SOURCE_SECONDS_Msk) {

                // Do something...

        }
}

Note

The device must remain in active mode while the breath timer is functioning. By pressing the K1 button on Pro DevKit, LED D1 will stop blinking and the device will return to its initial state, that is extended sleep mode.

4.2. Alert Related APIs and Macros¶

The provided sample code exhibits a set of APIs that can be used to perform alert operations. Table 5 briefly explains the most useful APIs for alerts.

Table 5 APIs for the Alert Functionality¶
API Name	Description
`time_alert_init()`	This function initializes all the resources required for the alert mechanism. It should be the first invoked API before any other alert related operation.
`time_alert_register_cb()`	This function register callback function to be triggered upon an alert event. Note: All the three alert classes call the same callback function. It’s, user’s responsibility to identify the source of the alert event. Developer can use the appropriate masks (starting with `ALERT_SOURCE_xxx_xxx`).
`time_alert_unregister_cb()`	This function unregisters any previously registered callback function.
`time_alert_class_set()`	This function sets alert events for a specific alert class, that is either Hours, Minutes or Seconds.
`time_alert_class_set_all()`	This function sets alert events for all the three alert classes at once. This function can be considered as a shortcut function.
`time_alert_class_clear()`	This function disables/clears alert events either for an individual alert class, or for all the three at once.
`void (*alert_cb) (uint8_t class)`	Function prototype for callback functions.

Table 6 briefly explains the most useful macros for alerts.

Table 6 Macros for the Alert Functionality¶
Macro Name	Description
`SET_ALERT_CLASS`	Use this enum to specify an alert class during setting related operations.
`CLEAR_ALERT_CLASS`	Use this enum to specify an alert class/classes during clearance related operations.
`ALERT_SOURCE_HOURS_Msk`	Use this mask to check whether the source of an alert event is [Hours].
`ALERT_SOURCE_MINUTES_Msk`	Use this mask to check whether the source of an alert event is [Minutes].
`ALERT_SOURCE_SECONDS_Msk`	Use this mask to check whether the source of an alert event is [Seconds].