DOCSEARCHbyAlgolia
Submit Docs

Embassy Framework

repository·main·Indexed 27 days ago

https://github.com/embassy-rs/embassy

An async-first embedded framework for Rust designed for high-performance, low-power, and safe multitasking without a traditional RTOS. It includes the embassy-executor for static task allocation and no-heap async/await, embassy-boot for power-fail-safe firmware updates, and embassy-embedded-hal for SPI/I2C bus sharing and flash utilities. The framework provides hardware-specific support for RP2040, STM32, nRF, and Ambiq Apollo3, including a cyw43 driver for the CYW43439 WiFi+Bluetooth chip used in Raspberry Pi Pico W.

Tokens
24.2K
Snippets
39
Records
172
Agent score
94%

What's inside Embassy

  1. Overview of embassy-stm32-wpan

    main

    The embassy-stm32-wpan crate provides asynchronous WPAN (Wireless Personal Area Network) support for STM32WB family microcontrollers. It enables short-range wireless communication using the following features:

    • A Rust interface to the WPAN stack running on the STM32WB co-processor.
    • A Controller trait implementation compatible with the stm32wb-hci crate.
    • An embassy-net driver implementation specifically for the 802.15.4 MAC layer.

  2. Overview of embassy-futures

    main

    The embassy-futures crate provides utility functions for working with Rust futures in embedded environments. It is specifically designed to be no_std compatible and does not require an alloc (heap allocation) dependency. It is optimized for minimal code size, making it suitable for resource-constrained embedded systems.

    Key features include:

    • Future combinators: Tools like join and select to manage multiple concurrent futures.
    • Async utilities: Functions to use async logic without a full executor, such as block_on and yield_now.

  3. Overview of Embassy components

    main

    Embassy is a collection of crates designed to make async/await a first-class option for embedded development. The project is modular, allowing you to use specific crates independently or together. Key components include:

    • embassy-executor: An async/await executor that runs a fixed number of tasks (allocated at startup) and provides a system timer for async and blocking delays.
    • Hardware Abstraction Layers (HALs): Provide safe Rust APIs for peripherals (USART, I2C, SPI, etc.). They support both async and blocking APIs. Embassy HALs can be used standalone without the executor and implement embedded-hal traits.
    • embassy-net: A network stack supporting Ethernet, IP, TCP, UDP, ICMP, and DHCP.
    • embassy-usb: A device-side USB stack with a builder API for common classes like CDC ACM and HID.
    • embassy-boot: A lightweight, power-fail-safe bootloader supporting firmware upgrades with trial boots and rollbacks.
    • Bluetooth/LoRa: Specialized crates for BLE (trouble, nrf-softdevice) and LoRaWAN (lora-rs).

  4. Overview of embassy-sync synchronization primitives

    main

    The embassy-sync crate provides synchronization primitives and data structures designed for asynchronous embedded development. These primitives are compatible with any executor.

    Available primitives include:

    Channels

    • Channel: A Multiple Producer Multiple Consumer (MPMC) channel where each message is received by exactly one consumer.
    • PriorityChannel: An MPMC channel where higher priority items are shifted to the front.
    • PubSubChannel: A broadcast (publish-subscribe) channel where each message is received by all consumers.

    Signaling

    • Signal: Signals the latest value to a single consumer.
    • Watch: Signals the latest value to multiple consumers.

    State and Streams

    • Mutex: Synchronizes state between asynchronous tasks.
    • Pipe: A byte stream implementing embedded_io traits.
    • LazyLock: A value that is initialized on its first access.

    Waker Utilities

    • WakerRegistration: Utility to register and wake a Waker.
    • AtomicWaker: Utility to register and wake a Waker from an interrupt context.
    • MultiWakerRegistration: Utility for registering and waking multiple Wakers.

  5. Overview of Embassy iMXRT HAL

    main
    The embassy-imxrt HAL provides safe, idiomatic Rust APIs for the NXP iMXRT Family of MCUs. It supports both blocking and async APIs. Using the async APIs allows the HAL to handle interrupt management and peripheral waiting in low power mode, enabling applications to focus on business logic. The HAL is compatible with any executor.

  6. Overview of embassy-executor

    main

    embassy-executor is an async/await executor specifically designed for embedded systems. It provides several key features for resource-constrained environments:

    • No Heap Required: Does not require an allocator (no_alloc).
    • Static Task Allocation: Tasks are statically allocated at compile time. The exact size required is calculated automatically, and if tasks exceed available RAM, the linker will detect this at compile time, preventing runtime OOM panics.
    • Efficient Polling: Wakes only the specific task that was woken, rather than polling all tasks. It also implements fairness to prevent a single task from monopolizing the CPU.
    • Low Power: The executor avoids busy-loop polling; the CPU sleeps (using WFE/SEV or interrupts) when no work is pending.
    • Integrated Timer Queue: Supports easy sleeping via Timer::after_secs(n).await;.
    • Multi-priority Support: You can create multiple executor instances to run tasks at different priority levels, allowing higher-priority tasks to preempt lower-priority ones.

  7. Overview of Embassy Microchip HAL

    main

    The Embassy Microchip HAL provides safe, idiomatic Rust APIs for the Microchip MEC and CEC Family of MCUs. It eliminates the need for raw register manipulation by providing high-level abstractions for hardware capabilities.

    Key features include:

    • Dual API Styles: Supports both blocking and async APIs for many peripherals.
    • Async Benefits: When using async APIs, the HAL automatically handles interrupt management and peripheral waiting in low-power modes, allowing developers to focus on application logic.
    • Runtime Flexibility: The HAL can be used for both non-async and async operations. For async operations, you can choose your preferred Embassy runtime.

  8. Overview of Embassy Framework

    main

    Embassy is a next-generation embedded framework for Rust that leverages async/await to provide safe, efficient, and easy multitasking. It eliminates the need for a traditional RTOS by using cooperative multitasking via an async executor, which runs on a single stack and requires no dynamic memory allocation.

    Key features include:

    • Low-power design: The executor automatically puts the core to sleep when idle.
    • Real-time readiness: Supports multiple executors with different priorities for preemption.
    • Batteries included: Provides HALs, networking stacks, USB, Bluetooth, and bootloaders.

  9. Overview of embassy-time-queue-utils

    main

    The embassy-time-queue-utils crate provides timer queue implementations designed to assist in the creation of an embassy-time-driver.

    Usage Guidance:

    • HAL Users: You generally do not need to depend on this crate directly.
    • HAL Implementers: You should use this crate if you are implementing a new time driver for a hardware abstraction layer (HAL). For implementation guidance, refer to the embassy-time-driver documentation.

  10. Overview of embassy-boot functionality

    main

    embassy-boot is a lightweight bootloader designed for power-fail-safe firmware updates. It supports trial boots and rollbacks.

    It can be used in two ways:

    1. As a standalone bootloader: Flashed directly using default configurations derived from linker scripts.
    2. As a library: Integrated into your application to handle firmware updates (e.g., after your application has downloaded a new image via a network).

    Note: The bootloader itself does not provide networking; the user application must handle fetching new firmware.

  11. Overview of Embassy nRF HAL

    main
    The embassy-nrf HAL provides safe, idiomatic Rust APIs for Nordic Semiconductor nRF hardware. It supports both blocking and async APIs. Using async APIs allows the HAL to handle peripheral completion and interrupts automatically in low power mode. The HAL can be used with any executor and supports both non-async and async operations.

  12. Overview of embassy-usb

    main

    embassy-usb is an asynchronous USB device stack designed for embedded devices in Rust. It features a native async implementation and is fully lock-free, meaning endpoints are separate objects that can be used independently without a central mutex. If the underlying driver supports it, endpoints can even be used from different priority levels.

    Key features include:

    • Suspend/resume and remote wakeup support.
    • Support for USB composite devices.
    • An ergonomic descriptor builder.
    • Ready-to-use implementations for several USB classes: Serial ports (CDC ACM), Ethernet (CDC NCM), Human Interface Devices (HID), and MIDI.