From a7673b35f7486222d2a1650e48cd09333c313458 Mon Sep 17 00:00:00 2001 From: Jesse Braham Date: Wed, 20 Aug 2025 06:22:26 -0700 Subject: [PATCH] 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 | 4 +-- esp-hal-procmacros/src/builder.rs | 3 +- esp-radio/CHANGELOG.md | 2 ++ esp-radio/Cargo.toml | 1 + esp-radio/MIGRATING-0.15.0.md | 8 +++-- esp-radio/src/wifi/mod.rs | 43 ++++++-------------------- examples/wifi/bench/src/main.rs | 5 +-- examples/wifi/csi/src/main.rs | 5 +-- examples/wifi/dhcp/src/main.rs | 5 +-- examples/wifi/embassy_dhcp/src/main.rs | 16 ++++++++-- examples/wifi/static_ip/src/main.rs | 5 +-- 11 files changed, 47 insertions(+), 50 deletions(-) diff --git a/esp-hal-procmacros/CHANGELOG.md b/esp-hal-procmacros/CHANGELOG.md index a78b77234..df289ea86 100644 --- a/esp-hal-procmacros/CHANGELOG.md +++ b/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 diff --git a/esp-hal-procmacros/src/builder.rs b/esp-hal-procmacros/src/builder.rs index bb79382c3..58c45bf67 100644 --- a/esp-hal-procmacros/src/builder.rs +++ b/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)* } }; diff --git a/esp-radio/CHANGELOG.md b/esp-radio/CHANGELOG.md index 652562eec..f499dffe9 100644 --- a/esp-radio/CHANGELOG.md +++ b/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 diff --git a/esp-radio/Cargo.toml b/esp-radio/Cargo.toml index 4645f134d..1683831b9 100644 --- a/esp-radio/Cargo.toml +++ b/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 } diff --git a/esp-radio/MIGRATING-0.15.0.md b/esp-radio/MIGRATING-0.15.0.md index 88b3031a8..be28995f7 100644 --- a/esp-radio/MIGRATING-0.15.0.md +++ b/esp-radio/MIGRATING-0.15.0.md @@ -19,10 +19,10 @@ Furthermore, `esp_wifi::init` no longer requires `RNG` or a timer. `esp_wifi` crate has been renamed to `esp_radio` -```diff +```diff - esp-wifi = "0.15.0" + esp-radio = "{{currentVersion}}" -``` +``` ## `EspWifi` prefix has been removed @@ -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`. diff --git a/esp-radio/src/wifi/mod.rs b/esp-radio/src/wifi/mod.rs index c37d62c6b..ed5441525 100644 --- a/esp-radio/src/wifi/mod.rs +++ b/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, } 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, WifiError> { - self.scan_with_config_sync_max(config, usize::MAX) - } - - pub fn scan_with_config_sync_max( - &mut self, - config: ScanConfig<'_>, - max: usize, ) -> Result, WifiError> { esp_wifi_result!(crate::wifi::wifi_start_scan(true, config))?; - let result = self.scan_results(max)?; - Ok(result) + self.scan_results(config.max.unwrap_or(usize::MAX)) } fn scan_results(&mut self, max: usize) -> Result, 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, 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, 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, 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, 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) } diff --git a/examples/wifi/bench/src/main.rs b/examples/wifi/bench/src/main.rs index 3d4d2b457..ac7f2a7fb 100644 --- a/examples/wifi/bench/src/main.rs +++ b/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); } diff --git a/examples/wifi/csi/src/main.rs b/examples/wifi/csi/src/main.rs index 3171c0c28..84375901f 100644 --- a/examples/wifi/csi/src/main.rs +++ b/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); } diff --git a/examples/wifi/dhcp/src/main.rs b/examples/wifi/dhcp/src/main.rs index c05398b54..02bb61bfa 100644 --- a/examples/wifi/dhcp/src/main.rs +++ b/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); } diff --git a/examples/wifi/embassy_dhcp/src/main.rs b/examples/wifi/embassy_dhcp/src/main.rs index dc58f059f..4e9fb151b 100644 --- a/examples/wifi/embassy_dhcp/src/main.rs +++ b/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); } diff --git a/examples/wifi/static_ip/src/main.rs b/examples/wifi/static_ip/src/main.rs index adf0f704c..b293899ad 100644 --- a/examples/wifi/static_ip/src/main.rs +++ b/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); }