Add Wi-Fi power save configuration with WifiPowerSave enum and builder method

Author: fwaibel

CHANGELOG.md

@@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `rustyfarian-esp-idf-mqtt`: non-blocking `MqttHandle::try_publish`, `try_publish_retained`, and `try_publish_with` with `TryPublishError` for time-critical loops
+- `wifi-pure`: `WifiPowerSave` enum (`None`, `MinModem`, `MaxModem`) and `WiFiConfig::with_power_save()` builder method
+- `rustyfarian-esp-idf-wifi`: applies configured power save mode via `esp_wifi_set_ps()` after Wi-Fi start
 
 ## [0.1.0] - 2026-03-16
 

crates/rustyfarian-esp-idf-wifi/src/lib.rs

@@ -66,7 +66,8 @@ use rgb::RGB8;
 // Re-export all pure types from wifi-pure
 pub use wifi_pure::{
     validate_password, validate_ssid, wifi_disconnect_reason_name, ConnectMode, WiFiConfig,
-    WifiDriver, DEFAULT_TIMEOUT_SECS, PASSWORD_MAX_LEN, POLL_INTERVAL_MS, SSID_MAX_LEN,
+    WifiDriver, WifiPowerSave, DEFAULT_TIMEOUT_SECS, PASSWORD_MAX_LEN, POLL_INTERVAL_MS,
+    SSID_MAX_LEN,
 };
 
 // Re-export StatusLed and SimpleLed from led_effects for convenience
@@ -156,7 +157,15 @@ impl WiFiManager {
         }))?;
 
         wifi.start()?;
-        log::info!("WiFi started");
+
+        let ps_mode = match config.power_save {
+            WifiPowerSave::None => esp_idf_svc::sys::wifi_ps_type_t_WIFI_PS_NONE,
+            WifiPowerSave::MinModem => esp_idf_svc::sys::wifi_ps_type_t_WIFI_PS_MIN_MODEM,
+            WifiPowerSave::MaxModem => esp_idf_svc::sys::wifi_ps_type_t_WIFI_PS_MAX_MODEM,
+        };
+        esp_idf_svc::sys::esp!(unsafe { esp_idf_svc::sys::esp_wifi_set_ps(ps_mode) })
+            .context("failed to set WiFi power save mode")?;
+        log::info!("WiFi started, power save: {:?}", config.power_save);
 
         // In non-blocking mode, subscribe to disconnect events so failures such as
         // WIFI_REASON_NO_AP_FOUND are visible at WARN level without enabling debug logs.

crates/wifi-pure/src/lib.rs

@@ -82,6 +82,27 @@ impl Default for ConnectMode {
     }
 }
 
+// ─── WifiPowerSave ──────────────────────────────────────────────────────────
+
+/// Wi-Fi power save mode passed to `esp_wifi_set_ps()` after starting Wi-Fi.
+///
+/// # ESP-NOW caveat
+///
+/// `esp-idf-svc` `EspNow::take()` internally forces `WIFI_PS_NONE`,
+/// overriding whatever mode was set here.
+/// This setting is most useful for battery-powered devices that use
+/// Wi-Fi *without* ESP-NOW.
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub enum WifiPowerSave {
+    /// Radio always on. Best latency, highest power draw.
+    #[default]
+    None,
+    /// Minimum modem sleep — radio sleeps between DTIM beacon intervals.
+    MinModem,
+    /// Maximum modem sleep — radio sleeps as long as possible.
+    MaxModem,
+}
+
 // ─── WiFiConfig ─────────────────────────────────────────────────────────────
 
 /// Wi-Fi connection configuration.
@@ -90,14 +111,16 @@ impl Default for ConnectMode {
 ///
 /// ```ignore
 /// let config = WiFiConfig::new("MyNetwork", "password123")
-///     .with_timeout(60)      // optional: override the 30 s default
-///     .connect_nonblocking(); // optional: return immediately from new()
+///     .with_timeout(60)                    // optional: override the 30 s default
+///     .connect_nonblocking()                    // optional: return immediately from new()
+///     .with_power_save(WifiPowerSave::MinModem); // optional: modem sleep for battery savings
 /// ```
 #[derive(Debug, Clone)]
 pub struct WiFiConfig<'a> {
     pub ssid: &'a str,
     pub password: &'a str,
     pub connect_mode: ConnectMode,
+    pub power_save: WifiPowerSave,
 }
 
 impl<'a> WiFiConfig<'a> {
@@ -109,6 +132,7 @@ impl<'a> WiFiConfig<'a> {
             ssid,
             password,
             connect_mode: ConnectMode::default(),
+            power_save: WifiPowerSave::default(),
         }
     }
 
