STM32RTC Library

Some STM32 RTCs (like stm32wl55) support different functional modes.

• MODE_BCD: Standard BCD mode for calendar.
• MODE_MIX: Combines BCD with a 32-bit free-running binary counter.
• MODE_BIN: Uses only the binary counter (time and date registers are not used).

Subsecond behavior by mode:

• In MIX or BCD mode, subseconds are expressed in milliseconds [0..999].
• In BIN mode, subseconds are expressed as [0..0xFFFFFFFF]. In this mode, getEpoch only returns the subsecond value (the time_t returned is invalid).

rtc.setBinaryMode(STM32RTC::MODE_MIX);
Binary_Mode currentMode = rtc.getBinaryMode();

STM32RTC uses the Singleton design pattern. You should not instantiate the class yourself; instead, retrieve the single existing instance using getInstance().

/* Get the rtc object */
STM32RTC& rtc = STM32RTC::getInstance();

By default, if a time is set, it will not be reset after a reboot. To force the RTC registers to reset upon calling begin(), pass true as the first argument.

You can check if a time has already been set using isTimeSet() to avoid overwriting the time on every boot.

// Reset registers on begin
rct.begin(true);

// Or reset and set 24h format
rct.begin(true, HOUR_24);

// Check if time is already set
if (!rtc.isTimeSet()) {
  rtc.setHours(hours);
  rtc.setMinutes(minutes);
  rtc.setSeconds(seconds);
}

The requirements for STM32RTC depend on the version of the library you are using in relation to the Arduino_Core_STM32 version:

• For STM32RTC 1.x.x:
  • Requires Arduino_Core_STM32 version $\ge$ 1.3.0 and $<$ 3.x.x
• For STM32RTC 2.x.x:
  • Requires Arduino_Core_STM32 version $\ge$ 3.x.x

Some STM32 RTC hardware supports a second alarm named ALARM_B. You can target this specific alarm by passing STM32RTC::ALARM_B to the alarm API functions.

rtc.attachInterrupt(myCallback, &myCallbackdata, STM32RTC::ALARM_B);
rtc.setAlarmDay(day, STM32RTC::ALARM_B);
rtc.setAlarmTime(hours, minutes, seconds + 5, 567, STM32RTC::ALARM_B);
rtc.enableAlarm(rtc.MATCH_DHHMMSS, STM32RTC::ALARM_B);

You can manually configure the RTC clock source and the (a)synchronous prescaler values. This configuration must be called before begin().

To ensure the clock runs at 1Hz, the following condition must be met: 1Hz = RTC CLK source / ((predivA + 1) * (predivS + 1))

To reset to default computed values, use (PREDIVA_MAX + 1) and (PREDIVS_MAX + 1) as arguments.

// Example configuration before begin()
rct.setClockSource(LSE_CLOCK, predivA, predivS);
rct.begin();

The STM32 RTC can generate a periodic one-second interrupt signal. This is native on stm32F1xx and mapped to the WakeUp interrupt on other STM32 MCUs. It is not available on some stm32F0 devices.

void myCallback() {
  // Periodic task
}

rct.attachSecondsInterrupt(myCallback);
rct.detachSecondsInterrupt();

The library provides methods to set and get time, date, and subseconds. Note that STM32 RTC architecture does not support months or years for alarms, so functions like setAlarmMonth or setAlarmYear are not supported.

Time and Date API

• void setTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds = 1000, AM_PM period = AM)
• void getTime(uint8_t *hours, uint8_t *minutes, uint8_t *seconds, uint32_t *subSeconds, AM_PM *period = nullptr)
• void setDate(uint8_t weekDay, uint8_t day, uint8_t month, uint8_t year)
• void getDate(uint8_t *weekDay, uint8_t *day, uint8_t *month, uint8_t *year)
• uint8_t getHours(AM_PM *period = nullptr)
• uint8_t getWeekDay(void)

Subseconds

• uint32_t getSubSeconds(void)
• void setSubSeconds(uint32_t subSeconds)

Note: STM32F1 and STM32L1xx (ULPM density) series do not support subseconds.

You can configure which clock source the RTC uses via setClockSource(). Supported sources depend on your specific STM32 hardware:

• LSI_CLOCK: Low Speed Internal clock.
• LSE_CLOCK: Low Speed External clock.
• HSI_CLOCK or HSE_CLOCK: High Speed Internal or External clock (availability depends on the MCU).

You can also manually set the prescalers using setPrediv() or getPrediv().

STM32RTC &rtc = STM32RTC::getInstance();
rtc.setClockSource(STM32RTC::LSE_CLOCK);

The library provides several ways to manage time and date components individually or as a group.

Time components:

• setTime(hours, minutes, seconds, subSeconds, period)
• setHours(), setMinutes(), setSeconds(), setSubSeconds()
• getTime(hours, minutes, seconds, subSeconds, period)
• getSeconds(), getMinutes(), getHours(), getSubSeconds()

Date components:

• setDate(day, month, year)
• setDay(), setMonth(), setYear()
• getDate(weekDay, day, month, year)
• getDay(), getMonth(), getYear(), getWeekDay()

STM32RTC &rtc = STM32RTC::getInstance();
rtc.setTime(14, 30, 0, 0, STM32RTC::AM);

uint8_t h, m, s;
rtc.getTime(&h, &m, &s);

The library provides helpers to work with time_t (Unix epoch) values.

• setEpoch(ts, subSeconds): Sets the RTC time based on a timestamp.
• getEpoch(subSeconds): Returns the current time as a time_t value.
• setY2kEpoch(ts): Sets time using a Y2K-based epoch.
• getAlarmEpoch(name): Returns the epoch time configured for a specific alarm.

STM32RTC &rtc = STM32RTC::getInstance();
time_t now = rtc.getEpoch();

The STM32RTC class uses a singleton pattern. Access the global instance using STM32RTC::getInstance(). To initialize the RTC, call begin(). You can optionally pass true to resetTime to reset the time on startup, and specify the Hour_Format (either HOUR_12 or HOUR_24).

STM32RTC &rtc = STM32RTC::getInstance();
rtc.begin(); // or rtc.begin(true, STM32RTC::HOUR_12);