Initial commit

docs/troubleshooting.md

@@ -0,0 +1,47 @@
+# Troubleshooting
+
+## Probe Not Found
+
+- Run `probe-rs list`.
+- Check USB cable and power.
+- Check `SWDIO`, `SWCLK`, `GND`, and `3V3`.
+
+## Linux Udev Permissions
+
+- You may need udev rules for ST-Link or your probe.
+- Install the vendor or distro rules, then replug the probe.
+
+## Wrong Chip Selected
+
+- Run `probe-rs chip list | rg STM32F103`.
+- Override the default with `PROBE_RS_CHIP=STM32F103C8`.
+
+## No Firmware Output
+
+- Use `run-04` or `run-08` from `nix develop`.
+- Confirm the firmware did not crash early.
+- Confirm the probe stays attached.
+- Confirm `BOOT0` is low.
+
+## Host Chapter Does Not Run
+
+- Use `run-00`, `run-01`, `run-02`, or `run-03`.
+- If you skipped Nix, make sure `rustup toolchain install 1.95.0` and `rustup target add thumbv7m-none-eabi` are done.
+- If you skipped Nix, make sure `flip-link` is on your `PATH` for embedded builds.
+
+## Blue Pill LED Looks Inverted
+
+- That is expected on most boards.
+- `PC13` is usually active-low, so driving it low turns the LED on.
+
+## Safety
+
+- Check board voltage before connecting anything.
+- Check `SWDIO`, `SWCLK`, `GND`, and `3V3` wiring before flashing.
+- Do not assume a random button or LED pinout without checking the board.
+
+## Contribution
+
+- Keep `nix develop`, `fmt`, `check`, and the chapter build or run aliases working.
+- Document hardware assumptions when they matter.
+- Do not claim hardware-tested behavior unless it was actually tested on hardware.