Add support for subSeconds alarms (#25)

Co-authored-by: Frederic Pillon <frederic.pillon@st.com>

Author: angelnu

README.md

@@ -10,7 +10,7 @@ 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:
-```
+```C++
 /* Get the rtc object */
 STM32RTC& rtc = STM32RTC::getInstance();
 ```
@@ -58,6 +58,18 @@ _Time and date configuration (added for convenience)_
 * **`void getTime(uint8_t *hours, uint8_t *minutes, uint8_t *seconds, uint32_t *subSeconds, AM_PM *period = NULL)`**
 * **`void getDate(uint8_t *weekDay, uint8_t *day, uint8_t *month, uint8_t *year)`**
 
+### Since STM32RTC version > 1.0.3
+
+  _SubSeconds alarm management_
+
+  * **`void setAlarmSubSeconds(uint32_t subSeconds)`**
+
+  * **Updated API:**
+    * **`void setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds = 0)`**
+    * **`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)`** 
+
 ### 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.
@@ -66,7 +78,7 @@ 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)`**
-```
+```C++
   if (!rtc.isTimeSet()) {
     // Set the time
     rtc.setHours(hours);

keywords.txt

@@ -48,6 +48,7 @@ getAlarmMinutes	KEYWORD2
 getAlarmSeconds	KEYWORD2
 getAlarmSubSeconds	KEYWORD2
 
+setAlarmSubSeconds  KEYWORD2
 setAlarmSeconds	KEYWORD2
 setAlarmMinutes	KEYWORD2
 setAlarmHours	KEYWORD2

src/STM32RTC.cpp

@@ -703,6 +703,20 @@ 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)
+  * @retval none
+  */
+void STM32RTC::setAlarmSubSeconds(uint32_t subSeconds)
+{
+  if (_configured) {
+    if (subSeconds < 1000) {
+      _alarmSubSeconds = subSeconds;
+    }
+  }
+}
+
 /**
   * @brief  set RTC alarm second.
   * @param  seconds: 0-59
@@ -768,12 +782,13 @@ void STM32RTC::setAlarmHours(uint8_t hours, AM_PM period)
   * @param  seconds: 0-59
   * @retval none
   */
-void STM32RTC::setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds)
+void STM32RTC::setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds)
 {
   if (_configured) {
     setAlarmHours(hours);
     setAlarmMinutes(minutes);
     setAlarmSeconds(seconds);
+    setAlarmSubSeconds(subSeconds);
   }
 }
 
@@ -848,9 +863,10 @@ void STM32RTC::setAlarmDate(uint8_t day, uint8_t month, uint8_t year)
 
 /**
   * @brief  get epoch time
+  * @param  subSeconds: optional pointer to where to store subseconds of the epoch in ms
   * @retval epoch time in seconds
   */
-uint32_t STM32RTC::getEpoch(void)
+uint32_t STM32RTC::getEpoch(uint32_t *subSeconds)
 {
   struct tm tm;
 
@@ -870,6 +886,9 @@ uint32_t STM32RTC::getEpoch(void)
   tm.tm_hour = _hours;
   tm.tm_min = _minutes;
   tm.tm_sec = _seconds;
+  if (subSeconds != nullptr) {
+    *subSeconds = _subSeconds;
+  }
 
   return mktime(&tm);
 }
@@ -886,8 +905,10 @@ uint32_t STM32RTC::getY2kEpoch(void)
 /**
   * @brief  set RTC alarm from epoch time
   * @param  epoch time in seconds
+  * @param  Alarm_Match match enum
+  * @param  subSeconds subSeconds in ms
   */
-void STM32RTC::setAlarmEpoch(uint32_t ts, Alarm_Match match)
+void STM32RTC::setAlarmEpoch(uint32_t ts, Alarm_Match match, uint32_t subSeconds)
 {
   if (_configured) {
     if (ts < EPOCH_TIME_OFF) {
@@ -901,15 +922,17 @@ void STM32RTC::setAlarmEpoch(uint32_t ts, Alarm_Match match)
     setAlarmHours(tmp->tm_hour);
     setAlarmMinutes(tmp->tm_min);
     setAlarmSeconds(tmp->tm_sec);
+    setAlarmSubSeconds(subSeconds);
     enableAlarm(match);
   }
 }
 
 /**
   * @brief  set RTC time from epoch time
   * @param  epoch time in seconds
+  * @param  subSeconds subSeconds in ms
   */
-void STM32RTC::setEpoch(uint32_t ts)
+void STM32RTC::setEpoch(uint32_t ts, uint32_t subSeconds)
 {
   if (_configured) {
     if (ts < EPOCH_TIME_OFF) {
@@ -930,6 +953,7 @@ void STM32RTC::setEpoch(uint32_t ts)
     _hours = tmp->tm_hour;
     _minutes = tmp->tm_min;
     _seconds = tmp->tm_sec;
+    _subSeconds = subSeconds;
 
     RTC_SetDate(_year, _month, _day, _wday);
     RTC_SetTime(_hours, _minutes, _seconds, _subSeconds, (_hoursPeriod == AM) ? HOUR_AM : HOUR_PM);

src/STM32RTC.h

@@ -152,11 +152,12 @@ class STM32RTC {
     void setDate(uint8_t day, uint8_t month, uint8_t year);
     void setDate(uint8_t weekDay, uint8_t day, uint8_t month, uint8_t year);
 
+    void setAlarmSubSeconds(uint32_t subSeconds);
     void setAlarmSeconds(uint8_t seconds);
     void setAlarmMinutes(uint8_t minutes);
     void setAlarmHours(uint8_t hours);
     void setAlarmHours(uint8_t hours, AM_PM period);
-    void setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds);
+    void setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds = 0);
     void setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, AM_PM period);
 
     void setAlarmDay(uint8_t day);
@@ -168,11 +169,11 @@ class STM32RTC {
 
     /* Epoch Functions */
 
-    uint32_t getEpoch(void);
+    uint32_t getEpoch(uint32_t *subSeconds = nullptr);
     uint32_t getY2kEpoch(void);
-    void setEpoch(uint32_t ts);
+    void setEpoch(uint32_t ts, uint32_t subSeconds = 0);
     void setY2kEpoch(uint32_t ts);
-    void setAlarmEpoch(uint32_t ts, Alarm_Match match = MATCH_DHHMMSS);
+    void setAlarmEpoch(uint32_t ts, Alarm_Match match = MATCH_DHHMMSS, uint32_t subSeconds = 0);
 
     void getPrediv(int8_t *predivA, int16_t *predivS);
     void setPrediv(int8_t predivA, int16_t predivS);