Crate esp_radio 

Wireless support for Espressif ESP32 devices.

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

Overview

esp-radio provides Wi-Fi, Bluetooth Low Energy (BLE), ESP-NOW and IEEE 802.15.4 drivers for Espressif microcontrollers. It builds on top of esp-hal and the vendor binary blobs to provide wireless connectivity in a no_std environment.

Wi-Fi and BLE require a dynamic memory allocator and a preemptive task scheduler at runtime. We recommend esp-alloc and esp-rtos for this, though any allocator or RTOS (such as Ariel OS) that implements the required interfaces will work. Drivers that don’t currently have a stable API are marked as unstable in the documentation. Enabling the unstable feature on esp-radio requires you to also enable the unstable feature on esp-hal in the final binary crate.

Quick start

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) = esp_radio::wifi::WifiController::new(
    peripherals.WIFI,
    Default::default(),
) {}

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

Examples

We have a number of examples in the esp-hal repository. We use an xtask to automate the building, running, and testing of code and examples within esp-hal.

Invoke the following command in the root of the esp-hal repository to get started:

cargo xtask help

We have a book that explains the full esp-hal ecosystem and how to get started, and a training that covers some common scenarios with examples.

Optimization level

The radio blobs require optimization level 2 or 3 to function correctly. Without it, Wi-Fi may fail to connect and BLE may fail to advertise.

To apply this only to esp-radio in debug builds, add to your Cargo.toml:

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

Disabling logging

esp-radio contains trace-level logging statements that may impact performance. To disable them, use the log crate’s compile-time filters and set release_max_level_off.

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.