Modern embedded framework, using Rust and async.
Go to file
Ulf Lilleengen 1ff1f00d5a
Merge pull request #3282 from elagil/add_sai_is_muted
feat: add function to check if SAI is muted
2024-08-25 13:59:27 +00:00
.github Enable rp235x doc tests, fixup feature doc 2024-08-12 05:47:16 -04:00
.vscode vscode: improve docs in settings.json 2024-05-20 11:33:13 -05:00
cyw43 Use released bt-hci crate 2024-08-21 18:14:15 +02:00
cyw43-firmware cyw43: add Bluetooth support. 2024-08-05 21:07:42 +02:00
cyw43-pio fix rp docs build 2024-08-12 14:31:54 +02:00
docs Update faq.adoc - "code doesn't work in release mode" (#3267) 2024-08-18 10:58:07 +02:00
embassy-boot Prepare to release embassy-boot 2024-08-05 08:56:29 +02:00
embassy-boot-nrf Prepare to release embassy-boot-nrf 2024-08-05 08:56:29 +02:00
embassy-boot-rp fix rp docs build 2024-08-12 14:31:54 +02:00
embassy-boot-stm32 Prepare to release embassy-boot 2024-08-05 08:56:29 +02:00
embassy-embedded-hal update dates 2024-08-05 08:58:56 +02:00
embassy-executor update dates 2024-08-05 08:58:56 +02:00
embassy-executor-macros prepare release embassy-executor 2024-08-05 08:56:29 +02:00
embassy-futures Reduced define for 'unreachable!' to a single macro rule 2024-07-17 17:05:52 -04:00
embassy-hal-internal Prepare release of embassy-hal-internal 2024-08-05 08:56:29 +02:00
embassy-net feat(mdns): Enable mdns support through smoltcp 2024-08-16 22:56:32 -04:00
embassy-net-adin1110 Prepare release embassy-net-driver-channel 2024-08-05 08:56:29 +02:00
embassy-net-driver Complete cargo.tomls more. 2024-01-12 00:32:47 +01:00
embassy-net-driver-channel update dates 2024-08-05 08:58:56 +02:00
embassy-net-enc28j60 Prepare embassy-time release 2024-08-05 08:56:29 +02:00
embassy-net-esp-hosted Silence some unused warnings on nightly. 2024-08-05 21:37:07 +02:00
embassy-net-ppp Prepare release embassy-net-driver-channel 2024-08-05 08:56:29 +02:00
embassy-net-tuntap Fix warnings in recent nightly. 2024-03-20 16:39:09 +01:00
embassy-net-wiznet Prepare release embassy-net-driver-channel 2024-08-05 08:56:29 +02:00
embassy-nrf Fixes build issues related to nrf9120 features 2024-08-12 06:23:32 -06:00
embassy-rp Set up timer0 tick when initializing clocks 2024-08-24 12:19:12 +02:00
embassy-stm32 Merge pull request #3282 from elagil/add_sai_is_muted 2024-08-25 13:59:27 +00:00
embassy-stm32-wpan Silence some unused warnings on nightly. 2024-08-05 21:37:07 +02:00
embassy-sync Fix link to PriorityChannel 2024-08-18 10:36:04 +02:00
embassy-time update dates 2024-08-05 08:58:56 +02:00
embassy-time-driver Complete cargo.tomls more. 2024-01-12 00:32:47 +01:00
embassy-time-queue-driver Fix spelling and white space mistakes 2024-04-11 19:45:38 +00:00
embassy-usb feat(usb): add device qualifier descriptor 2024-08-15 11:26:24 +08:00
embassy-usb-dfu Prepare to release embassy-boot 2024-08-05 08:56:29 +02:00
embassy-usb-driver Remove leftover cargo new boilerplate. 2024-04-26 22:59:50 +02:00
embassy-usb-logger Prepare to release embassy-usb 2024-08-05 08:56:29 +02:00
embassy-usb-synopsys-otg Merge pull request #3281 from elagil/ulpi_add_fs_support 2024-08-25 06:05:41 +00:00
examples Use released bt-hci crate 2024-08-21 18:14:15 +02:00
release add convenience script to bump dependency version 2024-06-04 09:19:07 +02:00
tests Merge pull request #3243 from HellbenderInc/rp2350 2024-08-12 11:22:19 +00:00
.gitattributes mark json file inside .vscode folder as jsonc 2024-01-06 11:59:55 +08:00
.gitignore stm32: use stm32-metapac from crates.io, remove stm32-data submodule. 2023-03-20 02:38:12 +01:00
ci-nightly.sh Update stable to Rust 1.79. 2024-06-13 20:40:04 +02:00
ci.sh rp: use the rp-binary-info crate for binary info. 2024-08-17 22:12:39 +02:00
LICENSE-APACHE Centralize license and MSRV boilerplate into the repo readme. 2024-01-11 18:18:35 +01:00
LICENSE-CC-BY-SA Explicitly license the book prose CC-BY-SA 2024-05-23 09:57:10 +02:00
LICENSE-MIT Centralize license and MSRV boilerplate into the repo readme. 2024-01-11 18:18:35 +01:00
NOTICE.md Fix spelling and white space mistakes 2024-04-11 19:45:38 +00:00
README.md fix link to embassy book 2024-05-24 17:31:14 +02:00
rust-toolchain-nightly.toml Update nightly, fix error with rp inline asm. 2024-07-16 16:40:54 +02:00
rust-toolchain.toml Update to Rust 1.80, make check-cfg unconditional. 2024-07-25 15:53:00 +02:00
rustfmt.toml Add rustfmt.toml with some nice settings. 2022-06-12 22:15:28 +02:00

Embassy

Embassy is the next-generation framework for embedded applications. Write safe, correct and energy-efficient embedded code faster, using the Rust programming language, its async facilities, and the Embassy libraries.

Documentation - API reference - Website - Chat

Rust + async ❤️ embedded

The Rust programming language is blazingly fast and memory-efficient, with no runtime, garbage collector or OS. It catches a wide variety of bugs at compile time, thanks to its full memory- and thread-safety, and expressive type system.

Rust's async/await allows for unprecedentedly easy and efficient multitasking in embedded systems. Tasks get transformed at compile time into state machines that get run cooperatively. It requires no dynamic memory allocation, and runs on a single stack, so no per-task stack size tuning is required. It obsoletes the need for a traditional RTOS with kernel context switching, and is faster and smaller than one!

Batteries included

  • Hardware Abstraction Layers - HALs implement safe, idiomatic Rust APIs to use the hardware capabilities, so raw register manipulation is not needed. The Embassy project maintains HALs for select hardware, but you can still use HALs from other projects with Embassy.

    • embassy-stm32, for all STM32 microcontroller families.
    • embassy-nrf, for the Nordic Semiconductor nRF52, nRF53, nRF91 series.
    • embassy-rp, for the Raspberry Pi RP2040 microcontroller.
    • esp-rs, for the Espressif Systems ESP32 series of chips.
      • Embassy HAL support for Espressif chips is being developed in the esp-rs/esp-hal repository.
      • Async WiFi, Bluetooth and ESP-NOW is being developed in the esp-rs/esp-wifi repository.
    • ch32-hal, for the WCH 32-bit RISC-V(CH32V) series of chips.
  • Time that Just Works - No more messing with hardware timers. embassy_time provides Instant, Duration and Timer types that are globally available and never overflow.

  • Real-time ready - Tasks on the same async executor run cooperatively, but you can create multiple executors with different priorities, so that higher priority tasks preempt lower priority ones. See the example.

  • Low-power ready - Easily build devices with years of battery life. The async executor automatically puts the core to sleep when there's no work to do. Tasks are woken by interrupts, there is no busy-loop polling while waiting.

  • Networking - 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.

  • Bluetooth - The nrf-softdevice crate provides Bluetooth Low Energy 4.x and 5.x support for nRF52 microcontrollers. The embassy-stm32-wpan crate provides Bluetooth Low Energy 5.x support for stm32wb microcontrollers.

  • LoRa - The lora-rs project provides an async LoRa and LoRaWAN stack that works well on Embassy.

  • USB - 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.

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

Sneak peek

use defmt::info;
use embassy_executor::Spawner;
use embassy_time::{Duration, Timer};
use embassy_nrf::gpio::{AnyPin, Input, Level, Output, OutputDrive, Pin, Pull};
use embassy_nrf::Peripherals;

// Declare async tasks
#[embassy_executor::task]
async fn blink(pin: AnyPin) {
    let mut led = Output::new(pin, Level::Low, OutputDrive::Standard);

    loop {
        // Timekeeping is globally available, no need to mess with hardware timers.
        led.set_high();
        Timer::after_millis(150).await;
        led.set_low();
        Timer::after_millis(150).await;
    }
}

// Main is itself an async task as well.
#[embassy_executor::main]
async fn main(spawner: Spawner) {
    let p = embassy_nrf::init(Default::default());

    // Spawned tasks run in the background, concurrently.
    spawner.spawn(blink(p.P0_13.degrade())).unwrap();

    let mut button = Input::new(p.P0_11, Pull::Up);
    loop {
        // Asynchronously wait for GPIO events, allowing other tasks
        // to run, or the core to sleep.
        button.wait_for_low().await;
        info!("Button pressed!");
        button.wait_for_high().await;
        info!("Button released!");
    }
}

Examples

Examples are found in the examples/ folder separated by the chip manufacturer they are designed to run on. For example:

  • examples/nrf52840 run on the nrf52840-dk board (PCA10056) but should be easily adaptable to other nRF52 chips and boards.
  • examples/nrf5340 run on the nrf5340-dk board (PCA10095).
  • examples/stm32xx for the various STM32 families.
  • examples/rp are for the RP2040 chip.
  • examples/std are designed to run locally on your PC.

Running examples

  • Install probe-rs following the instructions at https://probe.rs.
  • Change directory to the sample's base directory. For example:
cd examples/nrf52840
  • Ensure Cargo.toml sets the right feature for the name of the chip you are programming. If this name is incorrect, the example may fail to run or immediately crash after being programmed.

  • Ensure .cargo/config.toml contains the name of the chip you are programming.

  • Run the example

For example:

cargo run --release --bin blinky

For more help getting started, see Getting Started and Running the Examples.

Developing Embassy with Rust Analyzer based editors

The Rust Analyzer is used by Visual Studio Code and others. Given the multiple targets that Embassy serves, there is no Cargo workspace file. Instead, the Rust Analyzer must be told of the target project to work with. In the case of Visual Studio Code, please refer to the .vscode/settings.json file's rust-analyzer.linkedProjectssetting.

Minimum supported Rust version (MSRV)

Embassy is guaranteed to compile on stable Rust 1.75 and up. It might compile with older versions but that may change in any new patch release.

Why the name?

EMBedded ASYnc! :)

License

Embassy is licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.