Add burst timeout configuration for peer discovery in ScanConfig

- Introduced `DEFAULT_BURST_TIMEOUT` to limit the total time spent at boosted TX power during peer discovery.
- Updated `ScanConfig` to include a `burst_timeout` field and a method to override it.
- Enhanced the scanning logic to respect the burst timeout, stopping early if the limit is reached.
- Documented the new burst timeout behavior and its implications for TX power management.

Author: fwaibel

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `espnow-pure`: `ScanConfig::with_probe_timeout()` and `DEFAULT_PROBE_TIMEOUT` (100 ms) — per-channel probe timeout is now configurable
+- `espnow-pure`: `ScanConfig::with_burst_timeout()` and `DEFAULT_BURST_TIMEOUT` (3 s) — bounds total time the radio spends at boosted TX power during peer discovery
 - `wifi-pure`: `TxPowerLevel` enum (`Lowest`, `Low`, `Medium`, `High`, `Max`) with `to_quarter_dbm()` mapping to ESP-IDF quarter-dBm values; `WiFiConfig::with_tx_power()` builder method (see `docs/features/wifi-radio-power-config-v1.md`)
 - `rustyfarian-esp-hal-wifi`: `EspHalWifiManager` with real `WifiDriver` implementation using `esp-radio 0.17.0` for bare-metal ESP32-C3/C6 (ADR 006 Phase 5); `hal_c3_connect` and `hal_c6_connect` examples
 - `rustyfarian-network-pure`: `status_colors` module with shared LED colour palette (`BOOT`, `WIFI_CONNECTING`, `MQTT_CONNECTING`, `CONNECTED`, `ERROR`, `OFFLINE`)

crates/espnow-pure/src/lib.rs

@@ -43,6 +43,15 @@ pub const DEFAULT_SCAN_CHANNELS: [u8; 13] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11,
 /// [`ScanConfig::with_probe_timeout`].
 pub const DEFAULT_PROBE_TIMEOUT: core::time::Duration = core::time::Duration::from_millis(100);
 
+/// Default total burst timeout for a peer scan.
+///
+/// Caps the wall-clock time the radio spends at boosted TX power during a
+/// scan, regardless of how many channels remain.  At default settings
+/// (13 channels × 100 ms probe) the loop already finishes in ~1.3 s; this
+/// only kicks in for long custom probe timeouts or large channel lists.
+/// Override with [`ScanConfig::with_burst_timeout`].
+pub const DEFAULT_BURST_TIMEOUT: core::time::Duration = core::time::Duration::from_secs(3);
+
 // ─── Types ───────────────────────────────────────────────────────────────────
 
 /// A 6-byte IEEE 802.11 MAC address.
@@ -175,16 +184,23 @@ pub struct ScanConfig<'a> {
     pub probe_data: &'a [u8],
     /// Per-channel probe timeout (default: [`DEFAULT_PROBE_TIMEOUT`] = 100 ms).
     pub probe_timeout: core::time::Duration,
+    /// Total burst timeout (default: [`DEFAULT_BURST_TIMEOUT`] = 3 s).
+    ///
+    /// The scan loop checks elapsed time before each channel and stops
+    /// early once this limit is reached.  Bounds the time the radio
+    /// spends at boosted TX power during peer discovery.
+    pub burst_timeout: core::time::Duration,
 }
 
 impl<'a> ScanConfig<'a> {
     /// Create a scan config with default channels (1-13), the given probe
-    /// payload, and the default probe timeout.
+    /// payload, the default probe timeout, and the default burst timeout.
     pub fn new(probe_data: &'a [u8]) -> Self {
         Self {
             channels: &DEFAULT_SCAN_CHANNELS,
             probe_data,
             probe_timeout: DEFAULT_PROBE_TIMEOUT,
+            burst_timeout: DEFAULT_BURST_TIMEOUT,
         }
     }
 
@@ -199,6 +215,16 @@ impl<'a> ScanConfig<'a> {
         self.probe_timeout = timeout;
         self
     }
+
+    /// Override the total burst timeout.
+    ///
+    /// The scan loop stops early once this elapsed time is reached, even
+    /// if channels remain unprobed.  Use this to cap how long the radio
+    /// runs at boosted TX power if discovery fails.
+    pub fn with_burst_timeout(mut self, timeout: core::time::Duration) -> Self {
+        self.burst_timeout = timeout;
+        self
+    }
 }
 
 // ─── ScanResult ─────────────────────────────────────────────────────────────
