max/embassy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Modern embedded framework, using Rust and async.
2,028 Commits 67 Branches 32 Tags 16 MiB
Rust 98.9%
Shell 0.9%
Python 0.2%
1d265b73b2
Go to file
bors[bot] 1d265b73b2
Merge #601 
601: [part 1/n] Change macrotables to build.rs codegen r=lulf a=Dirbaio

This PR replaces the "macrotables" (the macros like `stm32_data::peripherals!`) with a `const METADATA`.

Macrotables had some problems:

- Hard to debug
- Somewhat footgunny (typo the "pattern" and then nothing matches and the macro now expands to nothing, silently!)
- Limited power
  - Can't count, so we had to add a [special macrotable for that](f50f3f0a73/embassy-stm32/src/dma/bdma.rs (L26)).
  - Can't remove duplicates, so we had to fallback to [Rust code in build.rs](f50f3f0a73/embassy-stm32/build.rs (L105-L145))
  - Can't include the results as a listto another macro, so again [build.rs](https://github.com/embassy-rs/embassy/blob/master/embassy-stm32/build.rs#L100-L101).

They work fine for the 95% of cases, but for the remaining 5% we need Rust code in build.rs. So we might as well do everything with Rust code, so everything is consistent.

The new approach generates a `const METADATA: Metadata = Metadata { ... }` with [these structs](https://github.com/embassy-rs/embassy/blob/unmacrotablize/stm32-metapac-gen/src/assets/metadata.rs) in `stm32-metapac`. `build.rs` can then read that and generate whatever code.


Co-authored-by: Dario Nieuwenhuis <dirbaio@dirbaio.net>
2022-02-09 15:27:35 +00:00
.github stm32: add gpio HIL test 2021-12-06 22:05:41 +01:00
.vscode Add all example crates to linked projects (commented out) 2021-12-09 19:44:41 -06:00
docs traits: migrate Delay to embedded-hal 1.0+async, remove Rng and Flash. 2022-01-27 00:08:02 +01:00
embassy traits: migrate Delay to embedded-hal 1.0+async, remove Rng and Flash. 2022-01-27 00:08:02 +01:00
embassy-boot Address review comments 2022-02-09 12:46:46 +01:00
embassy-hal-common Fix typo in defuse doc comment 2022-01-14 12:49:37 +01:00
embassy-lora Support unstable-trait feature for stm32 2022-01-26 22:39:06 +01:00
embassy-macros macros: initialize chip before executor. 2022-01-05 13:30:46 +01:00
embassy-net Use smoltcp 0.8.0 from crates.io. 2021-12-12 15:32:36 +01:00
embassy-nrf Upgrade to embedded-storage 0.3.0 2022-02-07 12:35:58 +01:00
embassy-rp Update rust-toolchain 2021-12-16 11:34:20 +01:00
embassy-stm32 Merge #601 2022-02-09 15:27:35 +00:00
embassy-traits Add embassy-boot 2022-02-09 10:50:29 +01:00
examples Add embassy-boot 2022-02-09 10:50:29 +01:00
stm32-data@b665a72922 Update stm32-data 2022-02-07 23:13:44 +01:00
stm32-gen-features [manual] Add stm32f3 family to stm32-gen-features 2021-12-13 13:49:41 +05:30
stm32-metapac stm32-metapac: add option to generate chip metadata as a rust const. 2022-02-09 00:28:05 +01:00
stm32-metapac-gen stm32: replace peripheral_rcc! macrotable with build.rs 2022-02-09 00:58:17 +01:00
tests/stm32 traits: migrate Delay to embedded-hal 1.0+async, remove Rng and Flash. 2022-01-27 00:08:02 +01:00
xtask Update lots of deps 2021-09-11 01:35:23 +02:00
.gitignore Enable running ci.sh locally multiple-times. 2021-12-09 12:37:44 +01:00
.gitmodules Add stm32-metapac crate, with codegen in rust 2021-05-31 02:40:58 +02:00
ci.sh Add unstable-traits for stm32 to CI 2022-01-26 22:49:45 +01:00
LICENSE-APACHE First commit 2020-09-22 18:03:43 +02:00
LICENSE-MIT First commit 2020-09-22 18:03:43 +02:00
README.md traits: migrate Delay to embedded-hal 1.0+async, remove Rng and Flash. 2022-01-27 00:08:02 +01:00
rust-toolchain.toml Update rust-toolchain 2021-12-16 11:34:20 +01:00

README.md

Embassy

Embassy is a project to make async/await a first-class option for embedded development. For more information and instructions to get started, go to https://embassy.dev.

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

HALs

Hardware Absraction Layers with asynchronous behaviors are provided for a variety of platforms. For example, the embassy-nrf crate contains implementations for nRF 52 series SoCs.

  • uarte: UARTE driver implementing AsyncBufRead and AsyncWrite.

  • qspi: QSPI driver implementing Flash.

  • gpiote: GPIOTE driver. Allows awaiting 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 implementing Clock and Alarm, for use with embassy::executor.

Examples

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

  • examples/nrf are designed to run on the nrf52840-dk board (PCA10056) but should be easily adaptable to other nRF52 chips and boards.
  • examples/rp are for the RP2040 chip.
  • examples/stm32 are designed for the STM32F429ZI chip but should be easily adaptable to other STM32F4xx chips.
  • 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/nrf
  • 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)

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 with async{} blocks, and for static-executor.

Stable support is a non-goal until these features get stabilized.

Documentation

Embassy documentation is located in the docs/ folder. The documentation is built in embassy-book and published to https://embassy.dev by CI.

Why the name?

EMBedded ASYnc! :)

License

This work is licensed under either of

at your option.