.github
.vscode
docs
modules
ROOT
examples
images
pages
basic_application.adoc
bootloader.adoc
examples.adoc
getting_started.adoc
hal.adoc
index.adoc
layer_by_layer.adoc
nrf.adoc
runtime.adoc
stm32.adoc
nav.adoc
antora.yml
embassy-boot
embassy-cortex-m
embassy-embedded-hal
embassy-executor
embassy-futures
embassy-hal-common
embassy-lora
embassy-macros
embassy-net
embassy-net-driver
embassy-net-driver-channel
embassy-nrf
embassy-rp
embassy-stm32
embassy-sync
embassy-time
embassy-usb
embassy-usb-driver
embassy-usb-logger
examples
stm32-data
stm32-gen-features
stm32-metapac
stm32-metapac-gen
tests
xtask
.gitignore
.gitmodules
LICENSE-APACHE
LICENSE-MIT
NOTICE.md
README.md
ci.sh
ci_stable.sh
rust-toolchain.toml
rustfmt.toml
d769e562c0
* Remove traits section now that we have embedded-hal-async and refer to it. * Explanation that embassy is multiple things. * Bootloader description image
35 lines
4.1 KiB
Plaintext
35 lines
4.1 KiB
Plaintext
= Embassy
|
|
|
|
Embassy is a project to make async/await a first-class option for embedded development.
|
|
|
|
== What is async?
|
|
|
|
Software written without async may block on I/O operations. In an std environment, such as a PC, software can handle this either by using threads or non-blocking operations.
|
|
|
|
With threads, one thread blocks on an I/O operation, another is able to take its place. However, even on a PC, threads are relatively heavy, and therefore some programming languages, such as Go, have implemented a concept called coroutines or 'goroutines' that are much lighter and less-intensive than threads.
|
|
|
|
The other way to handle blocking I/O operations is to support polling the state of the underlying peripherals to check whether it is available to perform the requested operation. In programming languages without builtin async support,
|
|
this requires building a complex loop checking for events.
|
|
|
|
In Rust, non-blocking operations can be implemented using async-await. Async-await works by transforming each async function into an object called a future. When a future blocks on I/O the future yields, and the scheduler, called an executor, can select a different future to execute. Compared to alternatives such as an RTOS, async can yield better performance and lower power consumption because the executor doesn't have to guess when a future is ready to execute. However, program size may be higher than other alternatives, which may be a problem for certain space-constrained devices with very low memory. On the devices Embassy supports, such as stm32 and nrf, memory is generally large enough to accommodate the modestly-increased program size.
|
|
|
|
== What is Embassy?
|
|
|
|
The Embassy project consists of several crates that you can use together or independently:
|
|
|
|
* **Executor** - The link:https://docs.embassy.dev/embassy-executor/[embassy-executor] is an async/await executor that generally executes a fixed number of tasks, allocated at startup, though more can be added later. The HAL is an API that you can use to access peripherals, such as USART, UART, I2C, SPI, CAN, and USB. Embassy provides implementations of both async and blocking APIs where it makes sense. DMA (Direct Memory Access) is an example where async is a good fit, whereas GPIO states are a better fit for a blocking API. The executor may also provide a system timer that you can use for both async and blocking delays. For less than one microsecond, blocking delays should be used because the cost of context-switching is too high and the executor will be unable to provide accurate timing.
|
|
|
|
* **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.
|
|
** link:https://docs.embassy.dev/embassy-stm32/[embassy-stm32], for all STM32 microcontroller families.
|
|
** link:https://docs.embassy.dev/embassy-nrf/[embassy-nrf], for the Nordic Semiconductor nRF52, nRF53, nRF91 series.
|
|
|
|
* **Networking** - The link:https://docs.embassy.dev/embassy-net/[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 link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] crate provides Bluetooth Low Energy 4.x and 5.x support for nRF52 microcontrollers.
|
|
|
|
* **LoRa** - link:https://docs.embassy.dev/embassy-lora/[embassy-lora] supports LoRa networking on STM32WL wireless microcontrollers and Semtech SX127x transceivers.
|
|
|
|
* **USB** - link:https://docs.embassy.dev/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** - link:https://github.com/embassy-rs/embassy/tree/master/embassy-boot[embassy-boot] is a lightweight bootloader supporting firmware application upgrades in a power-fail-safe way, with trial boots and rollbacks.
|