Crate esp_radio 

Wireless support for Espressif ESP32 devices.

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

Usage

Importing

Enabling the unstable feature on esp-radio requires you to also enable the unstable feature on esp-hal in the final binary crate.

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.

use esp_hal::interrupt::software::SoftwareInterruptControl;
use esp_hal::ram;
use esp_hal::timer::timg::TimerGroup;

esp_alloc::heap_allocator!(#[ram(reclaimed)] size: 64 * 1024);
esp_alloc::heap_allocator!(size: 36 * 1024);

let timg0 = TimerGroup::new(peripherals.TIMG0);
let sw_interrupt = SoftwareInterruptControl::new(peripherals.SW_INTERRUPT);

// THIS IS IMPORTANT FOR WIFI AND BLE: You MUST start the scheduler
// before initializing the radio!
esp_rtos::start(timg0.timer0, sw_interrupt.software_interrupt0);

if let Ok((controller, interfaces)) = esp_radio::wifi::new(
    peripherals.WIFI,
    Default::default(),
) {}

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

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.

Running on the Second Core

BLE and Wi-Fi can also be run on the second core.

esp_radio::init is recommended to be called on the first core. The tasks created by esp-radio are pinned to the first core.

It’s also important to allocate adequate stack for the second core; in many cases 8kB is not enough, and 16kB or more may be required depending on your use case. Failing to allocate adequate stack may result in strange behaviour, such as your application silently failing at some point during execution.

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.

• print-logs-from-driver — Outputs logs from the pre-compiled Wi-Fi and BLE driver blobs at info level.

  ⚠️ This feature is considered unstable.

Chip selection

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

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

Wireless Feature Flags

• wifi — Enable Wi-Fi support.

• wifi-eap — Enable Wi-Fi Enterprise Authentication Protocol (EAP) support.

  ⚠️ This feature is considered unstable.

• esp-now — Enable ESP-NOW support.

  ⚠️ This feature is considered unstable.

• sniffer — Enable sniffer mode support for Wi-Fi.

  ⚠️ This feature is considered unstable.

• ble — Enable BLE support.

  ⚠️ This feature is considered unstable.

• coex — Software controls Wi-Fi/Bluetooth coexistence. See ESP-IDF Programming Guide for details.

  ⚠️ This feature is considered unstable.

• csi — Enable Wi-Fi channel state information. See Wi-Fi Driver.

  ⚠️ This feature is considered unstable.

Ecosystem Feature Flags

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.

• unstable — Enables APIs that are not stable and thus come with no stability guarantees. Never enable this feature in a library crate using esp-radio.

• 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 embassy-net’s documentation	⚠️ Unstable	3	Positive integer or 0
ESP_RADIO_CONFIG_WIFI_MTU MTU, see embassy-net’s documentation	⚠️ Unstable	1492	Positive integer
ESP_RADIO_CONFIG_DUMP_PACKETS Dump packets via an info log statement	⚠️ Unstable	false
ESP_RADIO_CONFIG_EVENT_CHANNEL_CAPACITY Capacity of the internal event channel	⚠️ Unstable	2	Positive integer or 0
ESP_RADIO_CONFIG_EVENT_CHANNEL_SUBSCRIBERS Max subscriber count of the internal event channel	⚠️ Unstable	2	Positive integer or 0

Modules

bleble and unstable

Bluetooth Low Energy HCI interface

esp_nowesp-now and unstable

ESP-NOW is a kind of connectionless Wi-Fi communication protocol that is defined by Espressif.

wifiwifi

Wi-Fi (Station, Access Point and Station/AP-coexistence)

Enums

CalibrationResultunstable

Result of the PHY calibration.

Functions

last_calibration_resultunstable

Get the last calibration result.

phy_calibration_dataunstable

Get calibration data.

set_phy_calibration_dataunstable

Set calibration data.

wifi_set_log_verboseunstable

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