STM32RTC

A RTC library for STM32.

Requirement

• Arduino_Core_STM32 version >= 1.3.0

API

This library is based on the Arduino RTCZero library. The library allows to take control of the internal RTC of the STM32 boards.

Singleton design pattern is used to ensure that only one STM32RTC instance is instantiated:

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

The following functions are not supported:

• void standbyMode(): use the STM32 Low Power library instead.
• uint8_t getAlarmMonth(): month not supported by STM32 RTC architecture.
• uint8_t getAlarmYear(): year not supported by STM32 RTC architecture.
• void setAlarmMonth(uint8_t month): month not supported by STM32 RTC architecture.
• void setAlarmYear(uint8_t year): year not supported by STM32 RTC architecture.
• void setAlarmDate(uint8_t day, uint8_t month, uint8_t year): month and year not supported by STM32 RTC architecture.

The following functions have been added to support specific STM32 RTC features:

RTC hours mode (12 or 24)

• void begin(Hour_Format format)

RTC clock source

• Source_Clock getClockSource(void) : get current clock source.
• void setClockSource(Source_Clock source) : this function must be called before begin().

RTC Asynchronous and Synchronous prescaler

• void getPrediv(int8_t *predivA, int16_t *predivS) : get (a)synchronous prescaler values if set else computed ones for the current clock source.
• void setPrediv(int8_t predivA, int16_t predivS) : set (a)synchronous prescaler values. This function must be called before begin(). Use -1 to reset value and use computed ones. Those values have to match the following conditions: 1Hz = RTC CLK source / ((predivA + 1) * (predivS + 1))

SubSeconds management

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

Hour format (AM or PM)

• uint8_t getHours(AM_PM *period = nullptr)
• void setHours(uint8_t hours, AM_PM period = AM)
• void setTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds = 1000, AM_PM period = AM)
• void setAlarmHours(uint8_t hours, AM_PM period = AM)
• uint8_t getAlarmHours(AM_PM *period)
• void setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, AM_PM period)

Week day configuration

• uint8_t getWeekDay(void)
• void setWeekDay(uint8_t weekDay)
• void setDate(uint8_t weekDay, uint8_t day, uint8_t month, uint8_t year)

Time and date configuration (added for convenience)

• void getTime(uint8_t *hours, uint8_t *minutes, uint8_t *seconds, uint32_t *subSeconds, AM_PM *period = nullptr)
• void getDate(uint8_t *weekDay, uint8_t *day, uint8_t *month, uint8_t *year)

Since STM32RTC version higher than 1.0.3

SubSeconds alarm management

Important note:

• STM32F1 and STM32L1xx (Ultra Low Power Medium (ULPM) density) series do not support subsecond.
• Subsecond “resolution” depends on synchronous prescaler value. Bigger than this value is, better resolution will get for subsecond.

• void setAlarmSubSeconds(uint32_t subSeconds)

• Updated API:

  • void setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds = 0, AM_PM period = AM)
  • uint32_t getEpoch(uint32_t *subSeconds = nullptr)
  • void setEpoch(uint32_t ts, uint32_t subSeconds = 0)
  • void setAlarmEpoch(uint32_t ts, Alarm_Match match = MATCH_DHHMMSS, uint32_t subSeconds = 0)

Library version management

STM32 RTC library version is based on Semantic Versioning 2.0.0 (https://semver.org/)

This will ease some dependencies:

* `STM32_RTC_VERSION_MAJOR` -> major version
* `STM32_RTC_VERSION_MINOR` -> minor version
* `STM32_RTC_VERSION_PATCH` -> patch version
* `STM32_RTC_VERSION_EXTRA` -> Extra label
 with:
  - 0: official release
  - [1-9]: release candidate
  - F[0-9]: development

* `STM32_RTC_VERSION` --> Full version number

STM32_RTC_VERSION can de used to handle some API change:

#if defined(STM32_RTC_VERSION) && (STM32_RTC_VERSION  >= 0x01010000)
  rtc.setAlarmTime(alarmHours, alarmMinutes, alarmSeconds, 123);
#else
  rtc.setAlarmTime(alarmHours, alarmMinutes, alarmSeconds);
#endif

Since STM32 Core version > 1.5.0

Reset time management

By default, if a time is set it will not be reset after a reboot.

Using begin(true) or begin(true, HOUR_24) will reset the RTC registers.

To know if a time has already been set use:

• bool isTimeSet(void)

  if (!rtc.isTimeSet()) {
    // Set the time
    rtc.setHours(hours);
    rtc.setMinutes(minutes);
    rtc.setSeconds(seconds);
  }

Refer to the Arduino RTC documentation for the other functions
http://arduino.cc/en/Reference/RTC

Source

Source files available at:
https://github.com/stm32duino/STM32RTC