Remove scan_*_max and scan_n* functions from esp-radio (#3963)

* Remove `scan_*_max` and `scan_n*` functions

* Derive `BuilderLite` for `ScanConfig`

* Update migration guide for `esp-radio`

* Update changelogs

esp-hal-procmacros/CHANGELOG.md

@@ -9,16 +9,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Added support for lifetimes and generics to `BuilderLite` derive macro (#3963)
 
 ### Changed
 
-
 ### Fixed
 
-
 ### Removed
 
-
 ## [v0.19.0] - 2025-07-16
 
 ### Added

esp-hal-procmacros/src/builder.rs

@@ -34,6 +34,7 @@ pub fn builder_lite_derive(item: TokenStream) -> TokenStream {
 
     let span = input.span();
     let ident = input.ident;
+    let generics = input.generics;
 
     let mut fns = Vec::new();
     let Data::Struct(DataStruct { fields, .. }) = &input.data else {
@@ -142,7 +143,7 @@ pub fn builder_lite_derive(item: TokenStream) -> TokenStream {
 
     let implementation = quote! {
         #[automatically_derived]
-        impl #ident {
+        impl #generics #ident #generics {
             #(#fns)*
         }
     };

esp-radio/CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - `AccessPointInfo::country` to access the Country Code from the Wi-Fi scan results (#3837)
 - `unstable` feature to opt into `ble`, `esp-now`, `csi`, `sniffer`, `esp-ieee802154` and `smoltcp` APIs (#3865)
+- Optional `max` field in `ScanConfig` to allow limiting the number of returned results (#3963)
 
 ### Changed
 
@@ -31,6 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+- `scan_with_config_sync_max`, `scan_with_config_sync_max`, `scan_n`, and `scan_n_async` functions (#3963)
 
 ## [v0.15.0] - 2025-07-16
 

esp-radio/Cargo.toml

@@ -37,6 +37,7 @@ esp-wifi-sys = "0.7.1"
 num-derive = { version = "0.4.2" }
 num-traits = { version = "0.2.19", default-features = false }
 portable_atomic_enum = { version = "0.3.1", features = ["portable-atomic"] }
+procmacros = { version = "0.19.0", package = "esp-hal-procmacros", path = "../esp-hal-procmacros" }
 xtensa-lx-rt = { version = "0.20.0", path = "../xtensa-lx-rt", optional = true }
 byte = { version = "0.2.7", optional = true }
 ieee802154 = { version = "0.6.1", optional = true }

esp-radio/MIGRATING-0.15.0.md

@@ -49,3 +49,7 @@ Provide these symbols:
 + pub extern "C" fn realloc(ptr: *mut u8, new_size: usize) -> *mut u8 ...
 + pub extern "C" fn get_free_internal_heap_size() -> usize; ...
 ```
+
+## Scanning Functions
+
+The `scan_with_config_sync_max`, `scan_with_config_sync_max`, `scan_n`, and `scan_n_async` functions have been removed. You can instead use the `scan_with_config_async` or `scan_with_config_sync` funtions while specifying a `max` value in `ScanConfig`.

esp-radio/src/wifi/mod.rs

@@ -56,6 +56,7 @@ use num_derive::FromPrimitive;
 #[doc(hidden)]
 pub(crate) use os_adapter::*;
 use portable_atomic::{AtomicUsize, Ordering};
+use procmacros::BuilderLite;
 #[cfg(feature = "serde")]
 use serde::{Deserialize, Serialize};
 #[cfg(all(feature = "smoltcp", feature = "unstable"))]
@@ -1617,7 +1618,7 @@ impl ScanTypeConfig {
 }
 
 /// Scan configuration
-#[derive(Clone, Copy, Default, PartialEq, Eq)]
+#[derive(Clone, Copy, Default, PartialEq, Eq, BuilderLite)]
 pub struct ScanConfig<'a> {
     /// SSID to filter for.
     /// If [`None`] is passed, all SSIDs will be returned.
@@ -1638,6 +1639,10 @@ pub struct ScanConfig<'a> {
     pub show_hidden: bool,
     /// Scan type, active or passive.
     pub scan_type: ScanTypeConfig,
+    /// The maximum number of networks to return when scanning.
+    /// If [`None`] is passed, all networks will be returned.
+    /// If [`Some`] is passed, the specified number of networks will be returned.
+    pub max: Option<usize>,
 }
 
 pub(crate) fn wifi_start_scan(
@@ -1648,6 +1653,7 @@ pub(crate) fn wifi_start_scan(
         channel,
         show_hidden,
         scan_type,
+        ..
     }: ScanConfig<'_>,
 ) -> i32 {
     scan_type.validate();
@@ -2807,18 +2813,9 @@ impl WifiController<'_> {
     pub fn scan_with_config_sync(
         &mut self,
         config: ScanConfig<'_>,
-    ) -> Result<alloc::vec::Vec<AccessPointInfo>, WifiError> {
-        self.scan_with_config_sync_max(config, usize::MAX)
-    }
-
-    pub fn scan_with_config_sync_max(
-        &mut self,
-        config: ScanConfig<'_>,
-        max: usize,
     ) -> Result<alloc::vec::Vec<AccessPointInfo>, WifiError> {
         esp_wifi_result!(crate::wifi::wifi_start_scan(true, config))?;
-        let result = self.scan_results(max)?;
+        self.scan_results(config.max.unwrap_or(usize::MAX))
-        Ok(result)
     }
 
     fn scan_results(&mut self, max: usize) -> Result<alloc::vec::Vec<AccessPointInfo>, WifiError> {
@@ -2845,11 +2842,6 @@ impl WifiController<'_> {
         Ok(scanned)
     }
 
-    /// A blocking wifi network scan with default scanning options.
-    pub fn scan_n(&mut self, max: usize) -> Result<alloc::vec::Vec<AccessPointInfo>, WifiError> {
-        self.scan_with_config_sync_max(Default::default(), max)
-    }
-
     /// Starts the WiFi controller.
     pub fn start(&mut self) -> Result<(), WifiError> {
         crate::wifi::wifi_start()
@@ -3000,27 +2992,10 @@ impl WifiController<'_> {
         WifiMode::current()
     }
 
-    /// Async version of [`crate::wifi::WifiController`]'s `scan_n` method
-    pub async fn scan_n_async(
-        &mut self,
-        max: usize,
-    ) -> Result<alloc::vec::Vec<AccessPointInfo>, WifiError> {
-        self.scan_with_config_async_max(Default::default(), max)
-            .await
-    }
-
     /// An async wifi network scan with caller-provided scanning options.
     pub async fn scan_with_config_async(
         &mut self,
         config: ScanConfig<'_>,
-    ) -> Result<alloc::vec::Vec<AccessPointInfo>, WifiError> {
-        self.scan_with_config_async_max(config, usize::MAX).await
-    }
-
-    async fn scan_with_config_async_max(
-        &mut self,
-        config: ScanConfig<'_>,
-        max: usize,
     ) -> Result<alloc::vec::Vec<AccessPointInfo>, WifiError> {
         Self::clear_events(WifiEvent::ScanDone);
         esp_wifi_result!(wifi_start_scan(false, config))?;
@@ -3031,7 +3006,7 @@ impl WifiController<'_> {
 
         guard.defuse();
 
-        let result = self.scan_results(max)?;
+        let result = self.scan_results(config.max.unwrap_or(usize::MAX))?;
 
         Ok(result)
     }

examples/wifi/bench/src/main.rs

@@ -28,7 +28,7 @@ use esp_hal::{
     timer::timg::TimerGroup,
 };
 use esp_println::println;
-use esp_radio::wifi::{ClientConfiguration, Configuration};
+use esp_radio::wifi::{ClientConfiguration, Configuration, ScanConfig};
 use smoltcp::{
     iface::{SocketSet, SocketStorage},
     wire::{DhcpOption, IpAddress},
@@ -99,7 +99,8 @@ fn main() -> ! {
     println!("is wifi started: {:?}", controller.is_started());
 
     println!("Start Wifi Scan");
-    let res = controller.scan_n(10).unwrap();
+    let scan_config = ScanConfig::default().with_max(10);
+    let res = controller.scan_with_config_sync(scan_config).unwrap();
     for ap in res {
         println!("{:?}", ap);
     }

examples/wifi/csi/src/main.rs

@@ -13,7 +13,7 @@ use esp_alloc as _;
 use esp_backtrace as _;
 use esp_hal::{clock::CpuClock, main, rng::Rng, time, timer::timg::TimerGroup};
 use esp_println::println;
-use esp_radio::wifi::{ClientConfiguration, Configuration, CsiConfig};
+use esp_radio::wifi::{ClientConfiguration, Configuration, CsiConfig, ScanConfig};
 use smoltcp::{
     iface::{SocketSet, SocketStorage},
     wire::DhcpOption,
@@ -84,7 +84,8 @@ fn main() -> ! {
 
     println!("Waiting for CSI data...");
     println!("Start Wifi Scan");
-    let res = controller.scan_n(10).unwrap();
+    let scan_config = ScanConfig::default().with_max(10);
+    let res = controller.scan_with_config_sync(scan_config).unwrap();
     for ap in res {
         println!("{:?}", ap);
     }

examples/wifi/dhcp/src/main.rs

@@ -24,7 +24,7 @@ use esp_hal::{
     timer::timg::TimerGroup,
 };
 use esp_println::{print, println};
-use esp_radio::wifi::{ClientConfiguration, Configuration};
+use esp_radio::wifi::{ClientConfiguration, Configuration, ScanConfig};
 use smoltcp::{
     iface::{SocketSet, SocketStorage},
     wire::{DhcpOption, IpAddress},
@@ -84,7 +84,8 @@ fn main() -> ! {
     println!("is wifi started: {:?}", controller.is_started());
 
     println!("Start Wifi Scan");
-    let res = controller.scan_n(10).unwrap();
+    let scan_config = ScanConfig::default().with_max(10);
+    let res = controller.scan_with_config_sync(scan_config).unwrap();
     for ap in res {
         println!("{:?}", ap);
     }

examples/wifi/embassy_dhcp/src/main.rs

@@ -22,7 +22,15 @@ use esp_hal::{clock::CpuClock, rng::Rng, timer::timg::TimerGroup};
 use esp_println::println;
 use esp_radio::{
     Controller,
-    wifi::{ClientConfiguration, Configuration, WifiController, WifiDevice, WifiEvent, WifiState},
+    wifi::{
+        ClientConfiguration,
+        Configuration,
+        ScanConfig,
+        WifiController,
+        WifiDevice,
+        WifiEvent,
+        WifiState,
+    },
 };
 
 esp_bootloader_esp_idf::esp_app_desc!();
@@ -170,7 +178,11 @@ async fn connection(mut controller: WifiController<'static>) {
             println!("Wifi started!");
 
             println!("Scan");
-            let result = controller.scan_n_async(10).await.unwrap();
+            let scan_config = ScanConfig::default().with_max(10);
+            let result = controller
+                .scan_with_config_async(scan_config)
+                .await
+                .unwrap();
             for ap in result {
                 println!("{:?}", ap);
             }

examples/wifi/static_ip/src/main.rs

@@ -21,7 +21,7 @@ use esp_hal::{
     timer::timg::TimerGroup,
 };
 use esp_println::{print, println};
-use esp_radio::wifi::{ClientConfiguration, Configuration};
+use esp_radio::wifi::{ClientConfiguration, Configuration, ScanConfig};
 use smoltcp::iface::{SocketSet, SocketStorage};
 
 esp_bootloader_esp_idf::esp_app_desc!();
@@ -73,7 +73,8 @@ fn main() -> ! {
     println!("is wifi started: {:?}", controller.is_started());
 
     println!("Start Wifi Scan");
-    let res = controller.scan_n(10).unwrap();
+    let scan_config = ScanConfig::default().with_max(10);
+    let res = controller.scan_with_config_sync(scan_config).unwrap();
     for ap in res {
         println!("{:?}", ap);
     }