Crate esp_hal_embassy

Source
Expand description

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:

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:

NameDescriptionDefault valueAllowed value

ESP_HAL_EMBASSY_CONFIG_LOW_POWER_WAIT

⚠️ Unstable

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.

true

ESP_HAL_EMBASSY_CONFIG_TIMER_QUEUE

⚠️ Unstable

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.

single-integrated
One of:
  • generic
  • single-integrated
  • multiple-integrated

ESP_HAL_EMBASSY_CONFIG_GENERIC_QUEUE_SIZE

⚠️ Unstable

The capacity of the queue when the generic timer queue flavour is selected.

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§

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.