Modern embedded framework, using Rust and async.
Go to file
Samuel Tardieu e453334870 LoRa/SX1276: adjust Rx window offset and duration
After a transmission, two receive windows Rx1 and Rx2 are opened
for one second each, one right after the other, after a fixed delay
(for example 5s). The Rx window offset is added to the starting date
of each window and the Rx window duration represents the maximum
delay we will wait for an incoming message before declaring that
a timeout occurred.

A value of -500ms for the offset and 800ms for the duration means
that instead of having Rx1 = [5000, 6000[ and Rx2 = [6000, 7000[
we get Rx1 = [4500, 5300[ and Rx2 = [5500, 6300[. We only cover
30% of the expected windows.

The maximum time a SX127x can take before the Rx side is ready is
TS_HOP + TS_RE = 50µs + 2.33ms. Using 3ms for the offset and
1003ms for the duration will give much better time windows:
Rx1 = [4997, 5997[ and Rx2 = [5997, 7000]. Note that the
lorawan-device crate caps Rx1 end date to Rx2 start date.

This change allows a previously failing Murata CMWX1ZZABZ-091
module (STM32L + SX1276) to connect to the TTN LoRa network.
2023-01-27 16:01:41 +01:00
.github Support codesigning in the firmware updater 2023-01-12 13:30:58 +11:00
.vscode Update vscode settings for latest RA. 2023-01-11 17:43:12 +01:00
docs Documentation on verifying firmware 2023-01-14 17:36:22 +11:00
embassy-boot Support codesigning in the firmware updater 2023-01-12 13:30:58 +11:00
embassy-cortex-m all Cargo.toml: Add license to all crate Cargo.toml files 2022-10-07 12:41:56 +02:00
embassy-embedded-hal Switch to async-fn-in-trait 2022-11-25 21:02:06 +01:00
embassy-executor Remove unnecessary use of atomic-polyfill. 2022-12-23 20:46:49 +01:00
embassy-futures futures: cargo.toml metadata 2022-08-30 19:29:59 +02:00
embassy-hal-common rp: Fix BufferedUart drop code 2023-01-04 15:59:03 +01:00
embassy-lora LoRa/SX1276: adjust Rx window offset and duration 2023-01-27 16:01:41 +01:00
embassy-macros Hide doc comments from inner function include doc comments on outer function 2022-12-24 21:21:07 -06:00
embassy-net add missing copy of icmpv6 checksum 2023-01-24 10:25:37 +01:00
embassy-net-driver net: split driver trait to a separate crate. 2022-12-26 04:49:08 +01:00
embassy-net-driver-channel net/chan: split state runner. 2022-12-27 01:07:58 +01:00
embassy-nrf Replace Level: Into<bool> with From<Level> 2023-01-23 13:35:24 +01:00
embassy-rp rp gpio: make pin_bank() inline 2023-01-19 13:36:40 +08:00
embassy-stm32 Fix rcc prescaler for wb55 HCLK1 2023-01-21 14:39:25 +01:00
embassy-sync Remove unnecessary use of atomic-polyfill. 2022-12-23 20:46:49 +01:00
embassy-time time: Fix nighly feature compilation after upgrade to embedded-hal-async 2022-11-27 17:59:01 -05:00
embassy-usb Refactor embassy-usb address handling to allow reordering of status resoponse 2023-01-11 17:47:12 +01:00
embassy-usb-driver Refactor embassy-usb address handling to allow reordering of status resoponse 2023-01-11 17:47:12 +01:00
embassy-usb-logger docs: add missing README for usb-logger 2022-11-21 11:24:53 +01:00
examples Merge #1173 #1174 2023-01-24 09:26:21 +00:00
stm32-data@96decdd611 stm32: add stm32c0 support. 2023-01-17 21:28:16 +01:00
stm32-gen-features all Cargo.toml: Add license to all crate Cargo.toml files 2022-10-07 12:41:56 +02:00
stm32-metapac stm32: add stm32c0 support. 2023-01-17 21:28:16 +01:00
stm32-metapac-gen stm32: add stm32c0 support. 2023-01-17 21:28:16 +01:00
tests Refactor after review 2022-12-13 13:49:51 +01:00
xtask all Cargo.toml: Add license to all crate Cargo.toml files 2022-10-07 12:41:56 +02:00
.gitignore ci: add build with stable. 2022-02-12 01:16:31 +01:00
.gitmodules Add stm32-metapac crate, with codegen in rust 2021-05-31 02:40:58 +02:00
ci_stable.sh stm32: add stm32c0 support. 2023-01-17 21:28:16 +01:00
ci.sh fix embedded-sdmmc integration. 2023-01-21 00:32:34 +01:00
LICENSE-APACHE Update copyright holder names and add notice file (#790) 2022-06-02 13:09:37 +02:00
LICENSE-MIT Update copyright holder names and add notice file (#790) 2022-06-02 13:09:37 +02:00
NOTICE.md Update copyright holder names and add notice file (#790) 2022-06-02 13:09:37 +02:00
README.md Rename examples/nrf to examples/nrf52840 2023-01-09 22:30:02 +01:00
rust-toolchain.toml feat: compile bootloader examples for nRF91 2023-01-04 13:38:43 +01: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 unprecedently 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.
  • 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.

  • LoRa - embassy-lora supports LoRa networking on STM32WL wireless microcontrollers and Semtech SX126x and SX127x transceivers.

  • 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(Duration::from_millis(150)).await;
        led.set_low();
        Timer::after(Duration::from_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 seperated 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

  • Setup git submodules (needed for STM32 examples)
git submodule init
git submodule update
  • Install probe-run with defmt support.
cargo install probe-run
  • Change directory to the sample's base directory. For example:
cd examples/nrf52840
  • Run the example

For example:

cargo run --bin blinky

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 the latest stable Rust version at the time of release. It might compile with older versions but that may change in any new patch release.

Several features require nightly:

  • The #[embassy_executor::main] and #[embassy_executor::task] attribute macros.
  • Async traits

These are enabled by activating the nightly Cargo feature. If you do so, Embassy is guaranteed to compile on the exact nightly version specified in rust-toolchain.toml. It might compile with older or newer nightly versions, but that may change in any new patch release.

Why the name?

EMBedded ASYnc! :)

License

This work is licensed under either of

at your option.