Merge pull request #57 from FRASTM/seconds_int

implement a One-Second interrupt on stm32 MCUs

Author: fpistm

README.md

@@ -100,6 +100,20 @@ _Library version management_
 #endif
 ```
 
+### Since STM32RTC version higher than 1.1.1
+
+_One-Second interrupt_
+
+  STM32 RTC includes a one-second interrupt for generating a periodic interrupt signal.
+  - This feature is native on the stm32F1xx and mapped on the existing WakeUp interrupt on other stm32 mcus. 
+  - It is not available on some stm32F0 devices.
+
+  * **new API:**
+    * **`void attachSecondsInterrupt(voidFuncPtr callback)`**
+    * **`void detachSecondsInterrupt(void)`**
+
+
+
 ### Since STM32 Core version > 1.5.0
 _Reset time management_
 
@@ -118,10 +132,10 @@ To know if a time has already been set use:
   }
 ```
 
-Refer to the Arduino RTC documentation for the other functions  
+Refer to the Arduino RTC documentation for the other functions
 http://arduino.cc/en/Reference/RTC
 
 ## Source
 
-Source files available at:  
+Source files available at:
 https://github.com/stm32duino/STM32RTC

examples/RTC_Seconds/RTC_Seconds.ino

@@ -0,0 +1,113 @@
+/*
+  RTC_Seconds
+
+  This sketch allows to test STM32RTC Seconds IRQ.
+
+  Creation 25 nov 2021
+  by FRASTM for STMicroelectronics
+
+  This example code is in the public domain.
+
+  Note that this sketch is valid for STM32F1xx or stm32 MCU with WakeUp interrupt
+       (WUTE flag present in the RTC CR register)
+
+  https://github.com/stm32duino/STM32RTC
+
+*/
+
+#include <STM32RTC.h>
+
+#ifndef ONESECOND_IRQn
+#error "RTC has no feature for One-Second interrupt"
+#endif
+
+/* use led to display seconds */
+#if defined(LED_BUILTIN)
+#define pin  LED_BUILTIN
+#endif
+
+/* Get the rtc object */
+STM32RTC& rtc = STM32RTC::getInstance();
+
+/* Change these values to set the current initial time
+
+   format: date: "Dec 31 2017" and time: "23:59:56"
+   by default use built date and time
+*/
+/* Change these values to set the current initial time */
+const byte seconds = 0;
+const byte minutes = 5;
+const byte hours = 11;
+
+/* Change these values to set the current initial date */
+/* Monday 25 Nov. 2021 */
+const byte weekDay = 4;
+const byte day = 25;
+const byte month = 11;
+const byte year = 21;
+
+bool toggling = false; // changed each second by the CallBack function
+
+static STM32RTC::Hour_Format hourFormat = STM32RTC::HOUR_24;
+static STM32RTC::AM_PM period = STM32RTC::AM;
+
+void setup()
+{
+  Serial.begin(115200);
+  while (!Serial) {}
+
+#if defined(LED_BUILTIN)
+  // configure pin in output mode
+  pinMode(pin, OUTPUT);
+  digitalWrite(pin, HIGH);
+#endif /* LED_BUILTIN */
+
+  Serial.print("RTC Init ");
+
+  // Select RTC clock source: LSI_CLOCK, LSE_CLOCK or HSE_CLOCK.
+  // By default the LSI is selected as source. Use LSE for better accuracy if available
+  // rtc.setClockSource(STM32RTC::LSE_CLOCK);
+
+  // initialize RTC 24H format
+  rtc.begin(hourFormat);
+
+  // Set the time
+  rtc.setHours(hours, period);
+  rtc.setMinutes(minutes);
+  rtc.setSeconds(seconds);
+
+  // Set the date
+  rtc.setWeekDay(weekDay);
+  rtc.setDay(day);
+  rtc.setMonth(month);
+  rtc.setYear(year);
+
+  Serial.println("with seconds Alarm");
+  rtc.attachSecondsInterrupt(rtc_SecondsCB);
+}
+
+void loop()
+{
+  uint8_t sec = 0;
+  uint8_t mn = 0;
+  uint8_t hrs = 0;
+  uint32_t subs = 0;
+  rtc.getTime(&hrs, &mn, &sec, &subs);
+
+  if (toggling) {
+   Serial.printf("%02d:%02d:%02d\n", hrs, mn, sec);
+  } else {
+   Serial.printf("%02d %02d %02d\n", hrs, mn, sec);
+  }
+#if defined(LED_BUILTIN)
+  digitalWrite(pin, toggling);
+#endif /* LED_BUILTIN */
+  delay(1000);
+}
+
+/* callback function on each second interrupt */
+void rtc_SecondsCB(void *data)
+{
+  UNUSED(data);
+  toggling = !toggling;
+}

