updated STM32 README

Author: dirkju

hal/architecture/STM32/README.md

@@ -27,7 +27,10 @@ Should work on any STM32 board supported by the STM32duino core.
 - [x] Serial communication (USB CDC and Hardware UART)
 - [x] SPI interface for radios (nRF24L01+, RFM69, RFM95)
 - [x] EEPROM emulation using Flash memory
-- [x] Watchdog support (requires explicit initialization)
+- [x] Watchdog support (Independent Watchdog - IWDG)
+- [x] **Low-power sleep modes** (STOP mode with RTC wake-up)
+- [x] **RTC-based timekeeping** (wake-up timer for sleep intervals)
+- [x] **Interrupt-based wake from sleep** (GPIO EXTI on any pin)
 - [x] System reboot
 - [x] Random number generation (using internal temperature sensor)
 - [x] Unique device ID (96-bit STM32 UID)
@@ -38,10 +41,9 @@ Should work on any STM32 board supported by the STM32duino core.
 - [x] RAM routing table support
 
 ### Planned 🔄
-- [ ] Low-power sleep modes (STOP, STANDBY)
-- [ ] RTC-based timekeeping
-- [ ] Interrupt-based wake from sleep
 - [ ] Free memory reporting (heap analysis)
+- [ ] STANDBY mode support (optional, for ultra-low-power applications)
+- [ ] STM32L4-specific STOP2 mode optimization
 
 ## Pin Mapping
 
@@ -234,21 +236,283 @@ The STM32 HAL uses the STM32duino EEPROM library, which provides Flash-based EEP
 
 Configuration is automatic. EEPROM size can be adjusted in the STM32duino menu or via build flags.
 
-## Low-Power Considerations
+## Watchdog Support
 
-### Current Status
-Sleep modes are **NOT YET IMPLEMENTED** in this initial release. Calling `sleep()` functions will return `MY_SLEEP_NOT_POSSIBLE`.
+The STM32 HAL supports the Independent Watchdog (IWDG) for system reliability and crash recovery.
 
-### Future Implementation
-The STM32 supports several low-power modes:
-- **Sleep mode**: ~10mA (CPU stopped, peripherals running)
-- **Stop mode**: ~10-100µA (CPU and most peripherals stopped)
-- **Standby mode**: ~1-10µA (only backup domain active)
+### Overview
 
