Crate esp_radio 

Wireless support for Espressif ESP32 devices.

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.

You will also need a dynamic memory allocator, and a preemptive task scheduler in your application. For the dynamic allocator, we recommend using esp-alloc. For the task scheduler, the simplest option that is supported by us is esp-rtos, but you may use Ariel OS or other operating systems as well.

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

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-radio]
opt-level = 3

Globally disable logging

esp-radio 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.

Wi-Fi 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. In addition pay attention to these configuration keys:

• ESP_RADIO_RX_QUEUE_SIZE
• ESP_RADIO_TX_QUEUE_SIZE
• ESP_RADIO_MAX_BURST_SIZE

Feature 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 with the compat feature for dynamic allocations.

  If you opt-out, you need to provide implementations for the following functions:

  • pub extern "C" fn malloc(size: usize) -> *mut u8
  • pub extern "C" fn malloc_internal(size: usize) -> *mut u8
  • pub extern "C" fn free(ptr: *mut u8)
  • pub extern "C" fn free_internal(ptr: *mut u8)
  • pub extern "C" fn calloc(number: u32, size: usize) -> *mut u8
  • pub extern "C" fn calloc_internal(number: u32, size: usize) -> *mut u8
  • pub extern "C" fn realloc(ptr: *mut u8, new_size: usize) -> *mut u8
  • pub extern "C" fn get_free_internal_heap_size() -> usize;

  Note that the untyped nature of the allocator functions means that esp-alloc is likely the more memory efficient option.

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

Chip selection

One of the following features must be enabled to select the target chip:

• esp32
• esp32c2
• esp32c3
• esp32c6
• esp32h2
• esp32s2
• esp32s3

Wireless Feature Flags

• wifi — Enable Wi-Fi support
• wifi-eap — Enable Wi-Fi Enterprise Authentication Protocol (EAP) support
• esp-now — Enable ESP-NOW support
• sniffer — Enable sniffer mode support for Wi-Fi
• ble — Enable BLE support
• coex — Software controls Wi-Fi/Bluetooth coexistence. See ESP-IDF Programming Guide for details
• csi — Enable Wi-Fi channel state information. See ESP-IDF Programming Guide,
• ieee802154 — Enable IEEE 802.15.4. Cannot be used together with Wi-Fi.

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.

Unstable APIs

Unstable APIs are drivers and features that are not yet ready for general use. They may be incomplete, have bugs, or be subject to change without notice.

• requires-unstable — Libraries that depend on esp-radio should enable this feature to indicate their use of unstable APIs. However, they must not enable the unstable feature themselves.

  For development you can enable the unstable and the chip feature by adding esp-radio as a dev-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:

Option	Stability	Default value	Allowed values
ESP_RADIO_CONFIG_WIFI_MAX_BURST_SIZE See smoltcp’s documentation	⚠️ Unstable	3	Positive integer or 0
ESP_RADIO_CONFIG_WIFI_MTU MTU, see smoltcp’s documentation	⚠️ Unstable	1492	Positive integer
ESP_RADIO_CONFIG_DUMP_PACKETS Dump packets via an info log statement	⚠️ Unstable	false

Modules

bleunstable

Bluetooth Low Energy HCI interface

ieee802154unstable

Low-level IEEE 802.15.4 driver for the ESP32-C6 and ESP32-H2.

Structs

Controller

Controller for the ESP Radio driver.

Enums

InitializationError

Error which can be returned during init.

Functions

init

Initialize for using Wi-Fi and or BLE.

phy_calibration_data

Get calibration data.

set_phy_calibration_data

Set calibration data.

wifi_set_log_verboseunstable

Enable verbose logging within the Wi-Fi driver Does nothing unless the sys-logs feature is enabled.