Crate esp_hal_embassy

Embassy support for esp-hal.

Embassy is a modern asynchronous framework intended for use with embedded systems. This package provides support for building applications using Embassy with esp-hal.

Note that this crate currently requires you to enable the unstable feature on esp-hal.

Executors

Two types of executors are provided:

• Executor: A thread-mode executor
• InterruptExecutor: An interrupt-mode executor

InterruptExecutor can be used to achieve preemptive multitasking in asynchronous applications, which is typically something reserved for more traditional RTOS. More information can be found in the Embassy documentation.

Initialization

Embassy must be initialized by calling the init function. This initialization must be performed prior to spawning any tasks.

Initialization requires a number of timers to be passed in. The number of timers required depends on the timer queue flavour used, as well as the number of executors started. If you use the multiple-integrated timer queue flavour, then you need to pass as many timers as you start executors. In other cases, you can pass a single timer.

Configuration

You can configure the behaviour of the embassy runtime by using the following environment variables:

Option	Stability	Default value	Allowed values
ESP_HAL_EMBASSY_CONFIG_LOW_POWER_WAIT Enables the lower-power wait if no tasks are ready to run on the thread-mode executor. This allows the MCU to use less power if the workload allows. Recommended for battery-powered systems. May impact analog performance.	⚠️ Unstable	true
ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE The flavour of the timer queue provided by this crate. Integrated queues require the executors feature to be enabled. If you use embassy-executor, the single-integrated queue is recommended for ease of use, while the multiple-integrated queue is recommended for performance. The multiple-integrated option needs one timer per executor. The generic queue allows using embassy-time without the embassy executors.	⚠️ Unstable	single-integrated	One of: generic single-integrated multiple-integrated
ESP_HAL_EMBASSY_CONFIG_GENERIC_QUEUE_SIZE The capacity of the queue when the generic timer queue flavour is selected.	⚠️ Unstable	64	Positive integer

Feature Flags

• executors (enabled by default) — Enable the Executor and InterruptExecutor embassy executor implementations.

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.

Structs

Executor

Thread mode executor.

InterruptExecutor

Interrupt mode executor.

Traits

Callbacks

Callbacks to run code before/after polling the task queue.

TimeBase

A timer or collection on timers that can be passed to init.

Functions

init

Initialize embassy.

Attribute Macros

main

Creates a new executor instance and declares an application entry point spawning the corresponding function body as an async task.