# embassy-rs/embassy architecture

> Architecture diagram of the GitHub repository embassy-rs/embassy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/embassy-rs/embassy
- Repository: https://github.com/embassy-rs/embassy

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Hardware Layer
    subgraph "Hardware Layer"
        HW("Hardware (Sensors, GPIO, Peripherals)"):::hardware
    end

    %% HAL Layer
    subgraph "HAL Layer"
        EH("embassy-embedded-hal"):::hal
        ENRF("embassy-nrf"):::hal
        ESTM32("embassy-stm32"):::hal
        ERP("embassy-rp"):::hal
        EMS("embassy-mspm0"):::hal
        ENXP("embassy-nxp"):::hal
        EHALIN("embassy-hal-internal"):::hal
    end

    %% Core Async Runtime
    subgraph "Core Async Runtime"
        EEX("embassy-executor"):::core
        EF("embassy-futures"):::core
        ES("embassy-sync"):::core
        EEM("embassy-executor-macros"):::core
    end

    %% Timekeeping & Scheduling
    subgraph "Timekeeping & Scheduling"
        ET("embassy-time"):::time
        ETD("embassy-time-driver"):::time
        ETQ("embassy-time-queue-utils"):::time
    end

    %% Networking Stack
    subgraph "Networking Stack"
        ENET("embassy-net"):::net
        ENETAD("embassy-net-adin1110"):::net
        ENETDRV("embassy-net-driver"):::net
        ENETENC("embassy-net-enc28j60"):::net
        ENETESP("embassy-net-esp-hosted"):::net
        ENETNRF("embassy-net-nrf91"):::net
        ENETPPP("embassy-net-ppp"):::net
        ENETTUN("embassy-net-tuntap"):::net
        ENETWIZ("embassy-net-wiznet"):::net
    end

    %% USB Stack
    subgraph "USB Stack"
        EUSB("embassy-usb"):::usb
        EUSBDRV("embassy-usb-driver"):::usb
        EUSBD("embassy-usb-dfu"):::usb
        EUSBLOG("embassy-usb-logger"):::usb
        EUSBS("embassy-usb-synopsys-otg"):::usb
    end

    %% Bootloader/DFU
    subgraph "Bootloader/DFU"
        EBOOT("embassy-boot"):::boot
        EBOOTNRF("embassy-boot-nrf"):::boot
        EBOOTRP("embassy-boot-rp"):::boot
        EBOOTSTM("embassy-boot-stm32"):::boot
    end

    %% Examples & Tests
    subgraph "Examples & Tests"
        EX("examples"):::example
        TX("tests"):::example
    end

    %% Connections between layers
    HW --> EH
    EH --> EEX
    EHALIN --> EEX
    ENRF --> EEX
    ESTM32 --> EEX
    ERP --> EEX
    EMS --> EEX
    ENXP --> EEX

    ET --> EEX
    ETD --> EEX
    ETQ --> EEX

    EEX --> ENET
    EEX --> EUSB
    EBOOT --> EEX

    EEX --> EX
    EEX --> TX

    %% Internal Networking Connections
    ENET --> ENETAD
    ENET --> ENETDRV
    ENET --> ENETENC
    ENET --> ENETESP
    ENET --> ENETNRF
    ENET --> ENETPPP
    ENET --> ENETTUN
    ENET --> ENETWIZ

    %% Internal USB Connections
    EUSB --> EUSBDRV
    EUSB --> EUSBD
    EUSB --> EUSBLOG
    EUSB --> EUSBS

    %% Click Events for Core Async Runtime
    click EEX "https://github.com/embassy-rs/embassy/tree/main//embassy-executor"
    click EF "https://github.com/embassy-rs/embassy/tree/main//embassy-futures"
    click ES "https://github.com/embassy-rs/embassy/tree/main//embassy-sync"
    click EEM "https://github.com/embassy-rs/embassy/tree/main//embassy-executor-macros"

    %% Click Events for HAL Layer
    click EH "https://github.com/embassy-rs/embassy/tree/main//embassy-embedded-hal"
    click ENRF "https://github.com/embassy-rs/embassy/tree/main//embassy-nrf"
    click ESTM32 "https://github.com/embassy-rs/embassy/tree/main//embassy-stm32"
    click ERP "https://github.com/embassy-rs/embassy/tree/main//embassy-rp"
    click EMS "https://github.com/embassy-rs/embassy/tree/main//embassy-mspm0"
    click ENXP "https://github.com/embassy-rs/embassy/tree/main//embassy-nxp"
    click EHALIN "https://github.com/embassy-rs/embassy/tree/main//embassy-hal-internal"

    %% Click Events for Timekeeping & Scheduling
    click ET "https://github.com/embassy-rs/embassy/tree/main//embassy-time"
    click ETD "https://github.com/embassy-rs/embassy/tree/main//embassy-time-driver"
    click ETQ "https://github.com/embassy-rs/embassy/tree/main//embassy-time-queue-utils"

    %% Click Events for Networking Stack
    click ENET "https://github.com/embassy-rs/embassy/tree/main//embassy-net"
    click ENETAD "https://github.com/embassy-rs/embassy/tree/main//embassy-net-adin1110"
    click ENETDRV "https://github.com/embassy-rs/embassy/tree/main//embassy-net-driver"
    click ENETENC "https://github.com/embassy-rs/embassy/tree/main//embassy-net-enc28j60"
    click ENETESP "https://github.com/embassy-rs/embassy/tree/main//embassy-net-esp-hosted"
    click ENETNRF "https://github.com/embassy-rs/embassy/tree/main//embassy-net-nrf91"
    click ENETPPP "https://github.com/embassy-rs/embassy/tree/main//embassy-net-ppp"
    click ENETTUN "https://github.com/embassy-rs/embassy/tree/main//embassy-net-tuntap"
    click ENETWIZ "https://github.com/embassy-rs/embassy/tree/main//embassy-net-wiznet"

    %% Click Events for USB Stack
    click EUSB "https://github.com/embassy-rs/embassy/tree/main//embassy-usb"
    click EUSBDRV "https://github.com/embassy-rs/embassy/tree/main//embassy-usb-driver"
    click EUSBD "https://github.com/embassy-rs/embassy/tree/main//embassy-usb-dfu"
    click EUSBLOG "https://github.com/embassy-rs/embassy/tree/main//embassy-usb-logger"
    click EUSBS "https://github.com/embassy-rs/embassy/tree/main//embassy-usb-synopsys-otg"

    %% Click Events for Bootloader/DFU
    click EBOOT "https://github.com/embassy-rs/embassy/tree/main//embassy-boot"
    click EBOOTNRF "https://github.com/embassy-rs/embassy/tree/main//embassy-boot-nrf"
    click EBOOTRP "https://github.com/embassy-rs/embassy/tree/main//embassy-boot-rp"
    click EBOOTSTM "https://github.com/embassy-rs/embassy/tree/main//embassy-boot-stm32"

    %% Click Events for Examples & Tests
    click EX "https://github.com/embassy-rs/embassy/tree/main//examples"
    click TX "https://github.com/embassy-rs/embassy/tree/main//tests"

    %% Styles
    classDef hardware fill:#DCDCDC,stroke:#333,stroke-width:2px;
    classDef hal fill:#F0E68C,stroke:#333,stroke-width:2px;
    classDef core fill:#E6E6FA,stroke:#333,stroke-width:2px;
    classDef time fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef net fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef usb fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef boot fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef example fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