-Implementation will use:
-- RTC for timed wake-up
-- EXTI for interrupt wake-up
-- Backup SRAM for state retention
+- **Hardware watchdog** using STM32 IWDG peripheral
+- **Maximum timeout**: ~32 seconds (hardware limitation)
+- **Clock source**: Internal LSI oscillator (~32 kHz, ±40% accuracy)
+- **No external components** required
+- Works on all STM32 boards
+
+### Important Notes
+
+⚠️ **Watchdog is NOT automatically initialized** by MySensors. You must explicitly initialize and manage it in your sketch.
+
+⚠️ **Maximum timeout is ~32 seconds**. For longer intervals (e.g., low-power sensors with 1-hour wake cycles), you must periodically wake and feed the watchdog during sleep.
+
+⚠️ **Initialize watchdog LAST** in `setup()` after all delays and initialization to prevent premature timeout during startup.
+
+### Timeout Calculation
+
+The watchdog timeout depends on prescaler and reload value:
+
+```
+Timeout (seconds) = (Prescaler / 32000) × Reload
+```
+
+**Common configurations:**
+
+| Prescaler | Reload | Timeout | Use Case |
+|-----------|--------|---------|----------|
+| `IWDG_PRESCALER_32` | 4000 | ~4 seconds | Normal operation |
+| `IWDG_PRESCALER_128` | 4095 | ~16 seconds | Slower tasks |
+| `IWDG_PRESCALER_256` | 2500 | ~20 seconds | Recommended for sleep |
+| `IWDG_PRESCALER_256` | 4095 | ~32 seconds | Maximum timeout |
+
+### Usage Example
+
+```cpp
+#include <MySensors.h>
+#include "stm32f4xx_hal.h"
+
+IWDG_HandleTypeDef hiwdg;
+
+void initWatchdog() {
+    hiwdg.Instance = IWDG;
+    hiwdg.Init.Prescaler = IWDG_PRESCALER_256;
+    hiwdg.Init.Reload = 2500;  // ~20 second timeout (256/32000 * 2500 = 20s)
+    HAL_IWDG_Init(&hiwdg);
+}
+
+void setup() {
+    // Initialize everything first
+    // ...
+
+    // Initialize watchdog LAST (after all delays)
+    initWatchdog();
+}
+
+void loop() {
+    // Feed watchdog at start of loop
+    hwWatchdogReset();  // or: IWDG->KR = 0xAAAA;
+
+    // Your sensor code
+    readSensor();
+    sendData();
+
+    // Sleep in chunks, feeding watchdog during sleep
+    // Must wake every <20 seconds to feed the watchdog
+    watchdogSafeSleep(60000);  // Sleep for 1 minute total
+}
+
+void watchdogSafeSleep(uint32_t ms) {
+    uint32_t remaining = ms;
+    while (remaining > 0) {
+        uint32_t chunk = min(15000, remaining);  // 15-second chunks (< 20-second timeout)
+        sleep(chunk);
+        hwWatchdogReset();  // Feed watchdog after each chunk
+        remaining -= chunk;
+    }
+}
+```
+
+### Long Sleep Intervals with Watchdog
+
+For battery-powered sensors with long sleep intervals (e.g., 1 hour), you must wake periodically to feed the watchdog:
+
+```cpp
+void loop() {
+    hwWatchdogReset();
+
+    readSensor();
+    sendData();
+
+    // Sleep for 1 hour in chunks, feeding watchdog every 15 seconds
+    watchdogSafeSleep(3600000);
+}
+
+void watchdogSafeSleep(uint32_t ms) {
+    uint32_t remaining = ms;
+    while (remaining > 0) {
+        uint32_t chunk = min(15000, remaining);  // 15s chunks (< 20s timeout)
+        sleep(chunk);
+        hwWatchdogReset();  // Feed watchdog after each chunk
+        remaining -= chunk;
+    }
+}
+```
+
+**Key points:**
+- Sleep in chunks smaller than watchdog timeout
+- Feed watchdog between sleep chunks
+- This adds brief wake-ups (~1ms every 15 seconds) but provides crash protection
+
+**Alternative:** For ultra-low-power applications where watchdog wake-ups are unacceptable, consider:
+- External watchdog IC (e.g., TPL5010 with up to 2-hour timeout)
+- Software counter: Only trigger watchdog reset after N failed wake cycles
+
+### Build Configuration
+
+Add to `platformio.ini`:
+
+```ini
+build_flags =
+    -D HAL_IWDG_MODULE_ENABLED  ; Required to enable IWDG HAL module
+```
+
+**Note**: This build flag is **required** and cannot be defined in source code. The STM32 HAL framework needs this flag during compilation.
+
+### Detecting Watchdog Resets
+
+Check if the last reset was caused by the watchdog:
+
+```cpp
+void setup() {
+    if (__HAL_RCC_GET_FLAG(RCC_FLAG_IWDGRST)) {
+        // System was reset by watchdog
+        __HAL_RCC_CLEAR_RESET_FLAGS();
+        // Handle watchdog reset (e.g., log error, send alert)
+    }
+
+    // ... rest of setup
+    initWatchdog();  // Initialize watchdog LAST
+}
+```
+
+## Low-Power Sleep Support
+
+### Overview
+
+The STM32 HAL implements **STOP mode** for battery-powered sensor nodes, providing multi-year battery life while maintaining MySensors compatibility.
+
+### Sleep Modes
+
+| Mode | Sleep Current | Wake-up Time | Features | Battery Life* |
+|------|---------------|--------------|----------|---------------|
+| **STOP** ✅ | 10-50 µA | 1-3 ms | GPIO EXTI wake, RTC timer, state retained | **5-10 years** |
+| STANDBY 🔄 | 2-4 µA | 5-10 ms | RTC timer only, state lost | 10+ years |
+
+*Based on 2x AA batteries (2000 mAh), 5-minute reporting interval
+
+**Currently Implemented**: STOP mode (recommended for all battery-powered MySensors nodes)
+
+### Power Consumption
+
+**Typical Battery-Powered Sensor** (5-minute reporting interval):
+
+```
+Average current: 30-50 µA
+Battery life (2x AA): 5-10 years
+Sleep current (STM32F4): 30 µA
+Sleep current (STM32L4): 2-5 µA
+```
+
+### Sleep API Usage
+
+#### Timer-Based Sleep
+```cpp
+void loop() {
+    float temp = readTemperature();
+    send(msgTemp.set(temp, 1));
+
+    sleep(300000);  // Sleep for 5 minutes
+}
+```
+
+#### Interrupt Wake-Up (Event-Driven Sensors)
+```cpp
+#define BUTTON_PIN PA0
+
+void loop() {
+    // Sleep until button pressed
+    sleep(digitalPinToInterrupt(BUTTON_PIN), CHANGE, 0);
+
+    // Button was pressed
+    send(msgButton.set(1));
+}
+```
+
+#### Combined Timer + Interrupt Wake-Up
+```cpp
+void loop() {
+    // Sleep until button press OR 1 hour timeout
+    int8_t wakeReason = sleep(digitalPinToInterrupt(BUTTON_PIN), CHANGE, 3600000);
+
+    if (wakeReason == MY_WAKE_UP_BY_TIMER) {
+        // Timed wake-up - send periodic report
+        sendPeriodicReport();
+    } else {
+        // Button press wake-up
+        handleButtonPress();
+    }
+}
+```
+
+### Sleep Implementation Details
+
+**STOP Mode Characteristics**:
+- ✅ **GPIO EXTI wake-up** on any pin (supports radio IRQ, sensors, buttons)
+- ✅ **RTC wake-up timer** for periodic operation (1 ms to ~18 hours)
+- ✅ **State retention** (SRAM and registers preserved)
+- ✅ **Fast wake-up** (1-3 ms, compatible with radio timing)
+- ✅ **Low power** (10-50 µA on STM32F4, 2-5 µA on STM32L4)
+
+**Wake-up Sources**:
+- RTC wake-up timer (configured automatically by `sleep(ms)`)
+- GPIO EXTI interrupts (any pin, any edge)
+- Watchdog timeout (if enabled)
+
+**System Behavior**:
+1. Before sleep: RTC configured, interrupts attached, SysTick suspended
+2. During sleep: MCU in STOP mode (10-50 µA), peripherals stopped
+3. After wake-up: System clock restored, SysTick resumed, wake source identified
+4. State preserved: No reinitialization required
+
+### Configuration Options
+
+#### Sleep Configuration (MyConfig.h)
+```cpp
+// Stay on HSI (16 MHz) after wake-up for faster wake-up (default)
+// Uncomment to restore full speed (84 MHz) at cost of +2 ms wake-up time
+// #define MY_STM32_USE_HSE_AFTER_WAKEUP
+
+// RTC clock source (LSE recommended for accuracy)
+#define MY_STM32_RTC_CLOCK_SOURCE LSE  // Or LSI if no 32kHz crystal
+```
+
+#### Power Optimization Build Flags
+```ini
+[env:battery_sensor]
+build_flags =
+    -D MY_DISABLED_SERIAL          ; Disable serial for low power
+    -D MY_TRANSPORT_WAIT_READY_MS=1  ; Don't wait for gateway
+    -D MY_SLEEP_TRANSPORT_RECONNECT_TIMEOUT_MS=2000
+```
+
+### Hardware Considerations
+
+**For Best Battery Life**:
+1. **Use STM32L4** series for ultra-low-power (2-5 µA sleep vs 30 µA on STM32F4)
+2. **Add LSE crystal** (32.768 kHz) for accurate RTC timing
+3. **Disable unused peripherals** (USB, debug, unused UARTs)
+4. **Configure GPIO properly** (no floating pins, use pull-ups/downs)
+5. **Choose efficient regulator** (low quiescent current LDO <10 µA)
+
+**Compatible Radios**:
+- **nRF24L01+**: Radio can sleep (0.9 µA), IRQ pin wakes MCU
+- **RFM69/RFM95**: Radio can sleep (1-5 µA), DIO pins wake MCU
+
+### Known Limitations
+
+1. **Maximum sleep time**: ~18 hours (RTC wake-up timer limitation)
+   - For longer intervals, use multiple sleep cycles
+2. **Debug interface**: Disable in sleep for lowest power (debug keeps ~2 mA active)
+3. **USB CDC**: Not compatible with sleep (use hardware UART or disable serial)
+4. **STANDBY mode**: Not yet implemented (state loss, no GPIO EXTI support)
 
 ## Troubleshooting
 
