RTC alarm

The built-in RTC supports creating an alarm that triggers at a specific time, allowing the firmware to detect and respond accordingly. Alarms can be configured to trigger once per day, per hour, or per minute.

---

Simple alarm

This section demonstrates setting a simple RTC alarm that is checked using polling. The firmware continuously checks the alarm flag and responds when it is triggered.

// Initialize RTC in 24-hour format and reset it
inkplate.rtc.begin(RTC_HOURFORMAT_24, true);

// Set the time and date
inkplate.rtc.setTime(12, 24, 25, 0); // Set time to 12:24:25
inkplate.rtc.setDate(29, 5, 24, RTC_WEEKDAY_MONDAY); // Set date to 29/5/2024, Monday

// Enable an alarm at 12:24:35 on the same day
inkplate.rtc.enableSimpleAlarm(29, 12, 24, 35, RTC_ALARM_A, RTC_ALARMMASK_DATEWEEKDAY | RTC_ALARMMASK_HOURS | RTC_ALARMMASK_MINUTES);

// Use polling method to detect alarm event
while(true)
{
    // Check the RTC
    if (inkplate.rtc.checkForAlarm())
    {
        // Alarm is detected!
        // Print out the message
        inkplate.setCursor(320, 450);
        inkplate.println("ALARM EVENT!");
        // Let's display the message and halt the code here
        inkplate.display();

        // You can of course continue the code from here in any other use case
        // Use inkplate.rtc.checkForAlarm(true) to clear the alarm flag
    }
    delay(1000); // Wait a second between polling the RTC
}

inkplate.rtc.enableSimpleAlarm()

Enables a simple RTC alarm without interrupts. The alarm must be checked using polling.

Returns: none

Function parameters:

Type	Name	Description
uint8_t	_d	Day of the month to trigger the alarm.
uint8_t	_h	Hour value for the alarm.
uint8_t	_m	Minute value for the alarm.
uint8_t	_s	Second value for the alarm.
uint32_t	_alarm	Select which alarm to use. Use RTC_ALARM_A or RTC_ALARM_B (limited support for Alarm B).
uint32_t	_alarmMask	Defines when the alarm should trigger. See the table below.
uint8_t	_pmAm	Optional. PM/AM indicator (only relevant in 12-hour mode).
uint32_t	_dayLightSaving	Optional. Daylight saving setting: RTC_DAYLIGHTSAVING_SUB1H, RTC_DAYLIGHTSAVING_ADD1H, or RTC_DAYLIGHTSAVING_NONE.

The alarm masks essentially can filter out certain information for the alarm, making it easy to tirgger it always at a certain time. If you want to use multiple flags, they have to be OR'd together:

Alarm Frequency	Mask Definition
Once per day	RTC_ALARMMASK_DATEWEEKDAY
Once per hour	RTC_ALARMMASK_DATEWEEKDAY
Once per minute	RTC_ALARMMASK_DATEWEEKDAY
Every second	RTC_ALARMMASK_ALL (ignores all fields, triggers continuously)

inkplate.rtc.checkForAlarm()

Checks if an RTC alarm has been triggered.

Returns: Returns true if the alarm was triggered, otherwise false.

Function parameters:

Type	Name	Description
bool	_clearFlag	Set to true to clear the alarm flag immediately, false to keep it active.

---

Interrupt Alarm

The RTC alarm can also generate an interrupt instead of requiring polling. The alarm event can wake up the MCU from sleep or trigger an action immediately. To use this, you will need to globally declare a volatile bool to use as the alarm flag and a function which modifies this flag:

volatile bool alarmFlag = false;
// Function will be called on every alarm event
void alarmFunction()
{
    alarmFlag = true;
}

And then, in the body of the sketch:

// Initialize RTC in 24-hour format and reset it
inkplate.rtc.begin(RTC_HOURFORMAT_24, true);

// Set the time and date
inkplate.rtc.setTime(12, 24, 25, 0); // Set time to 12:24:25
inkplate.rtc.setDate(29, 5, 24, RTC_WEEKDAY_MONDAY); // Set date to 29/5/2024, Monday

// Enable an alarm at 12:24:35 on the same day
inkplate.rtc.enableAlarm(29, 12, 24, 35, RTC_ALARM_A, RTC_ALARMMASK_DATEWEEKDAY | RTC_ALARMMASK_HOURS | RTC_ALARMMASK_MINUTES);

// Enable the alarm interrupt
inkplate.rtc.enableAlarmInterrupt(alarmFunction);

// Let's periodically check for the interrupt  flag
while(true)
{
    // Check for alarm event
    if (alarmFlag)
    {
        // Clear the flag
        alarmFlag = false;
        // Print out the message
        inkplate.print("Interrupt alarm!");
        inkplate.display();
        // Continue alarm-handling code here as you wish
        // In this example, just stop the sketch
        while(true)
            delay(100);
    }
}

inkplate.rtc.enableAlarmInterrupt()

Enables an RTC alarm interrupt, triggering a callback function when the alarm occurs.

Returns: none

Function parameters:

Type	Name	Description
void(*)()	_f	Pointer to callback function that will be executed when the alarm triggers.

inkplate.rtc.disableAlarmInterrupt()

Disables the RTC alarm interrupt, preventing further callback executions.

Returns: none

---

Alarm output

Other than just being detected internally within Inkplate, it's possible to output a pulse output the STM32 pin PC13 by calling inkplate.rtc.setAlarmOutput():

inkplate.rtc.setAlarmOutput(true, RTC_OUTPUT_ALARMA);

inkplate.rtc.setAlarmOutput()

Routes the RTC alarm signal to a GPIO pin, allowing external hardware to detect the alarm event.

Returns: none

Function parameters:

Type	Name	Description
bool	_outEn	Set to true to enable the RTC Alarm Output on the GPIO pin, or false to disable it.
uint32_t	_alarm	Select which alarm output to use: RTC_OUTPUT_ALARMA (pin PC13), RTC_OUTPUT_ALARMB, or RTC_OUTPUT_DISABLE.

⚠️

Using RTC_OUTPUT_ALARMB is not yet implemented!

---

Full examples

For full working code examples, which provide a great overwiew, a real-world use scenario and code comments, see the links below:

Inkplate_6_Motion_Simple_Alarm.ino

How to set a polling alarm with the internal RTC on Inkplate 6 MOTION

Inkplate_6_Motion_RTC_Alarm_Interrupt.ino

Full example on how to detect alarm via interrupt

Inkplate_6_Motion_RTC_Alarm_Output.ino

Pulse an external LED when the alarm is triggered