Crate esp_wifi

Source
Expand description

This documentation is built for the ESP32-H2 . 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 = ["esp32h2", "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:

NameDescriptionDefault valueAllowed value

ESP_WIFI_CONFIG_RX_QUEUE_SIZE

⚠️ Unstable

Size of the RX queue in frames

5
Positive integer

ESP_WIFI_CONFIG_TX_QUEUE_SIZE

⚠️ Unstable

Size of the TX queue in frames

3
Positive integer

ESP_WIFI_CONFIG_STATIC_RX_BUF_NUM

⚠️ Unstable

WiFi static RX buffer number. See ESP-IDF Programming Guide

10
Positive integer

ESP_WIFI_CONFIG_DYNAMIC_RX_BUF_NUM

⚠️ Unstable

WiFi dynamic RX buffer number. See ESP-IDF Programming Guide

32
Positive integer

ESP_WIFI_CONFIG_STATIC_TX_BUF_NUM

⚠️ Unstable

WiFi static TX buffer number. See ESP-IDF Programming Guide

0

ESP_WIFI_CONFIG_DYNAMIC_TX_BUF_NUM

⚠️ Unstable

WiFi dynamic TX buffer number. See ESP-IDF Programming Guide

32

ESP_WIFI_CONFIG_AMPDU_RX_ENABLE

⚠️ Unstable

WiFi AMPDU RX feature enable flag. See ESP-IDF Programming Guide

true

ESP_WIFI_CONFIG_AMPDU_TX_ENABLE

⚠️ Unstable

WiFi AMPDU TX feature enable flag. See ESP-IDF Programming Guide

true

ESP_WIFI_CONFIG_AMSDU_TX_ENABLE

⚠️ Unstable

WiFi AMSDU TX feature enable flag. See ESP-IDF Programming Guide

false

ESP_WIFI_CONFIG_RX_BA_WIN

⚠️ Unstable

WiFi Block Ack RX window size. See ESP-IDF Programming Guide

6

ESP_WIFI_CONFIG_MAX_BURST_SIZE

⚠️ Unstable

See smoltcp’s documentation

1

ESP_WIFI_CONFIG_COUNTRY_CODE

⚠️ Unstable

Country code. See ESP-IDF Programming Guide

CN

ESP_WIFI_CONFIG_COUNTRY_CODE_OPERATING_CLASS

⚠️ Unstable

If not 0: Operating Class table number. See ESP-IDF Programming Guide

0

ESP_WIFI_CONFIG_MTU

⚠️ Unstable

MTU, see smoltcp’s documentation

1492
Positive integer

ESP_WIFI_CONFIG_TICK_RATE_HZ

⚠️ Unstable

Tick rate of the internal task scheduler in hertz

100
Positive integer

ESP_WIFI_CONFIG_LISTEN_INTERVAL

⚠️ Unstable

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_CONFIG_BEACON_TIMEOUT

⚠️ Unstable

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
Integer in range 6..30

ESP_WIFI_CONFIG_AP_BEACON_TIMEOUT

⚠️ Unstable

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_CONFIG_FAILURE_RETRY_CNT

⚠️ Unstable

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
Positive integer

ESP_WIFI_CONFIG_SCAN_METHOD

⚠️ Unstable

0 = WIFI_FAST_SCAN, 1 = WIFI_ALL_CHANNEL_SCAN, defaults to 0

0
Integer in range 0..2

ESP_WIFI_CONFIG_DUMP_PACKETS

⚠️ Unstable

Dump packets via an info log statement

false

ESP_WIFI_CONFIG_PHY_ENABLE_USB

⚠️ Unstable

Keeps USB running when using WiFi.

This allows debugging and log messages via USB Serial JTAG.
Turn off for best WiFi performance.

true

ESP_WIFI_CONFIG_PHY_SKIP_CALIBRATION_AFTER_DEEP_SLEEP

⚠️ Unstable

Use PHY_RF_CAL_NONE after deep sleep.

false

ESP_WIFI_CONFIG_PHY_FULL_CALIBRATION

⚠️ Unstable

Use PHY_RF_CAL_FULL instead of PHY_RF_CAL_PARTIAL.

true

Modules§

ble
Bluetooth Low Energy HCI interface
config
preempt
This module allows hooking esp-wifi into an external scheduler, instead of using the integrated one as provided by the preempt module.

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§

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.