@@ -301,14 +565,19 @@ Implementation will use:
 - **CPU**: 100 MHz ARM Cortex-M4F
 - **Flash**: 512KB
 - **RAM**: 128KB
-- **Current**: ~50mA active, <1µA standby (when implemented)
+- **Current (active)**: ~30-50 mA
+- **Current (STOP mode)**: 30-50 µA (STM32F4), 2-5 µA (STM32L4)
 - **MySensors overhead**: ~30KB Flash, ~4KB RAM
+- **Battery life**: 5-10 years (2x AA, 5-min reporting)
 
-### Benchmarks (preliminary)
-- **Radio message latency**: <10ms (similar to AVR)
+### Benchmarks
+- **Radio message latency**: <10ms (comparable to AVR)
+- **Wake-up time**: 1-3 ms (STOP mode)
 - **EEPROM read**: ~50µs per byte
 - **EEPROM write**: ~5ms per byte (Flash write)
 - **Temperature reading**: ~100µs
+- **Sleep current**: 30 µA typical (STM32F4 STOP mode)
+- **Average current** (5-min sensor): 30-50 µA
 
 ## Contributing
 
@@ -333,8 +602,16 @@ This code is part of the MySensors project and is licensed under the GNU General
 
 ## Version History
 
+- **v1.1.0** (2025-01-23) - Sleep mode and watchdog support
+  - ✅ STOP mode sleep implementation
+  - ✅ RTC wake-up timer (1 ms to ~18 hours)
+  - ✅ GPIO EXTI interrupt wake-up (any pin, any edge)
+  - ✅ Dual interrupt wake-up support
+  - ✅ Independent Watchdog (IWDG) support
+  - ✅ System clock reconfiguration after wake-up
+  
 - **v1.0.0** (2025-01-17) - Initial STM32 HAL implementation
   - Basic functionality (GPIO, SPI, EEPROM, Serial)
-  - Tested on STM32F401/F411 Black Pill
   - Gateway and sensor node support
-  - No sleep mode yet (planned for v1.1.0)
+  - CPU voltage and temperature reading
+  - Watchdog reset function (initialization required in user sketch)