Crate esp_wifi

Expand description

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

§Usage

§Importing

Note that this crate currently requires you to enable the unstable feature on esp-hal.

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 = ["esp32c3", "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.

§WiFi performance considerations

The default configuration is quite conservative to reduce power and memory consumption.

There are a number of settings which influence the general performance. Optimal settings are chip and applications specific. You can get inspiration from the ESP-IDF examples

Please note that the configuration keys are usually named slightly different and not all configuration keys apply.

By default the power-saving mode is PowerSaveMode::None and ESP_WIFI_PHY_ENABLE_USB is enabled by default.

In addition pay attention to these configuration keys:

ESP_WIFI_RX_QUEUE_SIZE
ESP_WIFI_TX_QUEUE_SIZE
ESP_WIFI_MAX_BURST_SIZE

§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 the following functions:
- pub extern "C" fn esp_wifi_free_internal_heap() -> usize
- pub extern "C" fn esp_wifi_allocate_from_internal_ram(size: usize) -> *mut u8
- pub extern "C" fn esp_wifi_deallocate_internal_ram(ptr: *mut u8)
sys-logs — Logs the WiFi logs from the driver at log level info (needs a nightly-compiler)
builtin-scheduler (enabled by default) — Use builtin scheduler

§Wireless Feature Flags

wifi — Enable WiFi support
esp-now — Enable esp-now support
sniffer — Enable sniffer mode support
ble — Enable BLE support
coex — Enable WiFi-BLE coexistence support
csi — Enable WiFi channel state information. See ESP-IDF Programming Guide“,

§Ecosystem Feature Flags

smoltcp — Provide implementations of smoltcp traits
serde — Implement serde Serialize / Deserialize

§Logging Feature Flags

log-04 — Enable logging output using version 0.4 of the log crate.
defmt — Enable logging output using defmt and implement defmt::Format on certain types.

§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:

Option	Stability	Default value	Allowed values
ESP_WIFI_CONFIG_RX_QUEUE_SIZE Size of the RX queue in frames	⚠️ Unstable	5	Positive integer
ESP_WIFI_CONFIG_TX_QUEUE_SIZE Size of the TX queue in frames	⚠️ Unstable	3	Positive integer
ESP_WIFI_CONFIG_STATIC_RX_BUF_NUM Max number of WiFi static RX buffers. Each buffer takes approximately 1.6KB of RAM. The static rx buffers are allocated when esp_wifi_init is called, they are not freed until esp_wifi_deinit is called. WiFi hardware use these buffers to receive all 802.11 frames. A higher number may allow higher throughput but increases memory use. If ESP_WIFI_AMPDU_RX_ENABLED is enabled, this value is recommended to set equal or bigger than ESP_WIFI_RX_BA_WIN in order to achieve better throughput and compatibility with both stations and APs.	⚠️ Unstable	10	Integer in range 0..129
ESP_WIFI_CONFIG_DYNAMIC_RX_BUF_NUM Max number of WiFi dynamic RX buffers Set the number of WiFi dynamic RX buffers, 0 means unlimited RX buffers will be allocated (provided sufficient free RAM). The size of each dynamic RX buffer depends on the size of the received data frame. For each received data frame, the WiFi driver makes a copy to an RX buffer and then delivers it to the high layer TCP/IP stack. The dynamic RX buffer is freed after the higher layer has successfully received the data frame. For some applications, WiFi data frames may be received faster than the application can process them. In these cases we may run out of memory if RX buffer number is unlimited (0). If a dynamic RX buffer limit is set, it should be at least the number of static RX buffers.	⚠️ Unstable	32	Integer in range 0..1025
ESP_WIFI_CONFIG_STATIC_TX_BUF_NUM Set the number of WiFi static TX buffers. Each buffer takes approximately 1.6KB of RAM. The static RX buffers are allocated when esp_wifi_init() is called, they are not released until esp_wifi_deinit() is called. For each transmitted data frame from the higher layer TCP/IP stack, the WiFi driver makes a copy of it in a TX buffer. For some applications especially UDP applications, the upper layer can deliver frames faster than WiFi layer can transmit. In these cases, we may run out of TX buffers.	⚠️ Unstable	0	Integer in range 0..65
ESP_WIFI_CONFIG_DYNAMIC_TX_BUF_NUM Set the number of WiFi dynamic TX buffers. The size of each dynamic TX buffer is not fixed, it depends on the size of each transmitted data frame. For each transmitted frame from the higher layer TCP/IP stack, the WiFi driver makes a copy of it in a TX buffer. For some applications, especially UDP applications, the upper layer can deliver frames faster than WiFi layer can transmit. In these cases, we may run out of TX buffers.	⚠️ Unstable	32	Integer in range 0..129
ESP_WIFI_CONFIG_AMPDU_RX_ENABLE Select this option to enable AMPDU RX feature	⚠️ Unstable	true
ESP_WIFI_CONFIG_AMPDU_TX_ENABLE Select this option to enable AMPDU TX feature	⚠️ Unstable	true
ESP_WIFI_CONFIG_AMSDU_TX_ENABLE Select this option to enable AMSDU TX feature. (If ESP_WIFI_CONFIG_CACHE_TX_BUFFER_NUM >= 2)	⚠️ Unstable	false
ESP_WIFI_CONFIG_RX_BA_WIN Set the size of WiFi Block Ack RX window. Generally a bigger value means higher throughput and better compatibility but more memory. Most of time we should NOT change the default value unless special reason, e.g. test the maximum UDP RX throughput with iperf etc. For iperf test in shieldbox, the recommended value is 9~12. If PSRAM is used and WiFi memory is preferred to allocate in PSRAM first, the default and minimum value should be 16 to achieve better throughput and compatibility with both stations and APs.	⚠️ Unstable	6	Integer in range 2..65
ESP_WIFI_CONFIG_MAX_BURST_SIZE See smoltcp’s documentation	⚠️ Unstable	1
ESP_WIFI_CONFIG_COUNTRY_CODE Country code. See ESP-IDF Programming Guide	⚠️ Unstable	CN
ESP_WIFI_CONFIG_COUNTRY_CODE_OPERATING_CLASS If not 0: Operating Class table number. See ESP-IDF Programming Guide	⚠️ Unstable	0
ESP_WIFI_CONFIG_MTU MTU, see smoltcp’s documentation	⚠️ Unstable	1492	Positive integer
ESP_WIFI_CONFIG_TICK_RATE_HZ Tick rate of the internal task scheduler in hertz	⚠️ Unstable	100	Positive integer
ESP_WIFI_CONFIG_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	⚠️ Unstable	3
ESP_WIFI_CONFIG_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	⚠️ Unstable	6	Integer in range 6..31
ESP_WIFI_CONFIG_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	⚠️ Unstable	300
ESP_WIFI_CONFIG_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	⚠️ Unstable	1	Positive integer
ESP_WIFI_CONFIG_SCAN_METHOD 0 = WIFI_FAST_SCAN, 1 = WIFI_ALL_CHANNEL_SCAN, defaults to 0	⚠️ Unstable	0	Integer in range 0..2
ESP_WIFI_CONFIG_DUMP_PACKETS Dump packets via an info log statement	⚠️ Unstable	false
ESP_WIFI_CONFIG_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.	⚠️ Unstable	true
ESP_WIFI_CONFIG_PHY_SKIP_CALIBRATION_AFTER_DEEP_SLEEP Use PHY_RF_CAL_NONE after deep sleep.	⚠️ Unstable	false
ESP_WIFI_CONFIG_PHY_FULL_CALIBRATION Use PHY_RF_CAL_FULL instead of PHY_RF_CAL_PARTIAL.	⚠️ Unstable	true

Modules§

ble: Bluetooth Low Energy HCI interface
config
esp_now: ESP-NOW is a kind of connectionless Wi-Fi communication protocol that is defined by Espressif.
preempt: This module allows hooking esp-wifi into an external scheduler, instead of using the integrated one as provided by the preempt module.
wifi: WiFi

Macros§

scheduler_impl: Set the Scheduler implementation.

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§

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.

Crate esp_wifiCopy item path