569ecd699d
467: docs: fix some `cargo doc` warnings r=lulf a=numero-744
There are still 3 warnings (below)
```
Documenting embassy v0.1.0 (embassy)
warning: unresolved link to `channel`
--> src/channel/mpsc.rs:241:22
|
241 | /// [`channel`]: channel
| ^^^^^^^ no item named `channel` in scope
|
= note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
= help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
warning: unresolved link to `Task::spawn`
--> src/executor/raw/mod.rs:105:12
|
105 | /// with [`Task::spawn()`], which will fail if it is already spawned.
| ^^^^^^^^^^^^^ no item named `Task` in scope
warning: public documentation for `spawn` links to private item `Executor::spawn`
--> src/executor/raw/mod.rs:156:17
|
156 | /// cause [`Executor::spawn()`] to return the error.
| ^^^^^^^^^^^^^^^^^ this item is private
|
= note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
= note: this link will resolve properly if you pass `--document-private-items`
warning: `embassy` (lib doc) generated 3 warnings
```
Co-authored-by: Côme ALLART <come.allart@etu.emse.fr>
Embassy
Embassy is a project to make async/await a first-class option for embedded development. For more information and instructions to get started, click here.
Traits and types
embassy provides a set of traits and types specifically designed for async usage.
embassy::io:AsyncBufRead,AsyncWrite. Traits for byte-stream IO, essentiallyno_stdcompatible versions offutures::io.embassy::traits::flash: Flash device trait.embassy::time:ClockandAlarmtraits. Std-likeDurationandInstant.- More traits for SPI, I2C, UART async HAL coming soon.
Executor
The embassy::executor module provides an async/await executor designed for embedded usage.
- No
alloc, no heap needed. Task futures are statically allocated. - No "fixed capacity" data structures, executor works with 1 or 1000 tasks without needing config/tuning.
- Integrated timer queue: sleeping is easy, just do
Timer::after(Duration::from_secs(1)).await;. - No busy-loop polling: CPU sleeps when there's no work to do, using interrupts or
WFE/SEV. - Efficient polling: a wake will only poll the woken task, not all of them.
- Fair: a task can't monopolize CPU time even if it's constantly being woken. All other tasks get a chance to run before a given task gets polled for the second time.
- Creating multiple executor instances is supported, to run tasks with multiple priority levels. This allows higher-priority tasks to preempt lower-priority tasks.
Utils
embassy::util contains some lightweight async/await utilities, mainly helpful for async driver development (signaling a task that an interrupt has occured, for example).
embassy-nrf
The embassy-nrf crate contains implementations for nRF 52 series SoCs.
-
uarte: UARTE driver implementingAsyncBufReadandAsyncWrite. -
qspi: QSPI driver implementingFlash. -
gpiote: GPIOTE driver. Allowsawaiting GPIO pin changes. Great for reading buttons or receiving interrupts from external chips. -
saadc: SAADC driver. Provides a full implementation of the one-shot sampling for analog channels. -
rtc: RTC driver implementingClockandAlarm, for use withembassy::executor.
Examples
Examples are found in the examples/ folder seperated by the chip manufacturer they are designed to run on:
examples/nrfare designed to run on thenrf52840-dkboard (PCA10056) but should be easily adaptable to other nRF52 chips and boards.examples/rpare for the RP2040 chip.examples/stm32are designed for the STM32F429ZI chip but should be easily adaptable to other STM32F4xx chips.examples/stdare designed to run locally on your pc.
Running examples
- Setup git submodules (needed for STM32 examples)
git submodule init
git submodule update
- Install
probe-runwith defmt support.
cargo install probe-run
- Run the example
cargo run --bin rtc_async
Minimum supported Rust version (MSRV)
Required nightly version is specified in the rust-toolchain.toml file. Nightly is required for:
generic_associated_types: for trait funcs returning futures.type_alias_impl_trait: for trait funcs returning futures implemented withasync{}blocks, and forstatic-executor.
Stable support is a non-goal until these features get stabilized.
Why the name?
EMBedded ASYnc! :)
License
This work is licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.