Embassy Book

The embassy-executor is an async/await executor that generally executes a fixed number of tasks, allocated at startup, though more can be added later. The executor may also provide a system timer that you can use for both async and blocking delays. For less than one microsecond, blocking delays should be used because the cost of context-switching is too high and the executor will be unable to provide accurate timing.

HALs implement safe Rust API which let you use peripherals such as USART, UART, I2C, SPI, CAN, and USB without having to directly manipulate registers.

Embassy provides implementations of both async and blocking APIs where it makes sense. DMA (Direct Memory Access) is an example where async is a good fit, whereas GPIO states are a better fit for a blocking API.

The Embassy project maintains HALs for select hardware, but you can still use HALs from other projects with Embassy.

The embassy-net network stack implements extensive networking functionality, including Ethernet, IP, TCP, UDP, ICMP and DHCP. Async drastically simplifies managing timeouts and serving multiple connections concurrently. Several drivers for WiFi and Ethernet chips can be found.

The nrf-softdevice crate provides Bluetooth Low Energy 4.x and 5.x support for nRF52 microcontrollers.

lora-rs supports LoRa networking on a wide range of LoRa radios, fully integrated with a Rust LoRaWAN implementation. It provides four crates — lora-phy, lora-modulation, lorawan-encoding, and lorawan-device — and basic examples for various development boards. It has support for STM32WL wireless microcontrollers or Semtech SX127x transceivers, among others.

embassy-usb implements a device-side USB stack. Implementations for common classes such as USB serial (CDC ACM) and USB HID are available, and a rich builder API allows building your own.

embassy-boot is a lightweight bootloader supporting firmware application upgrades in a power-fail-safe way, with trial boots and rollbacks.

Embassy supports many microcontroller families, but the quickest way to get started is by using a board which Embassy has existing example code for.

This list is non-exhaustive. If your board isn’t included here, check the examples folder to see if example code has been written for it.

First you need to clone the github repository;

Once you have a copy of the repository, find examples folder for your board and, and build an example program. blinky is a good choice as all it does is blink an LED – the embedded world’s equivalent of “Hello World”.

Once you’ve confirmed you can build the example, connect your computer to your board with a debug probe and run it on hardware:

If everything worked correctly, you should see a blinking LED on your board, and debug output similar to this on your computer:

Congratulations, you have your first Embassy application running! Here are some suggestions for where to go from here:

The full example can be found here.

The project definition needs to contain the embassy dependencies:

Depending on your microcontroller, you may need to replace embassy-nrf with something else (embassy-stm32 for STM32. Remember to update feature flags as well).

In this particular case, the nrf52840 chip is selected, and the RTC1 peripheral is used as the time driver.

As an example, let’s create a new embassy project from scratch for a STM32G474. The same instructions are applicable for any supported chip with some minor changes.

Run:

to create an empty rust project:

Looking in the Embassy examples, we can see there’s a stm32g4 folder. Find src/blinky.rs and copy its contents into our src/main.rs.

It may be tempting to pass arrays or wrappers, like heapless::Vec, to a function or return one just like you would with a std::Vec. However, in most embedded applications you don’t want to spend resources on an allocator and end up placing buffers on the stack. This, however, can easily blow up your stack if you are not careful.

Consider the following example:

When calling process_buffer in your program, a copy of the buffer you pass to the function will be created, consuming another 1024 bytes. After the processing, another 1024 byte buffer will be placed on the stack to be returned to the caller. (You can check the assembly, there will be two memcopy operations, e.g., bl __aeabi_memcpy when compiling for a Cortex-M processor.)

Possible Solution:

Pass the data by reference and not by value on both, the way in and the way out. For example, you could return a slice of the input buffer as the output. Requiring the lifetime of the input slice and the output slice to be the same, the memory safetly of this procedure will be enforced by the compiler.

The PAC is the lowest API for accessing peripherals and registers, if you don’t count reading/writing directly to memory addresses. It provides distinct types to make accessing peripheral registers easier, but it does not prevent you from writing unsafe code.

