aboutsummaryrefslogtreecommitdiff
path: root/docs/modules/ROOT/pages/basic_application.adoc
diff options
context:
space:
mode:
Diffstat (limited to 'docs/modules/ROOT/pages/basic_application.adoc')
-rw-r--r--docs/modules/ROOT/pages/basic_application.adoc81
1 files changed, 0 insertions, 81 deletions
diff --git a/docs/modules/ROOT/pages/basic_application.adoc b/docs/modules/ROOT/pages/basic_application.adoc
deleted file mode 100644
index 95792d5a0..000000000
--- a/docs/modules/ROOT/pages/basic_application.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
1= A basic Embassy application
2
3So 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.
4
5== Main
6
7The full example can be found link:https://github.com/embassy-rs/embassy/tree/master/docs/modules/ROOT/examples/basic[here].
8
9NOTE: If you’re using VS Code and rust-analyzer to view and edit the examples, you may need to make some changes to `.vscode/settings.json` to tell it which project we’re working on. Follow the instructions commented in that file to get rust-analyzer working correctly.
10
11=== Bare metal
12
13The first thing you’ll notice are two attributes at the top of the file. These tells the compiler that program has no access to std, and that there is no main function (because it is not run by an OS).
14
15[source,rust]
16----
17include::example$basic/src/main.rs[lines="1..2"]
18----
19
20=== Rust Nightly
21
22The next declaration is a Rust Unstable feature, which means that Embassy requires Rust Nightly:
23
24[source,rust]
25----
26include::example$basic/src/main.rs[lines="3"]
27----
28
29=== Dealing with errors
30
31Then, 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:
32
33[source,rust]
34----
35include::example$basic/src/main.rs[lines="10"]
36----
37
38=== Task declaration
39
40After a bit of import declaration, the tasks run by the application should be declared:
41
42[source,rust]
43----
44include::example$basic/src/main.rs[lines="12..20"]
45----
46
47An 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.
48
49NOTE: 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.
50
51=== Main
52
53The main entry point of an Embassy application is defined using the `#[embassy_executor::main]` macro. The entry point is passed a `Spawner`, which it can use to spawn other tasks.
54
55We then initialize the HAL with a default config, which gives us a `Peripherals` struct we can use to access the MCU’s various peripherals. In this case, we want to configure one of the pins as a GPIO output driving the LED:
56
57[source,rust]
58----
59include::example$basic/src/main.rs[lines="22..-1"]
60----
61
62What happens when the `blinker` task has 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_executor::main]` macro. The macro does the following:
63
64. Creates an Embassy Executor
65. Defines a main task for the entry point
66. Runs the executor spawning the main task
67
68There is also a way to run the executor without using the macro, in which case you have to create the `Executor` instance yourself.
69
70== The Cargo.toml
71
72The project definition needs to contain the embassy dependencies:
73
74[source,toml]
75----
76include::example$basic/Cargo.toml[lines="9..11"]
77----
78
79Depending on your microcontroller, you may need to replace `embassy-nrf` with something else (`embassy-stm32` for STM32. Remember to update feature flags as well).
80
81In this particular case, the nrf52840 chip is selected, and the RTC1 peripheral is used as the time driver.