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].