Writing an application using the PAC directly is therefore not recommended, but if the functionality you want to use is not exposed in the upper layers, that’s what you need to use.

The blinky app using PAC is shown below:

As you can see, a lot of code is needed to enable the peripheral clocks and to configure the input pins and the output pins of the application.

Another downside of this application is that it is busy-looping while polling the button state. This prevents the microcontroller from utilizing any sleep mode to save power.

To simplify our application, we can use the HAL instead. The HAL exposes higher level APIs that handle details such as:

The HAL example is shown below:

As you can see, the application becomes a lot simpler, even without using any async code. The Input and Output types hide all the details of accessing the GPIO registers and allow you to use a much simpler API for querying the state of the button and toggling the LED output.

The same downside from the PAC example still applies though: the application is busy looping and consuming more power than necessary.

To save power, we need to configure the application so that it can be notified when the button is pressed using an interrupt.

Once the interrupt is configured, the application can instruct the microcontroller to enter a sleep mode, consuming very little power.

Given Embassy focus on async Rust (which we’ll come back to after this example), the example application must use a combination of the HAL and PAC in order to use interrupts. For this reason, the application also contains some helper functions to access the PAC (not shown below).

The simple application is now more complex again, primarily because of the need to keep the button and LED states in the global scope where it is accessible by the main application loop, as well as the interrupt handler.

To do that, the types must be guarded by a mutex, and interrupts must be disabled whenever we are accessing this global state to gain access to the peripherals.

Luckily, there is an elegant solution to this problem when using Embassy.

It’s time to use the Embassy capabilities to its fullest. At the core, Embassy has an async executor, or a runtime for async tasks if you will. The executor polls a set of tasks (defined at compile time), and whenever a task blocks, the executor will run another task, or put the microcontroller to sleep.

The async version looks very similar to the HAL version, apart from a few minor details:

When button.await_for_any_edge().await is called, the executor will pause the main task and put the microcontroller in sleep mode, unless there are other tasks that can run. Internally, the Embassy HAL has configured the interrupt handler for the button (in ExtiInput), so that whenever an interrupt is raised, the task awaiting the button will be woken up.

The minimal overhead of the executor and the ability to run multiple tasks "concurrently" combined with the enormous simplification of the application, makes async a great fit for embedded.

We have seen how the same application can be written at the different abstraction levels in Embassy. First starting out at the PAC level, then using the HAL, then using interrupts, and then using interrupts indirectly using async Rust.

The executor function is described below. The executor keeps a queue of tasks that it should poll. When a task is created, it is polled (1). The task will attempt to make progress until it reaches a point where it would be blocked. This may happen whenever a task is .await’ing an async function. When that happens, the task yields execution by (2) returning Poll::Pending. Once a task yields, the executor enqueues the task at the end of the run queue, and proceeds to (3) poll the next task in the queue. When a task is finished or canceled, it will not be enqueued again.

If you use the #[embassy_executor::main] macro in your application, it creates the Executor for you and spawns the main entry point as the first task. You can also create the Executor manually, and you can in fact create multiple Executors.

Interrupts are a common way for peripherals to signal completion of some operation and fits well with the async execution model. The following diagram describes a typical application flow where (1) a task is polled and is attempting to make progress. The task then (2) instructs the peripheral to perform some operation, and awaits. After some time has passed, (3) an interrupt is raised, marking the completion of the operation.

The peripheral HAL then (4) ensures that interrupt signals are routed to the peripheral and updating the peripheral state with the results of the operation. The executor is then (5) notified that the task should be polled, which it will do.

Embassy features an internal timer queue enabled by the time feature flag. When enabled, Embassy assumes a time Driver implementation existing for the platform. Embassy provides time drivers for the nRF, STM32, RPi Pico, WASM and Std platforms.

The timer driver implementations for the embedded platforms might support only a fixed number of alarms that can be set. Make sure the number of tasks you expect wanting to use the timer at the same time do not exceed this limit.

