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);
  }
 }