Feature flags of esp-hal crate // Lib.rs

Cargo Features

[dependencies]
esp-hal = { version = "1.1.1", default-features = false, features = ["rt", "exception-handler", "float-save-restore", "esp32", "esp32c2", "esp32c3", "esp32c5", "esp32c6", "esp32c61", "esp32h2", "esp32s2", "esp32s3", "log-04", "defmt", "unstable", "requires-unstable"] }

default = exception-handler, float-save-restore, rt

These default features are set whenever esp-hal is added without default-features = false somewhere in the dependency tree.

rt default = critical-section

Runtime support

These features are meant to be enabled by firmware projects. If you are writing a library that depends on esp-hal, you should not enable these features under any circumstance.

Enable code necessary to run the firmware.

Enables esp-riscv-rt, optional esp32, optional esp32c2, optional esp32c3, optional esp32c6, optional esp32h2, optional esp32s2, optional esp32s3, and xtensa-lx-rt

esp32:
IMPORTANT:
Each supported device MUST have its PAC included below along with a corresponding feature.

Affects esp-hal::trapframe, esp-hal::init…

exception-handler default

Enable a simple exception handler turning exceptions into panics.

float-save-restore default

Save and restore the floating point co-processor context.

This feature enables the floating-point coprocessor in interrupt contexts, and adds code to save and restore the relevant registers.
If you intend to do floating-point calculations in multiple contexts, or in interrupt/exception handlers, you will need to enable this feature.
Note that this feature is only effective on ESP32 and ESP32-S3. Other chips don't have a hardware floating-point coprocessor.

⚠️ This feature is considered unstable.

Enables float-save-restore of xtensa-lx-rt

esp32

Chip selection

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

Enables esp32, rtc-fast and rtc-slow of esp-hal-procmacros, esp32 of esp-metadata-generated, esp-rom-sys, and esp-sync and sha1 ^0.10 and sha2 ^0.10

sha1:
ESP32-only fallback SHA algorithms

esp32c2

Enables esp32c2, esp32c2 of esp-metadata-generated, unsafe-assume-single-core of portable-atomic, esp32c2 of esp-rom-sys and esp-sync and no-mie-mip of esp-riscv-rt

esp-riscv-rt:
Indicate that the device does NOT support mie and mip CSRs.

esp32c3

Enables esp32c3, esp32c3 of esp-metadata-generated, no-mie-mip and rtc-ram of esp-riscv-rt, unsafe-assume-single-core of portable-atomic, rtc-fast of esp-hal-procmacros and esp32c3 of esp-rom-sys and esp-sync

esp-sync:
Target the ESP32-C3.

esp32c5

Enables esp32c5, esp32c5 of esp-metadata-generated, clic-48 and rtc-ram of esp-riscv-rt, has-lp-core and rtc-fast of esp-hal-procmacros and esp32c5 of esp-rom-sys and esp-sync

esp-sync:
Target the ESP32-C5.

esp32c6

Enables esp32c6, esp32c6 of esp-metadata-generated, rtc-ram of esp-riscv-rt, has-lp-core and rtc-fast of esp-hal-procmacros and esp32c6 of esp-rom-sys and esp-sync

esp-sync:
Target the ESP32-C6.

esp32c61

Enables esp32c61, esp32c61 of esp-metadata-generated, has-lp-core of esp-hal-procmacros, esp32c61 of esp-rom-sys and esp-sync and clic-48 of esp-riscv-rt

esp-riscv-rt:
CLIC with 48 total interrupt lines

esp32h2

Enables esp32h2, esp32h2 of esp-metadata-generated, rtc-fast of esp-hal-procmacros, esp32h2 of esp-rom-sys and esp-sync and rtc-ram of esp-riscv-rt

esp-riscv-rt:
Indicate that the device has RTC RAM.

esp32s2

Enables esp32s2, embassy-usb-driver and embassy-usb-synopsys-otg ^0.3, esp32sx and fs of esp-synopsys-usb-otg, unsafe-assume-single-core of portable-atomic, has-ulp-core, rtc-fast and rtc-slow of esp-hal-procmacros and esp32s2 of esp-metadata-generated, esp-rom-sys, and esp-sync

esp-sync:
Target the ESP32-S2.

esp32s3

Enables esp32s3, embassy-usb-driver and embassy-usb-synopsys-otg ^0.3, esp32sx and fs of esp-synopsys-usb-otg, has-ulp-core, rtc-fast and rtc-slow of esp-hal-procmacros and esp32s3 of esp-metadata-generated, esp-rom-sys, and esp-sync

esp-sync:
Target the ESP32-S3.

log-04

Logging Feature Flags

Enable logging output using version 0.4 of the log crate.

Enables log

defmt

Enable logging output using defmt and implement defmt::Format on certain types.

Enables defmt of embassy-futures and embassy-sync, defmt-03 of optional embedded-io ^0.6, defmt of optional embedded-io, defmt-03 of optional embedded-io-async ^0.6, defmt of enumset, esp-sync, fugit ^0.3.7, optional embedded-io-async, optional esp-riscv-rt, optional esp32, optional esp32c2, optional esp32c3, optional esp32c5, optional esp32c6, optional esp32c61, optional esp32h2, optional esp32s2, optional esp32s3, and optional xtensa-lx-rt and defmt

Logging interfaces, they are mutually exclusive so they need to be behind separate features.

unstable

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 APIs are not covered by semver guarantees.

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

Enables digest ^0.10.7

Dependencies that are optional because they are used by unstable drivers. They are needed when using the unstable feature.

and embassy-embedded-hal, embedded-can, embedded-io ^0.6, embedded-io, embedded-io-async ^0.6, embedded-io-async, nb, rand_core, rand_core ^0.6, rand_core ^0.9, and ufmt-write

embassy-embedded-hal:
Optional dependencies that enable ecosystem support. We could support individually enabling them, but there is no big downside to just enabling them all via the unstable feature.

Affects adc::AdcConfig, adc::CalibrationAccess, esp32::cpu_control, esp32s3::cpu_control…

requires-unstable

Libraries that depend on esp-hal 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-hal as a dev-dependency.

Features from optional dependencies

In crates that don't use the dep: syntax, optional dependencies automatically become Cargo features. These features may have been created by mistake, and this functionality may be removed in the future.

critical-section rt