src/STM32RTC.cpp

@@ -249,6 +249,27 @@ void STM32RTC::detachInterrupt(void)
   detachAlarmCallback();
 }
 
+#ifdef ONESECOND_IRQn
+/**
+  * @brief attach a callback to the RTC Seconds interrupt.
+  * @param callback: pointer to the callback
+  * @retval None
+  */
+void STM32RTC::attachSecondsInterrupt(voidFuncPtr callback)
+{
+  attachSecondsIrqCallback(callback);
+}
+
+/**
+  * @brief detach the RTC Seconds callback.
+  * @retval None
+  */
+void STM32RTC::detachSecondsInterrupt(void)
+{
+  detachSecondsIrqCallback();
+}
+
+#endif /* ONESECOND_IRQn */
 // Kept for compatibility. Use STM32LowPower library.
 void STM32RTC::standbyMode(void)
 {

src/STM32RTC.h

@@ -125,6 +125,12 @@ class STM32RTC {
     void attachInterrupt(voidFuncPtr callback, void *data = nullptr);
     void detachInterrupt(void);
 
+#ifdef ONESECOND_IRQn
+    // Other mcu than stm32F1 will use the WakeUp feature to interrupt each second.
+    void attachSecondsInterrupt(voidFuncPtr callback);
+    void detachSecondsInterrupt(void);
+
+#endif /* ONESECOND_IRQn */
     // Kept for compatibility: use STM32LowPower library.
     void standbyMode();
 

src/rtc.c

@@ -58,6 +58,7 @@ extern "C" {
 static RTC_HandleTypeDef RtcHandle = {0};
 static voidCallbackPtr RTCUserCallback = NULL;
 static void *callbackUserData = NULL;
+static voidCallbackPtr RTCSecondsIrqCallback = NULL;
 
 static sourceClock_t clkSrc = LSI_CLOCK;
 static uint8_t HSEDiv = 0;
@@ -388,6 +389,7 @@ void RTC_DeInit(void)
   HAL_RTC_DeInit(&RtcHandle);
   RTCUserCallback = NULL;
   callbackUserData = NULL;
+  RTCSecondsIrqCallback = NULL;
 }
 
 /**
@@ -731,6 +733,107 @@ void RTC_Alarm_IRQHandler(void)
   HAL_RTC_AlarmIRQHandler(&RtcHandle);
 }
 
+#ifdef ONESECOND_IRQn
+/**
+  * @brief Attach Seconds interrupt callback.
+  * @note  stm32F1 has a second interrupt capability
+  *        other MCUs map this on their WakeUp feature
+  * @param func: pointer to the callback
+  * @retval None
+  */
+void attachSecondsIrqCallback(voidCallbackPtr func)
+{
+#if defined(STM32F1xx)
+  /* callback called on Seconds interrupt */
+  RTCSecondsIrqCallback = func;
+
+  HAL_RTCEx_SetSecond_IT(&RtcHandle);
+  __HAL_RTC_SECOND_CLEAR_FLAG(&RtcHandle, RTC_FLAG_SEC);
+#else
+  /* callback called on wakeUp interrupt for One-Second purpose*/
+  RTCSecondsIrqCallback = func;
+
+  /* for MCUs using the wakeup feature : irq each second */
+#if defined(RTC_WUTR_WUTOCLR)
+  HAL_RTCEx_SetWakeUpTimer_IT(&RtcHandle, 0, RTC_WAKEUPCLOCK_CK_SPRE_16BITS, 0);
+#else
+  HAL_RTCEx_SetWakeUpTimer_IT(&RtcHandle, 0, RTC_WAKEUPCLOCK_CK_SPRE_16BITS);
+#endif /* RTC_WUTR_WUTOCLR */
+
+#endif /* STM32F1xx */
+  /* enable the IRQ that will trig the one-second interrupt */
+  HAL_NVIC_EnableIRQ(ONESECOND_IRQn);
+}
+
+/**
+  * @brief Detach Seconds interrupt callback.
+  * @param None
+  * @retval None
+  */
+void detachSecondsIrqCallback(void)
+{
+#if defined(STM32F1xx)
+  HAL_RTCEx_DeactivateSecond(&RtcHandle);
+#else
+  /* for MCUs using the wakeup feature : do not deactivate the WakeUp
+     as it might be used for another reason than the One-Second purpose */
+  // HAL_RTCEx_DeactivateWakeUpTimer(&RtcHandle);
+#endif /* STM32F1xx */
+  RTCSecondsIrqCallback = NULL;
+}
+
+#if defined(STM32F1xx)
+/**
+  * @brief  Seconds interrupt callback.
+  * @param  hrtc RTC handle
+  * @retval None
+  */
+void HAL_RTCEx_RTCEventCallback(RTC_HandleTypeDef *hrtc)
+{
+  UNUSED(hrtc);
+
+  if (RTCSecondsIrqCallback != NULL) {
+    RTCSecondsIrqCallback(NULL);
+  }
+}
+
+/**
+  * @brief  This function handles RTC Seconds interrupt request.
+  * @param  None
+  * @retval None
+  */
+void RTC_IRQHandler(void)
+{
+  HAL_RTCEx_RTCIRQHandler(&RtcHandle);
+}
+
+#else
+/**
+  * @brief  WakeUp event mapping the Seconds interrupt callback.
+  * @param  hrtc RTC handle
+  * @retval None
+  */
+void HAL_RTCEx_WakeUpTimerEventCallback(RTC_HandleTypeDef *hrtc)
+{
+  UNUSED(hrtc);
+
+  if (RTCSecondsIrqCallback != NULL) {
+    RTCSecondsIrqCallback(NULL);
+  }
+}
+
+/**
+  * @brief  This function handles RTC Seconds through wakeup interrupt request.
+  * @param  None
+  * @retval None
+  */
+void RTC_WKUP_IRQHandler(void)
+{
+  HAL_RTCEx_WakeUpTimerIRQHandler(&RtcHandle);
+}
+#endif /* STM32F1xx */
+#endif /* ONESECOND_IRQn */
+
 #ifdef __cplusplus
 }
 #endif

src/rtc.h

@@ -109,6 +109,28 @@ typedef void(*voidCallbackPtr)(void *);
 #define RTC_Alarm_IRQHandler RTC_TAMP_IRQHandler
 #endif
 
+/* mapping the IRQn for the one-second interrupt depending on the soc */
+#if defined(STM32F1xx) || (defined(STM32F0xx) && defined(RTC_CR_WUTE)) || \
+    defined(STM32L0xx) || defined(STM32L5xx) || defined(STM32U5xx) || \
+    defined(STM32WLE4xx)
+// specific WakeUp interrupt
+#define ONESECOND_IRQn RTC_IRQn
+#elif defined(STM32MP1xx)
+// global RTC interrupt
+#define ONESECOND_IRQn RTC_WKUP_ALARM_IRQn
+#elif defined(STM32G0xx)
+// global RTC/TAMP interrupt
+#define ONESECOND_IRQn RTC_TAMP_IRQn
+#elif defined(STM32WL54xx)|| defined(STM32WL55xx)
+// global RTC/LSS interrupt
+#define ONESECOND_IRQn RTC_LSECSS_IRQn
+#elif defined(RTC_CR_WUTE)
+// specific WakeUp interrupt (including M4 cpu of the STM32WLE5xx)
+#define ONESECOND_IRQn RTC_WKUP_IRQn
+#else
+// no One-Second IRQ available for the series
+#endif /* STM32F1xx || etc */
+
 #if defined(STM32F1xx) && !defined(IS_RTC_WEEKDAY)
 /* Compensate missing HAL definition */
 #define IS_RTC_WEEKDAY(WEEKDAY) (((WEEKDAY) == RTC_WEEKDAY_MONDAY)    || \
@@ -161,6 +183,10 @@ void RTC_StopAlarm(void);
 void RTC_GetAlarm(uint8_t *day, uint8_t *hours, uint8_t *minutes, uint8_t *seconds, uint32_t *subSeconds, hourAM_PM_t *period, uint8_t *mask);
 void attachAlarmCallback(voidCallbackPtr func, void *data);
 void detachAlarmCallback(void);
+#ifdef ONESECOND_IRQn
+void attachSecondsIrqCallback(voidCallbackPtr func);
+void detachSecondsIrqCallback(void);
+#endif /* ONESECOND_IRQn */
 
 #ifdef __cplusplus
 }