Merge pull request #26 from fpistm/unified

Unified API

Author: fpistm

README.md

@@ -42,10 +42,10 @@ _SubSeconds management_
 * **`void setSubSeconds(uint32_t subSeconds)`**
 
 _Hour format (AM or PM)_
-* **`uint8_t getHours(AM_PM *period)`**
-* **`void setHours(uint8_t hours, AM_PM period)`**
-* **`void setTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds, AM_PM period)`**
-* **`void setAlarmHours(uint8_t hours, AM_PM period)`**
+* **`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)`**
 
@@ -55,23 +55,50 @@ _Week day configuration_
 * **`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 = NULL)`**
+* **`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 > 1.0.3
+### Since STM32RTC version higher than 1.0.3
 
-  _SubSeconds alarm management_
+_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)`**
+    * **`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:
+```C++
+#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.

library.properties

@@ -1,5 +1,5 @@
 name=STM32duino RTC
-version=1.0.3
+version=1.1.0
 author=STMicroelectronics, Wi6Labs
 maintainer=stm32duino
 sentence=Allows to use the RTC functionalities of STM32 based boards.

src/STM32RTC.cpp

@@ -71,6 +71,7 @@ void STM32RTC::begin(bool resetTime, Hour_Format format)
 void STM32RTC::begin(Hour_Format format)
 {
   if (_configured == false) {
+    _format = format;
     RTC_init((format == HOUR_12) ? HOUR_FORMAT_12 : HOUR_FORMAT_24,
              (_clockSource == LSE_CLOCK) ? ::LSE_CLOCK :
              (_clockSource == HSE_CLOCK) ? ::HSE_CLOCK : ::LSI_CLOCK
@@ -143,7 +144,7 @@ void STM32RTC::setClockSource(Source_Clock source)
   */
 void STM32RTC::getPrediv(int8_t *predivA, int16_t *predivS)
 {
-  if ((predivA != NULL) && (predivS != NULL)) {
+  if ((predivA != nullptr) && (predivS != nullptr)) {
     RTC_getPrediv(predivA, predivS);
   }
 }
@@ -263,14 +264,14 @@ uint8_t STM32RTC::getMinutes(void)
 
 /**
   * @brief  get RTC hours.
-  * @param  format: optional (default: NULL)
+  * @param  format: optional (default: nullptr)
   *         pointer to the current hour period set in the RTC: AM or PM
   * @retval return the current hours from the RTC.
   */
 uint8_t STM32RTC::getHours(AM_PM *period)
 {
   syncTime();
-  if (period != NULL) {
+  if (period != nullptr) {
     *period = _hoursPeriod;
   }
   return _hours;
@@ -282,26 +283,26 @@ uint8_t STM32RTC::getHours(AM_PM *period)
   * @param  minutes: pointer to the current minutes
   * @param  seconds: pointer to the current seconds
   * @param  subSeconds: pointer to the current subSeconds
-  * @param  period: optional (default: NULL)
+  * @param  period: optional (default: nullptr)
   *         pointer to the current hour period set in the RTC: AM or PM
   * @retval none
   */
 void STM32RTC::getTime(uint8_t *hours, uint8_t *minutes, uint8_t *seconds, uint32_t *subSeconds, AM_PM *period)
 {
   syncTime();
-  if (hours != NULL) {
+  if (hours != nullptr) {
     *hours = _hours;
   }
-  if (minutes != NULL) {
+  if (minutes != nullptr) {
     *minutes = _minutes;
   }
-  if (seconds != NULL) {
+  if (seconds != nullptr) {
     *seconds = _seconds;
   }
-  if (subSeconds != NULL) {
+  if (subSeconds != nullptr) {
     *subSeconds = _subSeconds;
   }
-  if (period != NULL) {
+  if (period != nullptr) {
     *period = _hoursPeriod;
   }
 }
@@ -357,16 +358,16 @@ uint8_t STM32RTC::getYear(void)
 void STM32RTC::getDate(uint8_t *weekDay, uint8_t *day, uint8_t *month, uint8_t *year)
 {
   syncDate();
-  if (weekDay != NULL) {
+  if (weekDay != nullptr) {
     *weekDay = _wday;
   }
-  if (day != NULL) {
+  if (day != nullptr) {
     *day = _day;
   }
-  if (month != NULL) {
+  if (month != nullptr) {
     *month = _month;
   }
-  if (year != NULL) {
+  if (year != nullptr) {
     *year = _year;
   }
 }
@@ -403,14 +404,14 @@ uint8_t STM32RTC::getAlarmMinutes(void)
 
 /**
   * @brief  get RTC alarm hour.
-  * @param  format: optional (default: NULL)
+  * @param  format: optional (default: nullptr)
   *         pointer to the current hour format set in the RTC: AM or PM
   * @retval return the current alarm hour.
   */
 uint8_t STM32RTC::getAlarmHours(AM_PM *period)
 {
   syncAlarmTime();
-  if (period != NULL) {
+  if (period != nullptr) {
     *period = _alarmPeriod;
   }
   return _alarmHours;
@@ -503,23 +504,7 @@ void STM32RTC::setMinutes(uint8_t minutes)
 /**
   * @brief  set RTC hours.
   * @param  hours: 0-23
-  * @retval none
-  */
-void STM32RTC::setHours(uint8_t hours)
-{
-  if (_configured) {
-    syncTime();
-    if (hours < 24) {
-      _hours = hours;
-    }
-    RTC_SetTime(_hours, _minutes, _seconds, _subSeconds, (_hoursPeriod == AM) ? HOUR_AM : HOUR_PM);
-  }
-}
-
-/**
-  * @brief  set RTC hours.
-  * @param  hours: 0-23 or 0-12
-  * @param  hours format: AM or PM
+  * @param  period: hour format AM or PM (optional)
   * @retval none
   */
 void STM32RTC::setHours(uint8_t hours, AM_PM period)
@@ -529,41 +514,20 @@ void STM32RTC::setHours(uint8_t hours, AM_PM period)
     if (hours < 24) {
       _hours = hours;
     }
-    _hoursPeriod = period;
-    RTC_SetTime(_hours, _minutes, _seconds, _subSeconds, (_hoursPeriod == AM) ? HOUR_AM : HOUR_PM);
-  }
-}
-
-/**
-  * @brief  set RTC time.
-  * @param  hours: 0-23
-  * @param  minutes: 0-59
-  * @param  seconds: 0-59
-  * @retval none
-  */
-void STM32RTC::setTime(uint8_t hours, uint8_t minutes, uint8_t seconds)
-{
-  if (_configured) {
-    syncTime();
-    if (seconds < 60) {
-      _seconds = seconds;
-    }
-    if (minutes < 60) {
-      _minutes = minutes;
-    }
-    if (hours < 24) {
-      _hours = hours;
+    if (_format == HOUR_12) {
+      _hoursPeriod = period;
     }
     RTC_SetTime(_hours, _minutes, _seconds, _subSeconds, (_hoursPeriod == AM) ? HOUR_AM : HOUR_PM);
   }
 }
 
 /**
   * @brief  set RTC time.
-  * @param  hours: 0-23 or 0-12
+  * @param  hours: 0-23
   * @param  minutes: 0-59
   * @param  seconds: 0-59
-  * @param  hour format: AM or PM
+  * @param  subSeconds: 0-999 (optional)
+  * @param  period: hour format AM or PM (optional)
   * @retval none
   */
 void STM32RTC::setTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds, AM_PM period)
@@ -582,7 +546,9 @@ void STM32RTC::setTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t
     if (hours < 24) {
       _hours = hours;
     }
-    _hoursPeriod = period;
+    if (_format == HOUR_12) {
+      _hoursPeriod = period;
+    }
     RTC_SetTime(_hours, _minutes, _seconds, _subSeconds, (_hoursPeriod == AM) ? HOUR_AM : HOUR_PM);
   }
 }
@@ -745,24 +711,10 @@ void STM32RTC::setAlarmMinutes(uint8_t minutes)
   }
 }
 
-/**
-  * @brief  set RTC alarm hour.
-  * @param  hour: 0-23
-  * @retval none
-  */
-void STM32RTC::setAlarmHours(uint8_t hours)
-{
-  if (_configured) {
-    if (hours < 24) {
-      _alarmHours = hours;
-    }
-  }
-}
-
 /**
   * @brief  set RTC alarm hour.
   * @param  hour: 0-23 or 0-12
-  * @param  hour format: AM or PM
+  * @param  period: hour format AM or PM (optional)
   * @retval none
   */
 void STM32RTC::setAlarmHours(uint8_t hours, AM_PM period)
@@ -771,24 +723,9 @@ void STM32RTC::setAlarmHours(uint8_t hours, AM_PM period)
     if (hours < 24) {
       _alarmHours = hours;
     }
-    _alarmPeriod = period;
-  }
-}
-
-/**
-  * @brief  set RTC alarm time.
-  * @param  hours: 0-23
-  * @param  minutes: 0-59
-  * @param  seconds: 0-59
-  * @retval none
-  */
-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);
+    if (_format == HOUR_12) {
+      _alarmPeriod = period;
+    }
   }
 }
 
@@ -797,15 +734,17 @@ void STM32RTC::setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uin
   * @param  hours: 0-23
   * @param  minutes: 0-59
   * @param  seconds: 0-59
-  * @param  hour format: AM or PM
+  * @param  subSeconds: 0-999 (optional)
+  * @param  period: hour format AM or PM (optional)
   * @retval none
   */
-void STM32RTC::setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, AM_PM period)
+void STM32RTC::setAlarmTime(uint8_t hours, uint8_t minutes, uint8_t seconds, uint32_t subSeconds, AM_PM period)
 {
   if (_configured) {
     setAlarmHours(hours, period);
     setAlarmMinutes(minutes);
     setAlarmSeconds(seconds);
+    setAlarmSubSeconds(subSeconds);
   }
 }