From 990b44566ce1393a4a553a65d5a6c412cb656805 Mon Sep 17 00:00:00 2001
From: Barnaby Walters <barnaby@waterpigs.co.uk>
Date: Wed, 28 Feb 2024 15:11:30 +0100
Subject: [docs] Added some failure modes to watch out for

* Linked to probe.rs website rather than the crates.io page
* Fixed some formatting errors (>:( grrr asciidoc)
* Added cargo add probe-rs failure mode
* Added pico-w vs pico blinky failure mode
---
 docs/modules/ROOT/pages/getting_started.adoc | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

(limited to 'docs/modules/ROOT/pages/getting_started.adoc')

diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/modules/ROOT/pages/getting_started.adoc
index 24bde1c1f..be2b868eb 100644
--- a/docs/modules/ROOT/pages/getting_started.adoc
+++ b/docs/modules/ROOT/pages/getting_started.adoc
@@ -3,7 +3,7 @@
 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.
+* link:https://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.
 
@@ -82,19 +82,19 @@ If everything worked correctly, you should see a blinking LED on your board, and
 └─ 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.
+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:
+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)
+* 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:
+If you are trying to run an example with `+cargo run --release+` and you see the following output:
 [source]
 ----
 0.000000 INFO Hello World!
@@ -115,6 +115,20 @@ To get rid of the frame-index error add the following to your `Cargo.toml`:
 debug = 2
 ----
 
+If you’re get an extremely long error message containing something like the following:
+
+[source]
+----
+error[E0463]: can't find crate for `std`
+  |
+  = note: the `thumbv6m-none-eabi` target may not support the standard library
+  = note: `std` is required by `stable_deref_trait` because it does not declare `#![no_std]`
+----
+
+Make sure that you didn’t accidentally run `+cargo add probe-rs+` (which adds it as a dependency) instead of link:https://probe.rs/docs/getting-started/installation/[correctly installing probe-rs].
+
+If you’re using a raspberry pi pico-w, make sure you’re running `+cargo run --bin wifi_blinky --release+` rather than the regular blinky. The pico-w’s on-board LED is connected to the WiFi chip, which needs to be initialized before the LED can be blinked.
+
 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?
-- 
cgit 


From 2787164ea9ba30f806d6c38443d2eca2984b1e62 Mon Sep 17 00:00:00 2001
From: Barnaby Walters <barnaby@waterpigs.co.uk>
Date: Wed, 28 Feb 2024 15:15:43 +0100
Subject: grammar fix

---
 docs/modules/ROOT/pages/getting_started.adoc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs/modules/ROOT/pages/getting_started.adoc')

diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/modules/ROOT/pages/getting_started.adoc
index be2b868eb..e8bc84255 100644
--- a/docs/modules/ROOT/pages/getting_started.adoc
+++ b/docs/modules/ROOT/pages/getting_started.adoc
@@ -115,7 +115,7 @@ To get rid of the frame-index error add the following to your `Cargo.toml`:
 debug = 2
 ----
 
-If you’re get an extremely long error message containing something like the following:
+If you’re getting an extremely long error message containing something like the following:
 
 [source]
 ----
-- 
cgit 


From d07a0148d759fa09ba1ee8dc4810bb4edd8bda49 Mon Sep 17 00:00:00 2001
From: Barnaby Walters <barnaby@waterpigs.co.uk>
Date: Wed, 28 Feb 2024 15:48:37 +0100
Subject: Documented rp2040 probe-rs info bug, linked to new_project page

---
 docs/modules/ROOT/pages/getting_started.adoc | 3 +++
 1 file changed, 3 insertions(+)

(limited to 'docs/modules/ROOT/pages/getting_started.adoc')

diff --git a/docs/modules/ROOT/pages/getting_started.adoc b/docs/modules/ROOT/pages/getting_started.adoc
index e8bc84255..73cb5530d 100644
--- a/docs/modules/ROOT/pages/getting_started.adoc
+++ b/docs/modules/ROOT/pages/getting_started.adoc
@@ -129,6 +129,8 @@ Make sure that you didn’t accidentally run `+cargo add probe-rs+` (which adds
 
 If you’re using a raspberry pi pico-w, make sure you’re running `+cargo run --bin wifi_blinky --release+` rather than the regular blinky. The pico-w’s on-board LED is connected to the WiFi chip, which needs to be initialized before the LED can be blinked.
 
+If you’re using an rp2040 debug probe (e.g. the pico probe) and are having issues after running `probe-rs info`, unplug and reconnect the probe, letting it power cycle. Running `probe-rs info` is link:https://github.com/probe-rs/probe-rs/issues/1849[known to put the pico probe into an unusable state].
+
 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?
@@ -138,3 +140,4 @@ Congratulations, you have your first Embassy application running! Here are some
 * Read more about the xref:runtime.adoc[executor].
 * Read more about the xref:hal.adoc[HAL].
 * Start xref:basic_application.adoc[writing your application].
+* Learn how to xref:new_project.adoc[start a new embassy project by adapting an example].
-- 
cgit 

