Moved content from the wiki to the docs

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.

1 files changed, 69 insertions, 4 deletions

diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/modules/ROOT/pages/getting_started.adoc
index 2c6f4b1ee..ab819ac2a 100644
--- a/docs/modules/ROOT/pages/getting_started.adoc
+++ b/docs/modules/ROOT/pages/getting_started.adoc
@@ -9,7 +9,9 @@ If you don't have any supported board, don't worry: you can also run embassy on
 
 == Getting a board with examples
 
-Embassy supports many microcontroller families, but the easiest ways to get started is if you have one of the more common development kits.
+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
 
@@ -36,7 +38,7 @@ Embassy supports many microcontroller families, but the easiest ways to get star
 
 == Running an example
 
-First you need to clone the [github repository];
+First you need to clone the link:https://github.com/embassy-rs/embassy[github repository];
 
 [source, bash]
 ----
@@ -44,17 +46,80 @@ git clone https://github.com/embassy-rs/embassy.git
 cd embassy
 ----
 
-You can run an example by opening a terminal and entering the following commands:
+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 alternatives on where to go from here:
+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].