How embassy-rs/embassy works
Project Type and Purpose
• Embassy is a framework and set of libraries for embedded systems in Rust.
• It provides a complete asynchronous foundation (via its executor), hardware abstractions (through many HAL crates), and higher-level functionalities (network stacks, USB support, bootloader, etc.).
• The README clearly emphasizes that it “obsoletes the need for a traditional RTOS” thanks to the async design and that it “includes batteries (HALs, drivers, timekeeping, USB, networking, etc.).”
File Structure and Identify Main Components
• Executor and Async Core:
– Directories like “embassy-executor”, “embassy-futures”, and “embassy-sync” are responsible for task scheduling, async primitives, and synchronization.
– These represent the core runtime that converts async functions into state machines.
• Hardware Abstraction Layers (HALs):
– Crates such as “embassy-stm32”, “embassy-nrf”, “embassy-rp”, “embassy-mspm0”, “embassy-nxp”, etc. provide the hardware driver layer that makes raw device interactions safer and easier.
• Time and Scheduling:
– “embassy-time”, “embassy-time-driver”, and “embassy-time-queue-utils” handle timers, delays, and global timekeeping.
• Networking Stack:
– “embassy-net” along with its related driver and adapter crates (like “embassy-net-driver”, “embassy-net-adin1110”, “embassy-net-enc28j60”, etc.) encapsulate TCP/IP, UDP, DHCP, ICMP functionality.
• USB Support:
– “embassy-usb”, “embassy-usb-driver”, “embassy-usb-dfu”, “embassy-usb-logger”, “embassy-usb-synopsys-otg” provide device-side USB stacks, classes (serial, HID, etc.) and DFU support.
• Bootloader and DFU:
– “embassy-boot” and its platform variants (like “embassy-boot-nrf”, “embassy-boot-stm32”, “embassy-boot-rp”) implement a safe bootloader protocol with options like firmware upgrades and rollback.
• Examples and Tests:
– The “examples” and “tests” directories demonstrate the usage on a wide range of hardware platforms. They are essential for understanding how the various crates integrate together.
• Supporting Utilities:
– Several support directories (like “embassy-executor-macros”, “embassy-hal-internal”, “embassy-sync”) offer macros, shared bus implementations, and other utility functions used across the framework.
Relationships and Interactions
• The core executor (e.g. embassy-executor) forms the foundation for running async tasks on top of which all other operations are scheduled.
• HAL crates interact with the executor by providing drivers that expose non-blocking API for peripherals (GPIO, SPI, I2C, etc.).
• Time and timer libraries draft global timing functions that are used by the executor as well as higher-level protocols (network timeouts, USB polling, etc.).
• The networking and USB stacks “sit” on top of the HALs and the async runtime, leveraging non-blocking I/O, shared bus access (via embassy-sync), and hardware interrupts.
• The bootloader components serve as a prelude – they ensure that firmware is loaded correctly and then hand off control to an application that uses the async framework.
• Macros and utility crates (e.g. embassy-executor-macros) support compile-time transformations and code generation, enabling ergonomic use of async features.
Architectural Patterns and Design Principles
• Modular, multi-crate design with clear separation between the core async runtime, hardware drivers, protocol stacks, and example applications.
• Use of Rust’s ownership, zero-cost abstractions, and compile-time safety guarantees to eliminate common embedded pitfalls.
• Emphasis on cooperative multitasking (cooperative scheduling without thread preemption) and low-power, interrupt-driven designs.
• Abstraction via traits and macros for easy extensibility across different microcontrollers and platforms.