feat: add new API to setAlarmTime with subsecond

Add new API to set alarm Time with subseconds which is a nb of
milliseconds. Similar to setAlarmSubSeconds.

Signed-off-by: Francois Ramu <francois.ramu@st.com>

Author: FRASTM

README.md

@@ -158,6 +158,24 @@ _Get the RTC handle_
 
 * **`RTC_HandleTypeDef *RTC_GetHandle(void)`**
 
+_binary and mix modes_
+
+Some STM32 RTC have a binary mode with 32-bit free-running counter
+in addition to their BCD mode for calendar (for example stm32wl55).
+Combined with BCD this is the MIX mode. Only using the binary counter is the BIN mode.
+Three RTC functional modes are available:
+  - `STM32RTC::MODE_BCD`
+  - `STM32RTC::MODE_MIX`
+  - `STM32RTC::MODE_BIN`
+
+* **`Binary_Mode getBinaryMode(void);`**
+* **`void setBinaryMode(Binary_Mode mode);`**
+
+
+Any API using the Subsecond parameter is expressed in milliseconds
+whatever the RTC input clock. This parameter is [0..999] in MIX or BCD mode
+and [0..0xFFFFFFFF] in BIN mode. In this configuration, time and date registers
+are not used by the RTC.
 
 Refer to the Arduino RTC documentation for the other functions
 http://arduino.cc/en/Reference/RTC

src/STM32RTC.cpp

@@ -154,7 +154,13 @@ STM32RTC::Binary_Mode STM32RTC::getBinaryMode(void)
   */
 void STM32RTC::setBinaryMode(Binary_Mode mode)
 {
+#if defined(RTC_BINARY_NONE)
   _mode = mode;
+#else
+#warning "only BCD mode is supported"
+  UNUSED(mode);
+  _mode = MODE_BCD;
+#endif /* RTC_BINARY_NONE */
 }
 
 /**
@@ -340,7 +346,7 @@ void STM32RTC::standbyMode(void)
 
 /**
   * @brief  get RTC subseconds.
-  * @retval return the current subseconds from the RTC.
+  * @retval return the current milliseconds from the RTC.
   */
 uint32_t STM32RTC::getSubSeconds(void)
 {
@@ -388,7 +394,7 @@ uint8_t STM32RTC::getHours(AM_PM *period)
   * @param  hours: pointer to the current hours
   * @param  minutes: pointer to the current minutes
   * @param  seconds: pointer to the current seconds
-  * @param  subSeconds: pointer to the current subSeconds
+  * @param  subSeconds: pointer to the current subSeconds (in milliseconds)
   * @param  period: optional (default: nullptr)
   *         pointer to the current hour period set in the RTC: AM or PM
   * @retval none
@@ -835,20 +841,30 @@ void STM32RTC::setDate(uint8_t weekDay, uint8_t day, uint8_t month, uint8_t year
 
 /**
   * @brief  set RTC alarm subseconds.
-  * @param  subseconds: 0-999 (in ms)
+  * @param  subseconds: 0-999 (in ms) or 32bit nb of milliseconds in BIN mode
   * @param name: optional (default: ALARM_A)
   *        ALARM_A or ALARM_B if exists
   * @retval none
   */
 void STM32RTC::setAlarmSubSeconds(uint32_t subSeconds, Alarm name)
 {
-  if (subSeconds < 1000) {
+#ifndef RTC_ALARM_B
+  UNUSED(name);
+#endif
+  if (_mode == MODE_BIN) {
+#ifdef RTC_ALARM_B
+    if (name == ALARM_B) {
+      _alarmBSubSeconds = subSeconds;
+    } else
+#endif
+    {
+      _alarmSubSeconds = subSeconds;
+    }
+  } else if (subSeconds < 1000) {
 #ifdef RTC_ALARM_B
     if (name == ALARM_B) {
       _alarmBSubSeconds = subSeconds;
     } else
-#else
-    UNUSED(name);
 #endif
     {
       _alarmSubSeconds = subSeconds;
@@ -931,7 +947,7 @@ void STM32RTC::setAlarmHours(uint8_t hours, AM_PM period, Alarm name)
       if (_format == HOUR_12) {
         _alarmBPeriod = period;
       }
-    }
+    } else
 #else
     UNUSED(name);
 #endif
@@ -944,6 +960,18 @@ void STM32RTC::setAlarmHours(uint8_t hours, AM_PM period, Alarm name)
   }
 }
 
+
+/**
+  * @brief  set RTC alarm time.
+  * @param  subSeconds: 0-999 ms or 32bit nb of milliseconds in BIN mode
+  * @param  name: ALARM_A or ALARM_B if exists
+  * @retval none
+  */
+void STM32RTC::setAlarmTime(uint32_t subSeconds, Alarm name)
+{
+  setAlarmTime(0, 0, 0, subSeconds, AM, name);
+}
+
 /**
   * @brief  set RTC alarm time.
   * @param  hours: 0-23
@@ -962,7 +990,7 @@ void STM32RTC::setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, Ala
   * @param  hours: 0-23
   * @param  minutes: 0-59
   * @param  seconds: 0-59
-  * @param  subSeconds: 0-999
+  * @param  subSeconds: 0-999 ms or 32bit nb of milliseconds in BIN mode
   * @param  name: ALARM_A or ALARM_B if exists
   * @retval none
   */
@@ -973,10 +1001,10 @@ void STM32RTC::setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uin
 
 /**
   * @brief  set RTC alarm time.
-  * @param  hours: 0-23
-  * @param  minutes: 0-59
-  * @param  seconds: 0-59
-  * @param  subSeconds: 0-999 (optional)
+  * @param  hours: 0-23 (not used in BIN mode)
+  * @param  minutes: 0-59 (not used in BIN mode)
+  * @param  seconds: 0-59 (not used in BIN mode)
+  * @param  subSeconds: 0-999 ms (optional) or 32bit nb of milliseconds in BIN mode
   * @param  period: hour format AM or PM (optional)
   * @param  name: optional (default: ALARM_A)
   *         ALARM_A or ALARM_B if exists

src/STM32RTC.h

@@ -86,7 +86,7 @@ class STM32RTC {
     };
 
     enum Binary_Mode : uint8_t {
-      MODE_BCD = MODE_BINARY_NONE, /* not used */
+      MODE_BCD = MODE_BINARY_NONE,
       MODE_BIN = MODE_BINARY_ONLY,
       MODE_MIX = MODE_BINARY_MIX
     };
@@ -208,6 +208,7 @@ class STM32RTC {
     void setAlarmMinutes(uint8_t minutes, Alarm name = ALARM_A);
     void setAlarmHours(uint8_t hours, Alarm name);
     void setAlarmHours(uint8_t hours, AM_PM period = AM, Alarm name = ALARM_A);
+    void setAlarmTime(uint32_t subSeconds, Alarm name = ALARM_A);
     void setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, Alarm name);
     void setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds, Alarm name);
     void setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds = 0, AM_PM period = AM, Alarm name = ALARM_A);