@@ -134,6 +158,19 @@ impl<'a> WiFiConfig<'a> {
         self.connect_mode = ConnectMode::NonBlocking;
         self
     }
+
+    /// Sets the Wi-Fi power save mode applied after `wifi.start()`.
+    ///
+    /// Defaults to [`WifiPowerSave::None`] (radio always on).
+    ///
+    /// # ESP-NOW caveat
+    ///
+    /// `esp-idf-svc` `EspNow::take()` internally forces `WIFI_PS_NONE`,
+    /// overriding whatever mode is set here.
+    pub fn with_power_save(mut self, mode: WifiPowerSave) -> Self {
+        self.power_save = mode;
+        self
+    }
 }
 
 // ─── Disconnect reason mapping ──────────────────────────────────────────────
@@ -332,6 +369,43 @@ mod tests {
         assert!(!driver.is_connected().unwrap());
     }
 
+    // ── WifiPowerSave tests ──────────────────────────────────────────────
+
+    #[test]
+    fn power_save_default_is_none() {
+        assert_eq!(WifiPowerSave::default(), WifiPowerSave::None);
+    }
+
+    #[test]
+    fn wifi_config_default_power_save_is_none() {
+        let config = test_config();
+        assert_eq!(config.power_save, WifiPowerSave::None);
+    }
+
+    #[test]
+    fn wifi_config_power_save_min_modem() {
+        let config = test_config().with_power_save(WifiPowerSave::MinModem);
+        assert_eq!(config.power_save, WifiPowerSave::MinModem);
+    }
+
+    #[test]
+    fn wifi_config_power_save_max_modem() {
+        let config = test_config().with_power_save(WifiPowerSave::MaxModem);
+        assert_eq!(config.power_save, WifiPowerSave::MaxModem);
+    }
+
+    #[test]
+    fn wifi_config_chained_builders() {
+        let config = test_config()
+            .with_timeout(60)
+            .with_power_save(WifiPowerSave::MinModem)
+            .connect_nonblocking();
+        assert!(matches!(config.connect_mode, ConnectMode::NonBlocking));
+        assert_eq!(config.power_save, WifiPowerSave::MinModem);
+    }
+
+    // ── MockWifiDriver tests ────────────────────────────────────────────
+
     #[test]
     fn mock_driver_fail_connect() {
         let mut driver = mock::MockWifiDriver::new();

crates/wifi-pure/src/mock.rs

@@ -22,7 +22,7 @@
 //! assert_eq!(driver.connect_count, 1);
 //! ```
 
-use crate::WifiDriver;
+use crate::{WifiDriver, WifiPowerSave};
 
 /// Error type for [`MockWifiDriver`].
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -48,6 +48,7 @@ pub struct MockWifiDriver {
     pub netif_up: bool,
     pub connect_count: u32,
     pub fail_connect: bool,
+    pub power_save: WifiPowerSave,
 }
 
 impl MockWifiDriver {
@@ -60,6 +61,7 @@ impl MockWifiDriver {
             netif_up: false,
             connect_count: 0,
             fail_connect: false,
+            power_save: WifiPowerSave::default(),
         }
     }
 }

docs/ROADMAP.md

@@ -25,7 +25,8 @@ timeline
               : Phase 5 — TTN v3 EU868 OTAA validation (blocked on hardware)
               : LoRa post-adoption backlog — builder pattern, CRC-32, hardware driver, state machine
 
-    Long term : Full EspHalLoraRadio hardware driver (after TTN validation)
+    Long term : Evaluate ESP-IDF v5.5.2 coex fix for ESP-NOW send failures
+              : Full EspHalLoraRadio hardware driver (after TTN validation)
               : rustyfarian-esp-hal-mqtt — minimq-based bare-metal MQTT (after esp-hal WiFi)
 ```
 
@@ -136,6 +137,12 @@ All steps use TTN v3 EU868.
 
 </details>
 
+### Research
+
+| # | Item                                                                                                                       |
+|--:|:---------------------------------------------------------------------------------------------------------------------------|
+| 1 | Evaluate ESP-IDF v5.5.2 — contains fix for "ESP-NOW send failure when coexistence is enabled"; track for next ESP-IDF bump |
+
 ### LoRa post-adoption backlog
 
 <details>