The timer speed is configurable at compile time using the time-tick-<frequency>. At present, the timer may be configured to run at 1000 Hz, 32768 Hz, or 1 MHz. Before changing the defaults, make sure the target HAL supports the particular frequency setting.

The bootloader supports

In general, the bootloader works on any platform that implements the embedded-storage traits for its internal flash, but may require custom initialization code to work.

STM32L0x1 devices require the flash-erase-zero feature to be enabled.

The bootloader divides the storage into 4 main partitions, configurable when creating the bootloader instance or via linker scripts:

The partitions for ACTIVE (+BOOTLOADER), DFU and BOOTLOADER_STATE may be placed in separate flash. The page size used by the bootloader is determined by the lowest common multiple of the ACTIVE and DFU page sizes. The BOOTLOADER_STATE partition must be big enough to store one word per page in the ACTIVE and DFU partitions combined.

The bootloader has a platform-agnostic part, which implements the power fail safe swapping algorithm given the boundaries set by the partitions. The platform-specific part is a minimal shim that provides additional functionality such as watchdogs or supporting the nRF52 softdevice.

The embassy::time::Timer type provides two timing methods.

Timer::at creates a future that completes at the specified Instant, relative to the system boot time. Timer::after creates a future that completes after the specified Duration, relative to when the future was created.

An example of a delay is provided as follows:

The embassy::time::Delay type provides an implementation of the embedded-hal and embedded-hal-async traits. This can be used for drivers that expect a generic delay implementation to be provided.

An example of how this can be used:

The nRF timer driver operates at 32768 Hz by default.

The following peripherals have a HAL implementation at present

For bluetooth, you can use the nrf-softdevice crate.

STM32 microcontrollers come in many families, and flavors and supporting all of them is a big undertaking. Embassy has taken advantage of the fact that the STM32 peripheral versions are shared across chip families. Instead of re-implementing the SPI peripheral for every STM32 chip family, embassy has a single SPI implementation that depends on code-generated register types that are identical for STM32 families with the same version of a given peripheral.

The STM32 timer driver operates at 32768 Hz by default.

Using mutual exclusion is the simplest way to share a peripheral.

The structure facilitating access to the resource is the defined LedType.

A channel is another way to ensure exclusive access to a resource. Using a channel is great in the cases where the access can happen at a later point in time, allowing you to enqueue operations and do other things.

This example replaces the Mutex with a Channel, and uses another task (the main loop) to drive the LED. The advantage of this approach is that only a single task references the peripheral, separating concerns. However, using a Mutex has a lower overhead and might be necessary if you need to ensure that the operation is completed before continuing to do other work in your task.

An example showcasing more methods for sharing can be found here.

An example of how to deal with multiple devices sharing a common I2C or SPI bus can be found here.

When a project that imports embassy-stm32 is compiled, that project selects the feature corresponding to the chip that project is using. Based on that feature, embassy-stm32 selects supported IP for the chip, and enables the corresponding HAL implementations. But how does embassy-stm32 know what IP the chip contains, out of the hundreds of chips that we support? It’s a long story that starts with stm32-data-sources.

stm32-data-sources is as mostly barren repository. It has no README, no documentation, and few watchers. But it’s the core of what makes embassy-stm32 possible. The data for every chip that we support is taken in part from a corresponding XML file like STM32F051K4Ux.xml. In that file, you’ll see lines like the following:

These lines indicate that this chip has an i2c, and that it’s version is "v1_1". It also indicates that it has a general purpose timer that with a version of "v2_x". From this data, it’s possible to determine which implementations should be included in embassy-stm32. But actually doing that is another matter.

While all users of this project are familiar with embassy-stm32, fewer are familiar with the project that powers it: stm32-data. This project doesn’t just aim to generate data for embassy-stm32, but for machine consumption in general. To acheive this, information from multiple files from the stm32-data-sources project are combined and parsed to assign register block implementations for each supported IP. The core of this matching resides in chips.rs:

