add troubleshooting section

embedded-workshop-book/src/SUMMARY.md

@@ -46,4 +46,10 @@
     - [Next Steps](./next-steps.md)
     - [String Descriptors](./string-descriptors.md)
     - [Custom Control Transfers](./custom-control-transfers.md)
-- [References and Resources](./references-resources.md)
+- [References and Resources](./references-resources.md)
+- [Troubleshooting](./troubleshooting.md)
+    - [`cargo-size` is not working](./troubleshoot-cargo-size.md)
+    - [`cargo-flash` is not working](./troubleshoot-cargo-flash.md)
+    - [Rust analyzer is not working](./troubleshoot-rust-analyzer.md)
+    - [`cargo-build` fails to link](./troubleshoot-cargo-build.md)
+    - [`dongle-flash` is not working](./troubleshoot-dongle-flash.md)

embedded-workshop-book/src/troubleshoot-cargo-build.md

@@ -0,0 +1,3 @@
+# `cargo-build` fails to link
+
+If you have configured Cargo to use sscache then you'll need to disable sscache support. Unset the `RUSTC_WRAPPER` variable in your environment *before* opening VS code. Run `cargo clean` from the Cargo workspace you are working from (`beginner/apps` or `advanced/firmware`). Then open VS code.

embedded-workshop-book/src/troubleshoot-cargo-flash.md

@@ -0,0 +1,45 @@
+# `cargo-flash` is not working
+
+## Debug power request failed
+
+``` console
+$ cargo flash --chip nRF52840_xxAA --bin hello
+ ERROR probe_rs::architecture::arm::communication_interface > Debug power request failed
+Error processing command: An error specific to the selected architecture occured
+```
+
+This is a spurious error that occurs only once on a new development kit. Running the command again should make the error go away. If you still get the error run `RUST_LOG=probe_rs=debug cargo flash --chip nRF52840_xxAA --bin hello ` once.
+
+## 'erase_sector' failed with code 1
+
+``` console
+$ cargo flash --chip nRF52840_xxAA --bin hello
+(..)
+Error failed to flash app: The execution of 'erase_sector' failed with code 1
+```
+
+flash write protection is enabled in the device. To disable it use the `nrf-recover` tool. Instructions can be found in the [setup page](https://oxidizeconf.com/oxidize-global-setup/) and in the top-level README of this repository.
+
+## Linux permissions
+
+``` console
+$ cargo flash --chip nRF52840_xxAA --bin hello
+Error: An error specific to a probe type occured: USB error while opening USB device: Access denied (insufficient permissions)
+
+Caused by:
+    USB error while opening USB device: Access denied (insufficient permissions)
+```
+
+udev rules need to be changed to allow non-root access. Instructions can be found in the [setup page](https://oxidizeconf.com/oxidize-global-setup/) and in the top-level README of this repository.
+
+## Wrong Windows Driver
+
+``` console
+$ cargo flash --chip nRF52840_xxAA --bin hello
+Error: An error specific to a probe type occured: USB error while opening USB device: Entity not found
+
+Caused by:
+    USB error while opening USB device: Entity not found
+```
+
+You need to bind the BULK interface of the J-Link USB device to the WinUSB driver using the Zadig tool. Instructions can be found in the [setup page](https://oxidizeconf.com/oxidize-global-setup/) and in the top-level README of this repository.

embedded-workshop-book/src/troubleshoot-cargo-size.md

@@ -0,0 +1,9 @@
+# `cargo-size` is not working
+
+```
+$ cargo size --bin hello
+Failed to execute tool: size
+No such file or directory (os error 2)
+```
+
+`llvm-tools-preview` is not installed. Install it with `rustup component add llvm-tools-preview`

embedded-workshop-book/src/troubleshoot-dongle-flash.md

@@ -0,0 +1,9 @@
+# `dongle-flash` not working
+
+``` console
+$ dongle-flash loopback.hex
+packaging iHex using nrfutil ...
+Error: No such file or directory (os error 2)
+```
+
+this indicates that `nrfutil`, the Python tool, is not installed or not available in your PATH. Instructions on how to install `nrfutil` can be found in the [setup page](https://oxidizeconf.com/oxidize-global-setup/) and in the top-level README of this repository. If you install `nrfutil` in a virtual environment you'll need to activate the environment; the `nrfutil` binary must be available in your PATH.

embedded-workshop-book/src/troubleshoot-rust-analyzer.md

@@ -0,0 +1,9 @@
+# Rust-Analyzer is not working
+
+If Rust-Analyzer is not analyzing your code, that is you get no type annotations, no "Run" button and no syntax hightlighting then:
+
+- check that you have a single folder open in VS code; this is different from a single-folder VS code workspace. First close all the currently open folders then open a single folder using the 'File > Open Folder' menu. The open folder should be the `beginner/apps` folder for the beginner workshop or the `advanced/firmware` folder for the advanced workshop.
+
+- use the latest version of the Rust-Analyzer plugin. If you get a prompt to update the Rust-Analyzer extension hen you start VS code accept it. You may also get a prompt about updating the Rust-Analayzer binary; accept that one too. The extension should restart automatically after the update. If it doesn't then close and re-open VS code.
+
+- You may need to wait a little while Rust-Analyzer analyzes all the crates in the dependency graph. Then you may need to modify and save the currently open file to force Rust-Analyzer to analyze it.

embedded-workshop-book/src/troubleshooting.md

@@ -0,0 +1,3 @@
+# Troubleshooting
+
+If you have issues with any of the tools used in this workshop check out the sections in this chapter.