Async & blocking adaptors for the Wifi driver (supersedes esp-rs#240) (esp-rs#243)

* Added async Wifi implementation with stubs

The stubs just block on the sync variants of the functions, and return a 'ready' future.
In a later iteration, the async functions that block can be replaced with proper futures.
Also added an example of using the async Wifi.

Feedback and comments welcome!

* Add the new wifi_async example to list of examples in Cargo.toml

* Revert mistaken reformatting of Cargo.toml

* Attempt to address review comments

* Refactored to address my misunderstandings from previous review comments.

The implementation of asynch::Wifi is still dependent on "experimental"
feature, because embedded-svc only exports the trait with "experimental".

`get_configuration`, `set_configuration`, `get_capabilities`, `is_started`,
and `is_connected` methds are not async in AsyncWifiDriver, because I don't
think it make sense since they return immediately on the ESP32 platform.
However, they still have async wrappers in the `asynch::Wifi`
implementation to fulfill that trait.

* Cleanups in async methods. Removal of some nightly feature requirements.

* Fixup

* Added initial async implementation of Wifi start and stop.

Not tested.

* Added true async implementations for stop, connect and disconnect

* Make examples buildable (incl with CI)

* Fix the HTTP request example

* Blocking and async wrappers for the Wifi driver

* Wait for connect with a timeout

* Use debug! as we are much more noiser now

* Generalize Wait / AsyncWait in eventloop; NetifStatus trait

---------

Co-authored-by: Erland Lewin <[email protected]>

Author: ivmarkov

.cargo/config.toml

@@ -0,0 +1,22 @@
+[target.xtensa-esp32-espidf]
+linker = "ldproxy"
+
+[target.xtensa-esp32s2-espidf]
+linker = "ldproxy"
+
+[target.xtensa-esp32s3-espidf]
+linker = "ldproxy"
+
+[target.riscv32imc-esp-espidf]
+linker = "ldproxy"
+
+# Future - necessary for the experimental "native build" of esp-idf-sys with ESP32C3
+# See also https://github.com/ivmarkov/embuild/issues/16
+rustflags = ["-C", "default-linker-libraries"]
+
+[env]
+ESP_IDF_SDKCONFIG_DEFAULTS = ".github/configs/sdkconfig.defaults"
+
+[unstable]
+build-std = ["std", "panic_abort"]
+build-std-features = ["panic_immediate_abort"]

.github/configs/sdkconfig.defaults

@@ -1,3 +1,6 @@
 # Workaround for https://github.com/espressif/esp-idf/issues/7631
 CONFIG_MBEDTLS_CERTIFICATE_BUNDLE=n
 CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_FULL=n
+
+# Examples often require a larger than the default stack size for the main thread.
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=10000

.github/workflows/ci.yml

@@ -74,3 +74,10 @@ jobs:
           ESP_IDF_SDKCONFIG_DEFAULTS: $(pwd)/.github/configs/sdkconfig.defaults
           RUSTFLAGS: "${{ matrix.idf-version == 'release/v5.0' && '--cfg espidf_time64' || ''}}"
         run: cargo build --no-default-features --features nightly,experimental,alloc --target ${{ matrix.target }} -Zbuild-std=std,panic_abort -Zbuild-std-features=panic_immediate_abort
+
+      - name: Build | Examples
+        env:
+          ESP_IDF_VERSION: ${{ matrix.idf-version }}
+          ESP_IDF_SDKCONFIG_DEFAULTS: $(pwd)/.github/configs/sdkconfig.defaults
+          RUSTFLAGS: "${{ matrix.idf-version == 'release/v5.0' && '--cfg espidf_time64' || ''}} ${{ matrix.target == 'riscv32imc-esp-espidf' && '-C default-linker-libraries' || ''}}"
+        run: cargo build --examples --target ${{ matrix.target }} -Zbuild-std=std,panic_abort -Zbuild-std-features=panic_immediate_abort

Cargo.toml

@@ -37,11 +37,25 @@ esp-idf-sys = { version = "0.32.1", default-features = false, features = ["nativ
 esp-idf-hal = { version = "0.40", default-features = false, features = ["esp-idf-sys"] }
 embassy-sync = { version = "0.1", optional = true }
 embassy-time = { version = "0.1", optional = true, features = ["tick-hz-1_000_000"] }
+embassy-futures = "0.1"
 
 [build-dependencies]
 embuild = "0.31"
 anyhow = "1"
 
+[dev-dependencies]
+anyhow = "1"
+esp-idf-sys = { version = "0.32", features = ["native", "binstart"] }
+futures = "0.3"
+
 [[example]]
 name = "http_request"
 required-features = ["experimental"]
+
+[[example]]
+name = "wifi"
+required-features = ["experimental"]
+
+[[example]]
+name = "wifi_async"
+required-features = ["experimental"]

build.rs

@@ -1,3 +1,11 @@
 fn main() -> anyhow::Result<()> {
-    embuild::build::CfgArgs::output_propagated("ESP_IDF")
+    embuild::build::CfgArgs::output_propagated("ESP_IDF")?;
+
+    // Will not be available when built with a CMake-first or a PIO-first build
+    // We need to output these only when building the examples' binaries anyway
+    if let Ok(args) = embuild::build::LinkArgs::try_from_env("ESP_IDF") {
+        args.output();
+    }
+
+    Ok(())
 }

examples/http_request.rs

@@ -4,18 +4,16 @@
 //! Note: Requires `experimental` cargo feature to be enabled
 
 use embedded_svc::{
-    http::{client::Client as HttpClient, Method, Status},
+    http::{client::Client as HttpClient, Method},
     io::Write,
     utils::io,
 };
-use esp_idf_svc::http::client::{Configuration as HttpConfiguration, EspHttpConnection};
+use esp_idf_svc::http::client::EspHttpConnection;
+use esp_idf_sys::{self as _}; // If using the `binstart` feature of `esp-idf-sys`, always keep this module imported
 
 fn main() -> anyhow::Result<()> {
     // Create HTTP(S) client
-    let mut client = HttpClient::wrap(EspHttpConnection::new(&HttpConfiguration {
-        crt_bundle_attach: Some(esp_idf_sys::esp_crt_bundle_attach), // Needed for HTTPS support
-        ..Default::default()
-    })?);
+    let mut client = HttpClient::wrap(EspHttpConnection::new(&Default::default())?);
 
     // GET
     get_request(&mut client)?;

examples/wifi.rs

@@ -0,0 +1,65 @@
+//! Example of using async wifi.
+//!
+//! Add your own ssid and password
+//!
+//! Note: Requires `nightly` and `experimental` cargo feature to be enabled
+
+use embedded_svc::wifi::{AuthMethod, ClientConfiguration, Configuration};
+use esp_idf_hal::prelude::Peripherals;
+use esp_idf_svc::log::EspLogger;
+use esp_idf_svc::wifi::{BlockingWifi, EspWifi};
+use esp_idf_svc::{eventloop::EspSystemEventLoop, nvs::EspDefaultNvsPartition};
+use esp_idf_sys::{self as _}; // If using the `binstart` feature of `esp-idf-sys`, always keep this module imported
+use futures::executor::block_on;
+use log::info;
+
+const SSID: &'static str = env!("WIFI_SSID");
+const PASSWORD: &'static str = env!("WIFI_PASS");
+
+fn main() -> anyhow::Result<()> {
+    EspLogger::initialize_default();
+
+    let peripherals = Peripherals::take().unwrap();
+    let sys_loop = EspSystemEventLoop::take()?;
+    let nvs = EspDefaultNvsPartition::take()?;
+
+    let mut wifi = BlockingWifi::wrap(
+        EspWifi::new(peripherals.modem, sys_loop.clone(), Some(nvs))?,
+        sys_loop,
+    )?;
+
+    block_on(connect_wifi(&mut wifi))?;
+
+    let ip_info = wifi.wifi().sta_netif().get_ip_info()?;
+
+    info!("Wifi DHCP info: {:?}", ip_info);
+
+    info!("Shutting down in 5s...");
+
+    std::thread::sleep(core::time::Duration::from_secs(5));
+
+    Ok(())
+}
+
+async fn connect_wifi(wifi: &mut BlockingWifi<EspWifi<'static>>) -> anyhow::Result<()> {
+    let wifi_configuration: Configuration = Configuration::Client(ClientConfiguration {
+        ssid: SSID.into(),
+        bssid: None,
+        auth_method: AuthMethod::WPA2Personal,
+        password: PASSWORD.into(),
+        channel: None,
+    });
+
+    wifi.set_configuration(&wifi_configuration)?;
+
+    wifi.start()?;
+    info!("Wifi started");
+
+    wifi.connect()?;
+    info!("Wifi connected");
+
+    wifi.wait_netif_up()?;
+    info!("Wifi netif up");
+
+    Ok(())
+}

examples/wifi_async.rs

@@ -0,0 +1,68 @@
+//! Example of using async wifi.
+//!
+//! Add your own ssid and password
+//!
+//! Note: Requires `nightly` and `experimental` cargo feature to be enabled
+
+use embedded_svc::wifi::{AuthMethod, ClientConfiguration, Configuration};
+use esp_idf_hal::prelude::Peripherals;
+use esp_idf_svc::log::EspLogger;
+use esp_idf_svc::timer::EspTaskTimerService;
+use esp_idf_svc::wifi::{AsyncWifi, EspWifi};
+use esp_idf_svc::{eventloop::EspSystemEventLoop, nvs::EspDefaultNvsPartition};
+use esp_idf_sys::{self as _}; // If using the `binstart` feature of `esp-idf-sys`, always keep this module imported
+use futures::executor::block_on;
+use log::info;
+
+const SSID: &'static str = env!("WIFI_SSID");
+const PASSWORD: &'static str = env!("WIFI_PASS");
+
+fn main() -> anyhow::Result<()> {
+    EspLogger::initialize_default();
+
+    let peripherals = Peripherals::take().unwrap();
+    let sys_loop = EspSystemEventLoop::take()?;
+    let timer_service = EspTaskTimerService::new()?;
+    let nvs = EspDefaultNvsPartition::take()?;
+
+    let mut wifi = AsyncWifi::wrap(
+        EspWifi::new(peripherals.modem, sys_loop.clone(), Some(nvs))?,
+        sys_loop,
+        timer_service.clone(),
+    )?;
+
+    block_on(connect_wifi(&mut wifi))?;
+
+    let ip_info = wifi.wifi().sta_netif().get_ip_info()?;
+
+    info!("Wifi DHCP info: {:?}", ip_info);
+
+    info!("Shutting down in 5s...");
+
+    std::thread::sleep(core::time::Duration::from_secs(5));
+
+    Ok(())
+}
+
+async fn connect_wifi(wifi: &mut AsyncWifi<EspWifi<'static>>) -> anyhow::Result<()> {
+    let wifi_configuration: Configuration = Configuration::Client(ClientConfiguration {
+        ssid: SSID.into(),
+        bssid: None,
+        auth_method: AuthMethod::WPA2Personal,
+        password: PASSWORD.into(),
+        channel: None,
+    });
+
+    wifi.set_configuration(&wifi_configuration)?;
+
+    wifi.start().await?;
+    info!("Wifi started");
+
+    wifi.connect().await?;
+    info!("Wifi connected");
+
+    wifi.wait_netif_up().await?;
+    info!("Wifi netif up");
+
+    Ok(())
+}