Struct WifiController 

#[non_exhaustive]
pub struct WifiController<'d> { /* private fields */ }

Available on crate feature wifi only.

Wi-Fi controller.

Calling new starts the controller.

When the controller is dropped, the Wi-Fi driver is deinitialized and Wi-Fi is stopped.

Implementations

impl WifiController<'_>

pub fn set_csi( &mut self, csi: CsiConfig, cb: impl FnMut(WifiCsiInfo<'_>) + Send, ) -> Result<(), WifiError>

Available on crate feature unstable only.

Set CSI configuration and register the receiving callback.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn set_protocols(&mut self, protocols: Protocols) -> Result<(), WifiError>

Available on crate feature unstable only.

Set the Wi-Fi protocol.

This will set the desired protocols.

Arguments:

• protocols - The desired protocols

Example:

use esp_radio::wifi::Protocols;

let controller_config = ControllerConfig::default().with_initial_config(Config::AccessPoint(
    AccessPointConfig::default().with_ssid("esp-radio"),
));
let (mut wifi_controller, _interfaces) =
    esp_radio::wifi::new(peripherals.WIFI, controller_config)?;

wifi_controller.set_protocols(Protocols::default());

Note

Calling this function before set_config will return an error.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn set_power_saving(&mut self, ps: PowerSaveMode) -> Result<(), WifiError>

Available on crate feature unstable only.

Configures modem power saving.

Example

let (mut controller, _interfaces) = esp_radio::wifi::new(peripherals.WIFI, Default::default())?;
controller.set_power_saving(PowerSaveMode::Maximum)?;

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn rssi(&self) -> Result<i32, WifiError>

Get the RSSI information of access point to which the device is associated with. The value is obtained from the last beacon.

• Use this API only in Station or AccessPoint-Station mode.
• This API should be called after the station has connected to an access point.

Example

// Assume the station has already been started and connected
match controller.rssi() {
    Ok(rssi) => {
        println!("RSSI: {} dBm", rssi);
    }
    Err(e) => {
        println!("Failed to get RSSI: {e:?}");
    }
}

Errors

This function returns WifiError::Unsupported if the Station side isn’t running. For example, when configured for access point only.

pub fn ap_info(&self) -> Result<AccessPointInfo, WifiError>

Get the Access Point information of access point to which the device is associated with. The value is obtained from the last beacon.

• Use this API only in Station or AccessPoint-Station mode.
• This API should be called after the station has connected to an access point.

Example

// Assume the station has already been started and connected
match controller.ap_info() {
    Ok(info) => {
        println!("BSSID: {}", info.bssid);
    }
    Err(e) => {
        println!("Failed to get AP info: {e:?}");
    }
}

Errors

This function returns WifiError::Unsupported if the Station side isn’t running. For example, when configured for access point only.

pub fn set_config(&mut self, conf: &Config) -> Result<(), WifiError>

Set the configuration and (re)start the controller as needed.

This will set the mode accordingly. You need to use Self::connect_async for connecting to an access point.

If you don’t intend to use Wi-Fi anymore at all consider tearing down Wi-Fi completely.

Errors

If this function returns an error, the Wi-Fi mode is reset to NULL and the controller is stopped.

Example

let station_config = Config::Station(
    StationConfig::default()
        .with_ssid("SSID")
        .with_password("PASSWORD".into()),
);

controller.set_config(&station_config)?;

pub fn set_band_mode(&mut self, band_mode: BandMode) -> Result<(), WifiError>

Available on crate feature unstable only.

Set Wi-Fi band mode.

When the Wi-Fi band mode is set to BandMode::_2_4G, it operates exclusively on the 2.4GHz channels. The controller needs to be configured and started before setting the band mode.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn set_bandwidths( &mut self, bandwidths: Bandwidths, ) -> Result<(), WifiError>

Available on crate feature unstable only.

Sets the Wi-Fi channel bandwidth for the currently active interface(s).

If the device is operating in station mode, the bandwidth is applied to the Station interface. If operating in access point mode, it is applied to the Access Point interface. In Station+Access Point mode, the bandwidth is set for both interfaces.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn bandwidths(&self) -> Result<Bandwidths, WifiError>

Available on crate feature unstable only.

Returns the Wi-Fi channel bandwidth of the active interface.

If the device is operating in station mode, the bandwidth of the Station interface is returned. If operating in access point mode, the bandwidth of the Access Point interface is returned. In Station+Access Point mode, the bandwidth of the Access Point interface is returned.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn channel(&self) -> Result<(u8, SecondaryChannel), WifiError>

Available on crate feature unstable only.

Returns the current Wi-Fi channel configuration.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn set_channel( &mut self, primary: u8, secondary: SecondaryChannel, ) -> Result<(), WifiError>

Available on crate feature unstable only.

Sets the primary and secondary Wi-Fi channel.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn set_max_tx_power(&mut self, power: i8) -> Result<(), WifiError>

Available on crate feature unstable only.

Set maximum transmitting power after WiFi start.

Power unit is 0.25dBm, range is [8, 84] corresponding to 2dBm - 20dBm.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn is_connected(&self) -> bool

Available on crate feature unstable only.

Checks if the Wi-Fi controller is currently connected to an access point.

Example

if controller.is_connected() {
    println!("Station is connected");
} else {
    println!("Station is not connected yet");
}

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub async fn scan_async( &mut self, config: &ScanConfig, ) -> Result<Vec<AccessPointInfo>, WifiError>

An async Wi-Fi network scan with caller-provided scanning options.

Scanning is not supported in AcessPoint-only mode.

Example

// Create a scan configuration (e.g., scan up to 10 APs)
let scan_config = ScanConfig::default().with_max(10);
let result = controller
    .scan_async(&scan_config)
    .await
    .unwrap();
for ap in result {
    println!("{:?}", ap);
}

pub async fn connect_async(&mut self) -> Result<ConnectedStationInfo, WifiError>

Connect Wi-Fi station to the AP.

Use Self::disconnect_async to disconnect.

Calling Self::scan_async will not be effective until connection between device and the AP is established.

If device is scanning and connecting at the same time, it will abort scanning and return a warning message and error.

Example

match controller.connect_async().await {
    Ok(_) => {
        println!("Wifi connected!");
    }
    Err(e) => {
      println!("Failed to connect to wifi: {e:?}");
    }
}

pub async fn disconnect_async( &mut self, ) -> Result<DisconnectedStationInfo, WifiError>

Disconnect Wi-Fi station from the AP.

This function will wait for the connection to be closed before returning.

Example

match controller.disconnect_async().await {
    Ok(info) => {
        println!("Station disconnected successfully. {info:?}");
    }
    Err(e) => {
        println!("Failed to disconnect: {e:?}");
    }
}

pub async fn wait_for_disconnect_async( &self, ) -> Result<DisconnectedStationInfo, WifiError>

Wait until the station gets disconnected from the AP.

pub async fn wait_for_access_point_connected_event_async( &self, ) -> Result<AccessPointStationEventInfo, WifiError>

Wait for connected / disconnected events.

pub fn subscribe<'a>(&'a self) -> Result<EventSubscriber<'a>, WifiError>

Available on crate feature unstable only.

Subscribe to events.

Errors

This returns WifiError::Failed if no more subscriptions are available. Consider increasing the internal event channel subscriber count in this case.

Stability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Trait Implementations

impl<'d> Debug for WifiController<'d>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for WifiController<'_>

fn drop(&mut self)

Executes the destructor for this type.

impl<'d> Format for WifiController<'d>

where RadioRefGuard: Format, PhantomData<&'d ()>: Format,

fn format(&self, f: Formatter<'_>)

Writes the defmt representation of self to fmt.