In this case, the i2c version corresponds to our "v2" and the general purpose timer version corresponds to our "v1". Therefore, the i2c_v2.yaml and timer_v1.yaml register block implementations are assigned to those IP, respectively. The result is that these lines arr generated in STM32F051K4.json:

In addition to register blocks, data for pin and RCC mapping is also generated and consumed by embassy-stm32. stm32-metapac-gen is used to package and publish the data as a crate.

In the lib.rs file located in the root of embassy-stm32, you’ll see this line:

And in the mod.rs of the i2c mod, you’ll see this:

Because i2c is supported for STM32F051K4 and its version corresponds to our "v2", the i2c and i2c_v2, configuration directives will be present, and embassy-stm32 will include these files, respectively. This and other configuration directives and tables are generated from the data for chip, allowing embassy-stm32 to expressively and clearly adapt logic and implementations to what is required for each chip. Compared to other projects across the embedded ecosystem, embassy-stm32 is the only project that can re-use code across the entire stm32 lineup and remove difficult-to-implement unsafe logic to the HAL.

This means your code is sufficiently complex that panic! invocation’s formatting requirements could not be optimized out, despite your usage of panic-halt or panic-reset.

You can remedy this by adding the following to your .cargo/config.toml:

This replaces all panics with a UDF (undefined) instruction.

Depending on your chipset, this will exhibit different behavior.

Refer to the spec for your chipset, but for thumbv6m, it results in a hardfault. Which can be configured like so:

Refer to cortex-m’s exception handling for more info.

There are a couple techniques that have been documented, generally you want to measure how long you are spending in the idle or low priority loop.

We need to document specifically how to do this in embassy, but this older post describes the general process.

If you end up doing this, please update this section with more specific examples!

Tools like cargo size and cargo nm can tell you the size of any globals or other static usage. Specifically you will want to see the size of the .data and .bss sections, which together make up the total global/static memory usage.

Check out cargo-call-stack for statically calculating worst-case stack usage. There are some caveats and inaccuracies possible with this, but this is a good way to get the general idea. See the README for more details.

Check your board and crystal/oscillator, in particular make sure that HSE is set to the correct value, e.g. 8_000_000 Hertz if your board does indeed run on a 8 MHz oscillator.

The USB specification requires that all USB devices monitor the bus for detection of plugging/unplugging actions. The devices must pull-up the D+ or D- lane as soon as the host supplies VBUS.

See the docs, for example at usb/struct.Config.html for information on how to enable/disable vbus_detection.

When the device is powered only from the USB bus that simultaneously serves as the data connection, this is optional. (If there’s no power in VBUS the device would be off anyway, so it’s safe to always assume there’s power in VBUS, i.e. the USB cable is always plugged in). If your device doesn’t have the required connections in place to allow VBUS sensing (see below), then this option needs to be set to false to work.

When the device is powered from another power source and therefore can stay powered through USB cable plug/unplug events, then this must be implemented and vbus_detection MUST be set to true.

If your board is powered from the USB and you are unsure whether it supports vbus_detection, consult the schematics of your board to see if VBUS is connected to PA9 for USB Full Speed or PB13 for USB High Speed, vice versa, possibly with a voltage divider. When designing your own hardware, see ST application note AN4879 (in particular section 2.6) and the reference manual of your specific chip for more details.

STM32 chips with built-in power management (SMPS and LDO) settings often cause user problems when the configuration does not match how the board was designed.

Settings from the examples, or even from other working boards, may not work on YOUR board, because they are wired differently.

Additionally, some PWR settings require a full device reboot (and enough time to discharge any power capacitors!), making this hard to troubleshoot. Also, some "wrong" power settings will ALMOST work, meaning it will sometimes work on some boots, or for a while, but crash unexpectedly.

There is not a fix for this yet, as it is board/hardware dependant. See this tracking issue for more details

The STM32 BDMA controller included in some STM32H7 chips has to be configured to use only certain regions of RAM, otherwise the transfer will fail.

If you see errors that look like this:

You need to set up your linker script to define a special region for this area and copy data to that region before using with BDMA.

General steps:

See SMT32H7 SPI BDMA example for more details.