Initial commit

docs/blue-pill.md

@@ -0,0 +1,42 @@
+# Blue Pill Notes
+
+## Baseline
+
+- Board: STM32F103C8T6 Blue Pill
+- Core: Cortex-M3
+- Default target: `thumbv7m-none-eabi`
+
+## LED
+
+- Most Blue Pill boards wire the onboard LED to `PC13`
+- It is usually active-low
+- `set_low()` usually turns it on
+- `set_high()` usually turns it off
+
+## RGB LED
+
+- `PA0` = GND, drive low
+- `PA1` = red
+- `PA2` = green
+- `PA3` = blue
+- The RGB examples use these pins as a visible status output
+
+## 5-Way Button Board
+
+- `PB12` = GND, drive low
+- `PA10` = VCC, drive high
+- `PB13` = right
+- `PB14` = down
+- `PB15` = left
+- `PA8` = center
+- `PA9` = up
+- Assumption: the button inputs read high when pressed
+- The workshop uses `PA8` as the default center button in the simplest examples
+- TODO: flip the input polarity if your module is active-low instead
+
+## Probe Wiring
+
+- `SWDIO` -> `SWDIO`
+- `SWCLK` -> `SWCLK`
+- `GND` -> `GND`
+- `3V3` -> `3V3` reference

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.