a76dd2d70f
New: delaying_a_task.adoc, copied as-is from the wiki and placed in the navigation until we have a better place for it (or remove/replace it) index: Tweaked the structure, added some content from the wiki, and made some general copy edits to improve clarity. getting_started.adoc: Corrected various out-of-date information, added troubleshooting tips from the wiki, added some new information, various other small edits. basic_application.adoc: Corrected out-of-date information, various clarifications and edits. After these changes, IMO most of the content on the github wiki is no longer necessary and can be removed for clarity. The few sections I didn‘t integrate or copy over were either out of date or unfinished.
127 lines
5.9 KiB
Plaintext
127 lines
5.9 KiB
Plaintext
= Getting started
|
||
|
||
So you want to try Embassy, great! To get started, there are a few tools you need to install:
|
||
|
||
* link:https://rustup.rs/[rustup] - the Rust toolchain is needed to compile Rust code.
|
||
* link:https://crates.io/crates/probe-rs[probe-rs] - to flash the firmware on your device. If you already have other tools like `OpenOCD` setup, you can use that as well.
|
||
|
||
If you don't have any supported board, don't worry: you can also run embassy on your PC using the `std` examples.
|
||
|
||
== Getting a board with examples
|
||
|
||
Embassy supports many microcontroller families, but the quickest way to get started is by using a board which Embassy has existing example code for.
|
||
|
||
This list is non-exhaustive. If your board isn’t included here, check the link:https://github.com/embassy-rs/embassy/tree/main/examples[examples folder] to see if example code has been written for it.
|
||
|
||
=== nRF kits
|
||
|
||
* link:https://www.nordicsemi.com/Products/Development-hardware/nrf52-dk[nRF52 DK]
|
||
* link:https://www.nordicsemi.com/Products/Development-hardware/nRF9160-DK[nRF9160 DK]
|
||
|
||
=== STM32 kits
|
||
|
||
* link:https://www.st.com/en/evaluation-tools/nucleo-h743zi.html[STM32 Nucleo-144 development board with STM32H743ZI MCU]
|
||
* link:https://www.st.com/en/evaluation-tools/nucleo-f429zi.html[STM32 Nucleo-144 development board with STM32F429ZI MCU]
|
||
* link:https://www.st.com/en/evaluation-tools/b-l4s5i-iot01a.html[STM32L4+ Discovery kit IoT node, low-power wireless, BLE, NFC, WiFi]
|
||
* link:https://www.st.com/en/evaluation-tools/b-l072z-lrwan1.html[STM32L0 Discovery kit LoRa, Sigfox, low-power wireless]
|
||
* link:https://www.st.com/en/evaluation-tools/nucleo-wl55jc.html[STM32 Nucleo-64 development board with STM32WL55JCI MCU]
|
||
* link:https://www.st.com/en/evaluation-tools/b-u585i-iot02a.html[Discovery kit for IoT node with STM32U5 series]
|
||
|
||
|
||
=== RP2040 kits
|
||
|
||
* link:https://www.raspberrypi.com/products/raspberry-pi-pico/[Raspberry Pi Pico]
|
||
|
||
=== ESP32
|
||
|
||
* link:https://github.com/esp-rs/esp-rust-board[ESP32C3]
|
||
|
||
== Running an example
|
||
|
||
First you need to clone the link:https://github.com/embassy-rs/embassy[github repository];
|
||
|
||
[source, bash]
|
||
----
|
||
git clone https://github.com/embassy-rs/embassy.git
|
||
cd embassy
|
||
----
|
||
|
||
Once you have a copy of the repository, find examples folder for your board and, and build an example program. `blinky` is a good choice as all it does is blink an LED – the embedded world’s equivalent of “Hello World”.
|
||
|
||
[source, bash]
|
||
----
|
||
cd examples/nrf52840
|
||
cargo build --bin blinky --release
|
||
----
|
||
|
||
Once you’ve confirmed you can build the example, connect your computer to your board with a debug probe and run it on hardware:
|
||
|
||
[source, bash]
|
||
----
|
||
cargo run --bin blinky --release
|
||
----
|
||
|
||
If everything worked correctly, you should see a blinking LED on your board, and debug output similar to this on your computer:
|
||
|
||
[source]
|
||
----
|
||
Finished dev [unoptimized + debuginfo] target(s) in 1m 56s
|
||
Running `probe-run --chip STM32F407VGTx target/thumbv7em-none-eabi/debug/blinky`
|
||
(HOST) INFO flashing program (71.36 KiB)
|
||
(HOST) INFO success!
|
||
────────────────────────────────────────────────────────────────────────────────
|
||
0 INFO Hello World!
|
||
└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:18
|
||
1 INFO high
|
||
└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:23
|
||
2 INFO low
|
||
└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:27
|
||
3 INFO high
|
||
└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:23
|
||
4 INFO low
|
||
└─ blinky::__embassy_main::task::{generator#0} @ src/bin/blinky.rs:27
|
||
----
|
||
|
||
NOTE: How does the `cargo run` command know how to connect to our board and program it? In each `examples` folder, there’s a `.cargo/config.toml` file which tells cargo to use link:https://probe.rs/[probe-rs] as the runner for ARM binaries in that folder. probe-rs handles communication with the debug probe and MCU. In order for this to work, probe-rs needs to know which chip it’s programming, so you’ll have to edit this file if you want to run examples on other chips.
|
||
|
||
=== It didn’t work!
|
||
|
||
If you hare having issues when running `cargo run --release`, please check the following:
|
||
|
||
* You are specifying the correct `--chip on the command line``, OR
|
||
* You have set `.cargo/config.toml`'s run line to the correct chip, AND
|
||
* You have changed `examples/Cargo.toml`'s HAL (e.g. embassy-stm32) dependency's feature to use the correct chip (replace the existing stm32xxxx feature)
|
||
|
||
At this point the project should run. If you do not see a blinky LED for blinky, for example, be sure to check the code is toggling your board's LED pin.
|
||
|
||
If you are trying to run an example with `cargo run --release` and you see the following output:
|
||
[source]
|
||
----
|
||
0.000000 INFO Hello World!
|
||
└─ <invalid location: defmt frame-index: 14>
|
||
0.000000 DEBUG rcc: Clocks { sys: Hertz(80000000), apb1: Hertz(80000000), apb1_tim: Hertz(80000000), apb2: Hertz(80000000), apb2_tim: Hertz(80000000), ahb1: Hertz(80000000), ahb2: Hertz(80000000), ahb3: Hertz(80000000) }
|
||
└─ <invalid location: defmt frame-index: 124>
|
||
0.000061 TRACE allocating type=Interrupt mps=8 interval_ms=255, dir=In
|
||
└─ <invalid location: defmt frame-index: 68>
|
||
0.000091 TRACE index=1
|
||
└─ <invalid location: defmt frame-index: 72>
|
||
----
|
||
|
||
To get rid of the frame-index error add the following to your `Cargo.toml`:
|
||
|
||
[source,toml]
|
||
----
|
||
[profile.release]
|
||
debug = 2
|
||
----
|
||
|
||
If you’re still having problems, check the link:https://embassy.dev/book/dev/faq.html[FAQ], or ask for help in the link:https://matrix.to/#/#embassy-rs:matrix.org[Embassy Chat Room].
|
||
|
||
== What's next?
|
||
|
||
Congratulations, you have your first Embassy application running! Here are some suggestions for where to go from here:
|
||
|
||
* Read more about the xref:runtime.adoc[executor].
|
||
* Read more about the xref:hal.adoc[HAL].
|
||
* Start xref:basic_application.adoc[writing your application].
|