nordic-dev.net/embassy
2
0
Fork 0
mirror of https://github.com/embassy-rs/embassy.git synced 2024-11-23 07:12:29 +00:00
Code Issues Packages Projects Releases Wiki Activity
3ca01cba8d
embassy/README.md

113 lines
4.5 KiB
Markdown
Raw Normal View History

First commit
2020-09-22 16:03:43 +00:00
# Embassy
Some notes in the readme about docs
2021-12-13 12:23:18 +00:00
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](https://embassy.dev).
First commit
2020-09-22 16:03:43 +00:00
Update README.
2020-09-25 01:50:14 +00:00
## Traits and types
First commit
2020-09-22 16:03:43 +00:00
Update README.
2020-09-25 01:50:14 +00:00
`embassy` provides a set of traits and types specifically designed for `async` usage.
- `embassy::io`: `AsyncBufRead`, `AsyncWrite`. Traits for byte-stream IO, essentially `no_std` compatible versions of `futures::io`.
Move traits to separate crate.
2021-03-01 23:32:23 +00:00
- `embassy::traits::flash`: Flash device trait.
Update README.
2020-09-25 01:50:14 +00:00
- `embassy::time`: `Clock` and `Alarm` traits. Std-like `Duration` and `Instant`.
First commit
2020-09-22 16:03:43 +00:00
- More traits for SPI, I2C, UART async HAL coming soon.
Update readme
2021-01-02 19:13:35 +00:00
## Executor
Update README.
2020-09-25 01:50:14 +00:00
Update readme
2021-01-02 19:13:35 +00:00
The `embassy::executor` module provides an async/await executor designed for embedded usage.
Update README.
2020-09-25 01:50:14 +00:00
- No `alloc`, no heap needed. Task futures are statically allocated.
Update readme
2021-01-02 19:13:35 +00:00
- 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.
Add multi-priority executor example.
2020-09-25 22:36:02 +00:00
- Creating multiple executor instances is supported, to run tasks with multiple priority levels. This allows higher-priority tasks to preempt lower-priority tasks.
Update README.
2020-09-25 01:50:14 +00:00
## 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).
Rust Analyzer documentation Intends to clarify how to make Embassy usable from within Visual Studio Code by assuming the presence of the Rust Analyzer. Note that IntelliJ does not support the Rust Analyzer, so an open question remains as to the whether this is a good move. If it turns out not to be a good move then we should still look at clarifying the use of a workspace file.
2021-12-08 23:40:03 +00:00
## HALs
Update README.
2020-09-25 01:50:14 +00:00
Rust Analyzer documentation Intends to clarify how to make Embassy usable from within Visual Studio Code by assuming the presence of the Rust Analyzer. Note that IntelliJ does not support the Rust Analyzer, so an open question remains as to the whether this is a good move. If it turns out not to be a good move then we should still look at clarifying the use of a workspace file.
2021-12-08 23:40:03 +00:00
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.
First commit
2020-09-22 16:03:43 +00:00
- `uarte`: UARTE driver implementing `AsyncBufRead` and `AsyncWrite`.
- `qspi`: QSPI driver implementing `Flash`.
Update README.
2020-09-25 01:50:14 +00:00
- `gpiote`: GPIOTE driver. Allows `await`ing GPIO pin changes. Great for reading buttons or receiving interrupts from external chips.
Extend SAADC one shot support One-shot mode now permits the sampling of differential pins, and the sampling of multiple pins simultaneously. A new ChannelConfig structure has been introduced so that multiple channels can be configured individually. Further, the `sample` method now accepts a buffer into which samples are written. Along the way, I've reset some default configuration to align with Nordic's settings in their nrfx saadc driver. Specifically, the channel gain defaults to 6 (from 4) and the time defaults to 10us (from 20us).
2021-10-07 07:00:03 +00:00
- `saadc`: SAADC driver. Provides a full implementation of the one-shot sampling for analog channels.
Update README.
2020-09-25 01:50:14 +00:00
- `rtc`: RTC driver implementing `Clock` and `Alarm`, for use with `embassy::executor`.
Improve examples section of readme
2021-06-05 03:31:44 +00:00
## Examples
Update README.
2020-09-25 01:50:14 +00:00
Rust Analyzer documentation Intends to clarify how to make Embassy usable from within Visual Studio Code by assuming the presence of the Rust Analyzer. Note that IntelliJ does not support the Rust Analyzer, so an open question remains as to the whether this is a good move. If it turns out not to be a good move then we should still look at clarifying the use of a workspace file.
2021-12-08 23:40:03 +00:00
Examples are found in the `examples/` folder seperated by the chip manufacturer they are designed to run on. For example:
Improve examples section of readme
2021-06-05 03:31:44 +00:00
* `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.
Update README.
2020-09-25 01:50:14 +00:00
Improve examples section of readme
2021-06-05 03:31:44 +00:00
### Running examples
- Setup git submodules (needed for STM32 examples)
```
git submodule init
git submodule update
```
Update README.
2020-09-25 01:50:14 +00:00
- Install `probe-run` with defmt support.
```
Fix probe-run install command
2021-03-14 20:17:45 +00:00
cargo install probe-run
Update README.
2020-09-25 01:50:14 +00:00
```
Rust Analyzer documentation Intends to clarify how to make Embassy usable from within Visual Studio Code by assuming the presence of the Rust Analyzer. Note that IntelliJ does not support the Rust Analyzer, so an open question remains as to the whether this is a good move. If it turns out not to be a good move then we should still look at clarifying the use of a workspace file.
2021-12-08 23:40:03 +00:00
- Change directory to the sample's base directory. For example:
```
cd examples/nrf
```
Update README.
2020-09-25 01:50:14 +00:00
- Run the example
Rust Analyzer documentation Intends to clarify how to make Embassy usable from within Visual Studio Code by assuming the presence of the Rust Analyzer. Note that IntelliJ does not support the Rust Analyzer, so an open question remains as to the whether this is a good move. If it turns out not to be a good move then we should still look at clarifying the use of a workspace file.
2021-12-08 23:40:03 +00:00
For example:
Update README.
2020-09-25 01:50:14 +00:00
```
Rust Analyzer documentation Intends to clarify how to make Embassy usable from within Visual Studio Code by assuming the presence of the Rust Analyzer. Note that IntelliJ does not support the Rust Analyzer, so an open question remains as to the whether this is a good move. If it turns out not to be a good move then we should still look at clarifying the use of a workspace file.
2021-12-08 23:40:03 +00:00
cargo run --bin blinky
Update README.
2020-09-25 01:50:14 +00:00
```
Rust Analyzer documentation Intends to clarify how to make Embassy usable from within Visual Studio Code by assuming the presence of the Rust Analyzer. Note that IntelliJ does not support the Rust Analyzer, so an open question remains as to the whether this is a good move. If it turns out not to be a good move then we should still look at clarifying the use of a workspace file.
2021-12-08 23:40:03 +00:00
## Developing Embassy with Rust Analyzer based editors
The [Rust Analyzer](https://rust-analyzer.github.io/) is used by [Visual Studio Code](https://code.visualstudio.com/)
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.linkedProjects`setting.
Update README.
2020-09-25 01:50:14 +00:00
## Minimum supported Rust version (MSRV)
Improve examples section of readme
2021-06-05 03:31:44 +00:00
Required nightly version is specified in the `rust-toolchain.toml` file. Nightly is required for:
Update README.
2020-09-25 01:50:14 +00:00
- `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`.
First commit
2020-09-22 16:03:43 +00:00
Update README.
2020-09-25 01:50:14 +00:00
Stable support is a non-goal until these features get stabilized.
First commit
2020-09-22 16:03:43 +00:00
Some notes in the readme about docs
2021-12-13 12:23:18 +00:00
## Documentation
Embassy documentation is located in the `docs/` folder. The documentation is built in [embassy-book](https://github.com/embassy-rs/embassy-book) and published to [https://embassy.dev](https://embassy.dev) by CI.
First commit
2020-09-22 16:03:43 +00:00
## Why the name?
Update README.
2020-09-25 01:50:14 +00:00
EMBedded ASYnc! :)
First commit
2020-09-22 16:03:43 +00:00
## License
This work is licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
Trivial to trigger checks from CI.
2021-07-28 13:09:19 +00:00
Reference in New Issue Copy Permalink