@@ -368,6 +394,7 @@ mod tests {
         assert_eq!(config.channels, &DEFAULT_SCAN_CHANNELS);
         assert_eq!(config.probe_data, b"probe");
         assert_eq!(config.probe_timeout, DEFAULT_PROBE_TIMEOUT);
+        assert_eq!(config.burst_timeout, DEFAULT_BURST_TIMEOUT);
     }
 
     #[test]
@@ -384,6 +411,13 @@ mod tests {
         assert_eq!(config.probe_timeout, timeout);
     }
 
+    #[test]
+    fn scan_config_custom_burst_timeout() {
+        let timeout = core::time::Duration::from_secs(5);
+        let config = ScanConfig::new(b"ping").with_burst_timeout(timeout);
+        assert_eq!(config.burst_timeout, timeout);
+    }
+
     #[test]
     fn scan_result_equality() {
         assert_eq!(ScanResult { channel: 6 }, ScanResult { channel: 6 });

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

@@ -226,6 +226,14 @@ impl EspIdfEspNow {
         Ok((driver, result))
     }
 
+    /// Scan the channels in `config` for the peer at `mac`.
+    ///
+    /// Note on radio side-effects: TX power is a global radio setting.
+    /// While the burst is active, any concurrent Wi-Fi or ESP-NOW
+    /// transmissions on this chip also go out at the boosted level.
+    /// On dual-radio (Wi-Fi + ESP-NOW on the same chip) deployments,
+    /// schedule scans during quiet periods if predictable per-frame
+    /// power matters.
     fn scan_channels(
         &self,
         mac: &MacAddress,
@@ -257,7 +265,19 @@ impl EspIdfEspNow {
         }
 
         let scan_result = (|| -> anyhow::Result<ScanResult> {
+            let burst_start = Instant::now();
+            let mut probed = 0usize;
+
             for &channel in config.channels {
+                if burst_start.elapsed() >= config.burst_timeout {
+                    log::debug!(
+                        "Burst timeout {:?} reached after {} channels; stopping scan",
+                        config.burst_timeout,
+                        probed
+                    );
+                    break;
+                }
+
                 log::debug!("Probing channel {} for peer {:02X?}", channel, mac);
 
                 // SAFETY: esp_wifi_set_channel is an FFI call into the ESP-IDF
@@ -280,6 +300,8 @@ impl EspIdfEspNow {
                     continue;
                 }
 
+                probed += 1;
+
                 match ack_status.wait(config.probe_timeout) {
                     Some(true) => return Ok(ScanResult { channel }),
                     Some(false) => log::debug!("No ACK on channel {}", channel),
@@ -288,7 +310,8 @@ impl EspIdfEspNow {
             }
 
             anyhow::bail!(
-                "peer not found on any of the {} scanned channels",
+                "peer not found after probing {} of {} configured channels",
+                probed,
                 config.channels.len()
             )
         })();

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

@@ -234,13 +234,21 @@ impl WiFiManager {
         log::info!("WiFi started, power save: {:?}", config.power_save);
 
         let tx_power = config.tx_power.to_quarter_dbm();
-        esp_idf_svc::sys::esp!(unsafe { esp_idf_svc::sys::esp_wifi_set_max_tx_power(tx_power) })
-            .context("failed to set WiFi TX power")?;
-        log::info!(
-            "WiFi TX power set to {:?} ({} quarter-dBm)",
-            config.tx_power,
-            tx_power
-        );
+        match esp_idf_svc::sys::esp!(unsafe {
+            esp_idf_svc::sys::esp_wifi_set_max_tx_power(tx_power)
+        }) {
+            Ok(()) => log::info!(
+                "WiFi TX power set to {:?} ({} quarter-dBm)",
+                config.tx_power,
+                tx_power
+            ),
+            Err(e) => log::warn!(
+                "Failed to set WiFi TX power to {:?} ({} quarter-dBm), continuing at radio default: {:?}",
+                config.tx_power,
+                tx_power,
+                e
+            ),
+        }
 
         // 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

@@ -123,6 +123,13 @@ pub enum WifiPowerSave {
 /// | `Medium` | 52          | 13         |
 /// | `High`   | 68          | 17         |
 /// | `Max`    | 78          | 19.5       |
+///
+/// These values are heuristic defaults intended to span the usable range of
+/// supported ESP32 chips.
+/// Local regulatory limits, antenna design, and per-board layout may require
+/// lower settings — pick the lowest level that meets your range needs.
+/// The backend may also clamp the requested value to the chip's effective
+/// maximum, so the actual radiated power can differ from the table above.
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub enum TxPowerLevel {
     /// Minimum transmit power (~2 dBm). Best for close-range, low-heat use.

docs/features/wifi-radio-power-config-v1.md

@@ -2,15 +2,15 @@
 
 ## Decisions
 
-|                                                                                           Decision | Reason                                                                | Rejected Alternative                                                                 |
-|---------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------|:-------------------------------------------------------------------------------------|
-|                               5-level enum for TX power (`Lowest`, `Low`, `Medium`, `High`, `Max`) | Intuitive for users; abstracts raw dBm values which vary by chip      | Raw dBm integer — too low-level, error-prone, chip-dependent limits                  |
-|                                    5-level enum for power-save mode reusing the same scale concept | Consistent API; lowest maps to `MinModem`, highest maps to `MaxModem` | Exposing ESP-IDF `WifiPowerSave` directly — leaks platform detail                    |
-|                                                      Configuration at init time only (builder API) | Simplest correct approach; runtime adjustment can be added later      | Runtime-adjustable — unnecessary complexity for current use case                     |
-| Auto-burst during discovery: full TX power during `scan_for_peer()`, then drop to configured level | Maximizes discovery range without permanent heat; no manual toggling  | Always-high power — defeats the purpose; manual toggle — error-prone, easy to forget |
-|                                 Discovery burst has a configurable timeout (default a few seconds) | Prevents staying at full power if peer never comes online             | No timeout — risks sustained high power indefinitely on failed discovery             |
-|                                       Exact dBm mapping per level determined during implementation | Requires testing on real hardware across C3/C6/S3                     | Guessing values upfront — unreliable without measurement                             |
-|                                      Shared enum types in `wifi-pure` (platform-independent crate) | Keeps types testable and reusable across ESP-IDF and esp-hal backends | Defining in each HAL crate — duplication, divergent APIs                             |
+|                                                                                                Decision | Reason                                                                              | Rejected Alternative                                                                 |
+|--------------------------------------------------------------------------------------------------------:|:------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------|
+|                                    5-level enum for TX power (`Lowest`, `Low`, `Medium`, `High`, `Max`) | Intuitive for users; abstracts raw dBm values which vary by chip                    | Raw dBm integer — too low-level, error-prone, chip-dependent limits                  |
+|                                                           Configuration at init time only (builder API) | Simplest correct approach; runtime adjustment can be added later                    | Runtime-adjustable — unnecessary complexity for current use case                     |
+|                                                   TX power apply failure is non-fatal (warn + continue) | Matches existing `power_save` handling; tuning, not correctness                     | Returning an error — would block Wi-Fi start on a tuning preference                  |
+|      Auto-burst during discovery: full TX power during `scan_for_peer()`, then drop to configured level | Maximizes discovery range without permanent heat; no manual toggling                | Always-high power — defeats the purpose; manual toggle — error-prone, easy to forget |
+|                                              Burst bounded by an explicit `burst_timeout` (3 s default) | Prevents staying at full power if peer never comes online; checked between channels | Implicit bound from `channels × probe_timeout` — drifts with custom configs          |
+|                                            Exact dBm mapping per level determined during implementation | Requires testing on real hardware across C3/C6/S3                                   | Guessing values upfront — unreliable without measurement                             |
+|                                           Shared enum types in `wifi-pure` (platform-independent crate) | Keeps types testable and reusable across ESP-IDF and esp-hal backends               | Defining in each HAL crate — duplication, divergent APIs                             |
 
 ## Constraints
 
@@ -37,3 +37,4 @@
 - 2026-04-03 — Feature doc created via /feature dialog
 - 2026-04-03 — Added auto-burst during discovery with timeout
 - 2026-04-10 — Implemented: `TxPowerLevel` enum in `wifi-pure` with 5 levels and `to_quarter_dbm()` mapping. ESP-IDF backend calls `esp_wifi_set_max_tx_power()` after `wifi.start()`. esp-hal backend stores config but logs warning (esp-radio 0.17 lacks TX power API). ESP-NOW `scan_for_peer()` auto-bursts to max TX power during scanning with save/restore. 24 wifi-pure tests pass including 6 new TxPowerLevel tests. `just verify` and `just build-example` (hal_c3_connect, hal_c3_connect_async) all pass clean.
+- 2026-05-05 — Review follow-ups: dropped unimplemented "5-level power-save enum" decision row (PR reuses `WifiPowerSave`); added explicit `burst_timeout` (3 s default) to `ScanConfig` with early break in scan loop; converted ESP-IDF TX power apply failure to warn-and-continue (matches existing `power_save` handling); added regulatory/clamping note to `TxPowerLevel` docstring; added concurrency note to `scan_channels()`; replaced hardcoded burst value with `wifi_pure::TxPowerLevel::Max.to_quarter_dbm()` to remove drift risk.