Files
.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-nrf
embassy-rp
embassy-stm32
embassy-sync
embassy-time
embassy-usb
embassy-usb-hid
embassy-usb-ncm
embassy-usb-serial
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
embassy/docs/modules/ROOT/pages/basic_application.adoc
Ulf Lilleengen d769e562c0 Rewrite documentation using correct module names
* Remove traits section now that we have embedded-hal-async and refer to
  it.
* Explanation that embassy is multiple things.
* Bootloader description image
2022-08-16 11:27:57 +02:00

85 lines
3.3 KiB
Plaintext

= A basic Embassy application
So you've got one of the xref:examples.adoc[examples] running, but what now? Let's go through a simple Embassy application for the nRF52 DK to understand it better.
== Main
The full example can be found link:https://github.com/embassy-rs/embassy/tree/master/docs/modules/ROOT/examples/basic[here].
=== Rust Nightly
The first thing you'll notice is a few declarations stating that Embassy requires some nightly features:
[source,rust]
----
include::example$basic/src/main.rs[lines="1..3"]
----
=== Dealing with errors
Then, what follows are some declarations on how to deal with panics and faults. During development, a good practice is to rely on `defmt-rtt` and `panic-probe` to print diagnostics to the terminal:
[source,rust]
----
include::example$basic/src/main.rs[lines="11..12"]
----
=== Task declaration
After a bit of import declaration, the tasks run by the application should be declared:
[source,rust]
----
include::example$basic/src/main.rs[lines="13..22"]
----
An embassy task must be declared `async`, and may NOT take generic arguments. In this case, we are handed the LED that should be blinked and the interval of the blinking.
NOTE: Notice that there is no busy waiting going on in this task. It is using the Embassy timer to yield execution, allowing the microcontroller to sleep in between the blinking.
=== Main
The main entry point of an Embassy application is defined using the `#[embassy_executor::main]` macro. The entry point is also required to take a `Spawner` and a `Peripherals` argument.
The `Spawner` is the way the main application spawns other tasks. The `Peripherals` type comes from the HAL and holds all peripherals that the application may use. In this case, we want to configure one of the pins as a GPIO output driving the LED:
[source,rust]
----
include::example$basic/src/main.rs[lines="23..-1"]
----
`#[embassy_executor::main]` takes an optional `config` parameter specifying a function that returns an instance of HAL's `Config` struct. For example:
```rust
fn embassy_config() -> embassy_nrf::config::Config {
embassy_nrf::config::Config::default()
}
#[embassy_executor::main(config = "embassy_config()")]
async fn main(_spawner: Spawner, p: embassy_nrf::Peripherals) {
// ...
}
```
What happens when the `blinker` task have been spawned and main returns? Well, the main entry point is actually just like any other task, except that you can only have one and it takes some specific type arguments. The magic lies within the `#[embassy::main]` macro. The macro does the following:
. Creates an Embassy Executor
. Initializes the microcontroller HAL to get the `Peripherals`
. Defines a main task for the entry point
. Runs the executor spawning the main task
There is also a way to run the executor without using the macro, in which case you have to create the `Executor` instance yourself.
== The Cargo.toml
The project definition needs to contain the embassy dependencies:
[source,toml]
----
include::example$basic/Cargo.toml[lines="8..9"]
----
Depending on your microcontroller, you may need to replace `embassy-nrf` with something else (`embassy-stm32` for STM32. Remember to update feature flags as well).
In this particular case, the nrf52840 chip is selected, and the RTC1 peripheral is used as the time driver.