Power: make timerSleep fail-closed and report when the device stays awake

timerSleep powered the device off even when the wake-up alarm had not been
armed, and returned void so the caller could not tell.

- The three overloads return bool: if the function returns, sleep was not
  entered. Reasons: invalid arguments, an RTC without the needed feature
  (PowerHub has no timer, use the date/time overloads), a failed cleanup of
  the existing IRQ sources, a failed RTC setup, a failed wake-source
  registration, the PC build.
- Everything is validated (including the driver's own limits through
  canSetAlarm/hasTimerIRQ) before the existing IRQ sources are touched, so
  a bad request changes nothing. A request whose alarm fields are all
  wildcards is refused: the alarm API treats that as "clear", which must
  not be mistaken for an armed wake-up.
- The old timer and alarm are disabled and cleared (both attempted, then
  combined) before the new one is armed; the ESP timer wake-up is set to
  the period the RTC actually applied so both sources share the deadline,
  and an ESP timer left by an earlier light sleep is dropped before an
  RTC-only sleep ("not registered" counts as clean). Without an RTC the
  ESP timer wake-up is used as before and its registration must succeed.
- _powerOff / _timerSleep report a cancelled sleep: a failed EXT0 / GPIO /
  EXT1 wake registration, a wake pin that cannot be released, a PowerHub
  that does not accept the power-off request, a light sleep that cannot be
  entered. On cancellation the display is woken up again, a GPIO wake-up
  armed here is released (only the RTC pin, the GPIO wake source may carry
  the application's pins), and the caller releases the RTC IRQ and the ESP
  timer it armed. Without an RTC the RTC IRQ pin is not registered.
- Docs: timerSleep(seconds) owns the ESP timer wake source; the RTC alarm
  wakes only boards where its IRQ is wired to a wake route (an external RTC
  unit does not wake the board).

Author: ainyan03

src/utility/Power_Class.hpp

@@ -246,20 +246,43 @@ namespace m5
 
     /// sleep and timer boot. The boot condition can be specified by the argument.
     /// @param seconds Number of seconds to boot.
-    void timerSleep(int seconds);
+    /// @return If this function returns, sleep was not entered and the result is false. Reasons include
+    ///         invalid arguments, existing RTC IRQ cleanup failure, RTC setup failure, ESP timer wakeup
+    ///         registration failure without an RTC, wake source registration failure, and PC builds.
+    ///         Does not return once sleep is entered. Without an RTC the ESP32 timer wakeup is used.
+    /// @note This function owns the ESP timer wake source: it is set for this sleep and disabled
+    ///       again when the sleep is cancelled, a previous setting is not restored.
+    /// @note PowerHub has no periodic RTC timer; use a date/time overload on those boards.
+    /// @note When the ESP timer wakeup cannot be registered the RTC timer is used alone; that
+    ///       wakes only boards where the RTC IRQ is wired to a wake route (not an external RTC unit).
+    bool timerSleep(int seconds);
 
     /// sleep and timer boot. The boot condition can be specified by the argument.
     /// @param time Time to boot. (only minutes and hours can be specified. Ignore seconds)
+    /// @return If this function returns, sleep was not entered and the result is false. Reasons include
+    ///         invalid arguments, existing RTC IRQ cleanup failure, RTC setup failure,
+    ///         wake source registration failure, and PC builds.
+    ///         Does not return once sleep is entered.
+    /// @note The RTC alarm wakes only boards where its IRQ is wired to a wake route;
+    ///       an alarm from an external RTC unit does not wake the board.
+    /// @note An ESP timer wake-up left by an earlier sleep is disabled and not restored.
     /// @attention CoreInk and M5Paper can't alarm boot because it can't be turned off while connected to USB.
     /// @attention CoreInk と M5Paper は USB接続中はRTCタイマー起動が出来ない。;
-    void timerSleep(const rtc_time_t& time);
+    bool timerSleep(const rtc_time_t& time);
 
     /// sleep and timer boot. The boot condition can be specified by the argument.
     /// @param date Date to boot. (only date and weekDay can be specified. Ignore year and month)
     /// @param time Time to boot. (only minutes and hours can be specified. Ignore seconds)
+    /// @return If this function returns, sleep was not entered and the result is false. Reasons include
+    ///         invalid arguments, existing RTC IRQ cleanup failure, RTC setup failure,
+    ///         wake source registration failure, and PC builds.
+    ///         Does not return once sleep is entered.
+    /// @note The RTC alarm wakes only boards where its IRQ is wired to a wake route;
+    ///       an alarm from an external RTC unit does not wake the board.
+    /// @note An ESP timer wake-up left by an earlier sleep is disabled and not restored.
     /// @attention CoreInk and M5Paper can't alarm boot because it can't be turned off while connected to USB.
     /// @attention CoreInk と M5Paper は USB接続中はRTCタイマー起動が出来ない。;
-    void timerSleep(const rtc_date_t& date, const rtc_time_t& time);
+    bool timerSleep(const rtc_date_t& date, const rtc_time_t& time);
 
     /// Value for micro_seconds of deepSleep / lightSleep, meaning "sleep without a timer wakeup".
     /// The device sleeps until a wakeup pin or another wakeup source is triggered.
@@ -458,8 +481,11 @@ namespace m5
     /// that the answer is one of the advertised capabilities.
     charge_state_t _getChargeState(void);
     std::int32_t _getBatteryAdcRaw(void);
-    void _powerOff(bool withTimer);
-    void _timerSleep(void);
+    bool _disableEspTimerWakeup(void);
+    /// withTimer: wake by an RTC IRQ is expected (an RTC timer/alarm was armed).
+    bool _powerOff(bool withTimer);
+    /// rtc_armed: false = no RTC wake-up was armed (ESP timer only), so the RTC IRQ pin is not registered.
+    bool _timerSleep(bool rtc_armed = true);
 
 #if defined (CONFIG_IDF_TARGET_ESP32C5) || defined (CONFIG_IDF_TARGET_ESP32C61)
     /// Check whether a battery is actually attached (non-blocking).