Crate esp_wifi

This documentation is built for the ESP32-C3 . Please ensure you are reading the correct documentation for your target device.

Usage

Importing

Ensure that the right features are enabled for your chip. See Examples for more examples.

[dependencies.esp-wifi]
# A supported chip needs to be specified, as well as specific use-case features
features = ["esp32s3", "wifi", "esp-now"]

Optimization Level

It is necessary to build with optimization level 2 or 3 since otherwise, it might not even be able to connect or advertise.

To make it work also for your debug builds add this to your Cargo.toml

[profile.dev.package.esp-wifi]
opt-level = 3

Globally disable logging

esp-wifi contains a lot of trace-level logging statements. For maximum performance you might want to disable logging via a feature flag of the log crate. See documentation. You should set it to release_max_level_off.

Xtensa considerations

Within this crate, CCOMPARE0 CPU timer is used for timing, ensure that in your application you are not using this CPU timer.

Features flags

Note that not all features are available on every MCU. For example, ble (and thus, coex) is not available on ESP32-S2.

When using the dump_packets config you can use the extcap in extras/esp-wifishark to analyze the frames in Wireshark. For more information see extras/esp-wifishark/README.md

• esp-alloc (enabled by default) — Use esp-alloc for dynamic allocations.

  If you opt-out you need to provide implementations for pub extern "C" fn esp_wifi_free_internal_heap() -> usize and pub extern "C" fn esp_wifi_allocate_from_internal_ram(size: usize) -> *mut u8

• coex — Enable WiFi-BLE coexistence support

• sys-logs — Logs the WiFi logs from the driver at log level info (needs a nightly-compiler)

• defmt — Enable support for defmt

• log — Enable support for the log crate

• wifi — Enable WiFi support

• esp-now — Enable esp-now support

• sniffer — Enable sniffer mode support

• ble — Enable BLE support

• smoltcp — Provide implementations of smoltcp traits

• utils — Provide utilities for smoltcp initialization. Adds smoltcp dependency

Additional configuration

We’ve exposed some configuration options that don’t fit into cargo features. These can be set via environment variables, or via cargo’s [env] section inside .cargo/config.toml. Below is a table of tunable parameters for this crate:

Name	Description	Default value
ESP_WIFI_RX_QUEUE_SIZE	Size of the RX queue in frames	5
ESP_WIFI_TX_QUEUE_SIZE	Size of the TX queue in frames	3
ESP_WIFI_STATIC_RX_BUF_NUM	WiFi static RX buffer number. See ESP-IDF Programming Guide	10
ESP_WIFI_DYNAMIC_RX_BUF_NUM	WiFi dynamic RX buffer number. See ESP-IDF Programming Guide	32
ESP_WIFI_STATIC_TX_BUF_NUM	WiFi static TX buffer number. See ESP-IDF Programming Guide	0
ESP_WIFI_DYNAMIC_TX_BUF_NUM	WiFi dynamic TX buffer number. See ESP-IDF Programming Guide	32
ESP_WIFI_CSI_ENABLE	WiFi channel state information enable flag. See ESP-IDF Programming Guide	false
ESP_WIFI_AMPDU_RX_ENABLE	WiFi AMPDU RX feature enable flag. See ESP-IDF Programming Guide	true
ESP_WIFI_AMPDU_TX_ENABLE	WiFi AMPDU TX feature enable flag. See ESP-IDF Programming Guide	true
ESP_WIFI_AMSDU_TX_ENABLE	WiFi AMSDU TX feature enable flag. See ESP-IDF Programming Guide	false
ESP_WIFI_RX_BA_WIN	WiFi Block Ack RX window size. See ESP-IDF Programming Guide	6
ESP_WIFI_MAX_BURST_SIZE	See smoltcp’s documentation	1
ESP_WIFI_COUNTRY_CODE	Country code. See ESP-IDF Programming Guide	CN
ESP_WIFI_COUNTRY_CODE_OPERATING_CLASS	If not 0: Operating Class table number. See ESP-IDF Programming Guide	0
ESP_WIFI_MTU	MTU, see smoltcp’s documentation	1492
ESP_WIFI_TICK_RATE_HZ	Tick rate of the internal task scheduler in hertz	100
ESP_WIFI_LISTEN_INTERVAL	Interval for station to listen to beacon from AP. The unit of listen interval is one beacon interval. For example, if beacon interval is 100 ms and listen interval is 3, the interval for station to listen to beacon is 300 ms	3
ESP_WIFI_BEACON_TIMEOUT	For Station, If the station does not receive a beacon frame from the connected SoftAP during the inactive time, disconnect from SoftAP. Default 6s. Range 6-30	6
ESP_WIFI_AP_BEACON_TIMEOUT	For SoftAP, If the SoftAP doesn’t receive any data from the connected STA during inactive time, the SoftAP will force deauth the STA. Default is 300s	300
ESP_WIFI_FAILURE_RETRY_CNT	Number of connection retries station will do before moving to next AP. scan_method should be set as WIFI_ALL_CHANNEL_SCAN to use this config. Note: Enabling this may cause connection time to increase incase best AP doesn’t behave properly. Defaults to 1	1
ESP_WIFI_SCAN_METHOD	0 = WIFI_FAST_SCAN, 1 = WIFI_ALL_CHANNEL_SCAN, defaults to 0	0
ESP_WIFI_DUMP_PACKETS	Dump packets via an info log statement	false
ESP_WIFI_PHY_ENABLE_USB	Keeps USB running when using WiFi. This allows debugging and log messages via USB Serial JTAG. Turn off for best WiFi performance.	true

It’s important to note that due to a bug in cargo, any modifications to the environment, local or otherwise will only get picked up on a full clean build of the project.

Modules

• config
• esp_now
  ESP-NOW is a kind of connectionless Wi-Fi communication protocol that is defined by Espressif.
• wifi
  WiFi

Structs

• EspWifiController

Enums

• InitializationError
  Error which can be returned during init.

Traits

• EspWifiRngSource
  A marker trait for suitable Rng sources for esp-wifi
• EspWifiTimerSource
  A trait to allow better UX for initializing esp-wifi.

Functions

• deinit_unchecked^⚠
  Deinitializes the entire radio stack
• init
  Initialize for using WiFi and or BLE.
• wifi_set_log_verbose
  Enable verbose logging within the WiFi driver Does nothing unless the sys-logs feature is enabled.