From b7fa51bee0c79d56959fa1d38b8c389f2d092a3d Mon Sep 17 00:00:00 2001
From: Frederic Pillon <frederic.pillon@st.com>
Date: Fri, 8 Dec 2023 16:14:51 +0100
Subject: [PATCH] chore: enhance shutdown mode

Signed-off-by: Frederic Pillon <frederic.pillon@st.com>
---
 README.md             | 14 ++++++++------
 src/STM32LowPower.cpp |  4 +++-
 src/low_power.c       | 12 +++++++-----
 src/low_power.h       |  2 +-
 4 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 314b3a5..5139f54 100644
--- a/README.md
+++ b/README.md
@@ -21,7 +21,8 @@ Arduino library to support STM32 Low Power.
 * **`void shutdown(uint32_t ms)`**: enter in shutdown mode
 **param** ms (optional): number of milliseconds before to exit the mode. The RTC is used in alarm mode to wakeup the board in ms milliseconds.
 
-**Note: With [STM32RTC](https://github.com/stm32duino/STM32RTC) version lower than 1.1.0, the minimum number of milliseconds is 1000 ms.**
+> [!Note]
+> With [STM32RTC](https://github.com/stm32duino/STM32RTC) version lower than 1.1.0, the minimum number of milliseconds is 1000 ms.**
 
 * **`void attachInterruptWakeup(uint32_t pin, voidFuncPtrVoid callback, uint32_t mode, LP_Mode LowPowerMode)`**: Enable GPIO pin in interrupt mode. If the pin is a wakeup pin, it is configured as wakeup source (see board documentation).
 **param** pin: pin number  
@@ -49,11 +50,12 @@ enable an I2C peripheral in low power mode. See board documentation for low powe
 
 `attachInterruptWakeup()` or `enableWakeupFrom()` functions should be called before `idle()`, `sleep()`, `deepSleep()` or `shutdown()` functions.  
 
-HardwareSerial used as Wakeup source will configure it to use HSI clock source even if another peripheral clock is configured.
-
-RTC used as Wakeup source requires to have LSE or LSI as clock source. If one of them is used nothing is changed else it will configure it to use LSI clock source. One exception exists when `SHUTDOWN_MODE` is requested and `PWR_CR1_LPMS` is defined, in that case LSE is used.
-
-The board will restart when exit shutdown mode.
+> [!Important]
+> * HardwareSerial used as Wakeup source will configure it to use HSI clock source even if another peripheral clock is configured.
+>
+> * RTC used as Wakeup source requires to have LSE or LSI as clock source. If one of them is used nothing is changed else it will configure it to use LSI clock source. One exception exists when `SHUTDOWN_MODE` is requested and `PWR_CR1_LPMS` is defined, in that case LSE is required. So, if the board does not have LSE, it will fail.
+>
+> * The board will restart when exit shutdown mode.
 
 ## Hardware state
 
diff --git a/src/STM32LowPower.cpp b/src/STM32LowPower.cpp
index 30c34bf..00a85d8 100644
--- a/src/STM32LowPower.cpp
+++ b/src/STM32LowPower.cpp
@@ -115,7 +115,9 @@ void STM32LowPower::shutdown(uint32_t ms)
   if ((ms != 0) || _rtc_wakeup) {
     programRtcWakeUp(ms, SHUTDOWN_MODE);
   }
-  LowPower_shutdown();
+  /* Get the rtc object to know if it is configured */
+  STM32RTC &rtc = STM32RTC::getInstance();
+  LowPower_shutdown(rtc.isConfigured());
 }
 
 /**
diff --git a/src/low_power.c b/src/low_power.c
index 8d119d4..e7df307 100644
--- a/src/low_power.c
+++ b/src/low_power.c
@@ -567,10 +567,10 @@ void LowPower_standby()
 /**
   * @brief  Enable the shutdown mode.The board reset when leaves this mode.
   *         If shutdown mode not available, use standby mode instead.
-  * @param  None
+  * @param  boolean true if RTC is configured, in that case LSE is required
   * @retval None
   */
-void LowPower_shutdown()
+void LowPower_shutdown(bool isRTC)
 {
   __disable_irq();
 
@@ -593,11 +593,13 @@ void LowPower_shutdown()
            will make system enter in Stop2 mode. */
   LL_C2_PWR_SetPowerMode(LL_PWR_MODE_SHUTDOWN);
 #endif
-#if defined(PWR_LOWPOWERMODE_SHUTDOWN) || defined(PWR_CR1_LPMS_SHUTDOWN) || defined(LL_PWR_SHUTDOWN_MODE)
-  /* LSE must be on to use shutdown mode */
-  if (__HAL_RCC_GET_FLAG(RCC_FLAG_LSERDY) == SET) {
+#if defined(PWR_CR1_LPMS)
+  /* LSE must be on to use shutdown mode within RTC else fallback to standby */
+  if ((!isRTC) || (__HAL_RCC_GET_FLAG(RCC_FLAG_LSERDY) == SET)) {
     HAL_PWREx_EnterSHUTDOWNMode();
   } else
+#else
+  UNUSED(isRTC);
 #endif
   {
     LowPower_standby();
diff --git a/src/low_power.h b/src/low_power.h
index 3318c59..7aede40 100644
--- a/src/low_power.h
+++ b/src/low_power.h
@@ -58,7 +58,7 @@ void LowPower_EnableWakeUpUart(serial_t *serial, void (*FuncPtr)(void));
 void LowPower_sleep(uint32_t regulator);
 void LowPower_stop(serial_t *obj);
 void LowPower_standby();
-void LowPower_shutdown();
+void LowPower_shutdown(bool isRTC);
 /* Weaked function */
 void SystemClock_ConfigFromStop(void);
 #ifdef __cplusplus