rust: probe-flash.md — flash+defmt via Pi Debug Probe in a Silverblue toolbox

Verified workflow (not first-principles): host udev rules with uaccess ACL (maps by UID
into the toolbox; group access shows nobody:nobody), prebuilt probe-rs in the toolbox,
probe-rs run --chip RP235x pm-kit.elf for flash+RTT defmt streaming.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

rust/probe-flash.md

@@ -0,0 +1,76 @@
+# Flashing & debugging pm-kit with the Raspberry Pi Debug Probe
+
+How to flash the Rust RP2350 firmware (`rust/pm-kit`) and watch its `defmt` logs live, from a
+**Fedora Silverblue `toolbox`**. This replaces the BOOTSEL/UF2 drag for development — over SWD you
+get one-command flash + reset + RTT log streaming, and panics print their message and `file:line`.
+
+Wiring and chip name were verified against the official docs (links at the bottom); don't guess them.
+
+## 0. Hardware wiring (once)
+
+- **Probe "D" port → Pico 2 DEBUG connector** with the included 3-pin JST-SH cable
+  (SC=SWCLK / SD=SWDIO / GND — connector is keyed). The "U" port is UART, not used here.
+- **Probe USB → computer.**  **Pico 2 USB → power** (the probe does SWD only, not power).
+- Connect **GND first** when the target is separately powered.
+- If `probe-rs` can't see the chip later, the **probe's own firmware** may predate the Pico 2 —
+  update it: hold BOOTSEL on the *probe*, plug it in (mounts `RPI-RP2`), drag the latest
+  `debugprobe.uf2` from github.com/raspberrypi/debugprobe/releases.
+
+## 1. Host udev rules (once, on the Silverblue HOST — not inside toolbox)
+
+The host's `udevd` sets the device permissions; the rule's `TAG+="uaccess"` grants *your UID* an
+ACL, which is what maps correctly into the toolbox (group-based access shows as `nobody:nobody`).
+
+```sh
+sudo curl -L https://probe.rs/files/69-probe-rs.rules -o /etc/udev/rules.d/69-probe-rs.rules
+sudo udevadm control --reload
+sudo udevadm trigger
+# then unplug/replug the probe
+```
+(`/etc` is writable on Silverblue. If your terminal opens inside a toolbox, run these on the host,
+e.g. `flatpak-spawn --host sudo …`.)
+
+## 2. Install probe-rs in the toolbox (once)
+
+```sh
+toolbox enter                       # or: toolbox create probe && toolbox enter probe
+sudo dnf install -y libusb1         # runtime lib the prebuilt binary links against
+curl --proto '=https' --tlsv1.2 -LsSf \
+  https://github.com/probe-rs/probe-rs/releases/latest/download/probe-rs-tools-installer.sh | sh
+# follow the installer's PATH note (it lands in ~/.cargo/bin) or restart the shell
+probe-rs --version
+probe-rs list                       # should show the CMSIS-DAP Debug Probe
+```
+
+## 3. Flash + watch logs
+
+```sh
+curl -O https://metronome.varasys.io/pm-kit.elf
+probe-rs run --chip RP235x pm-kit.elf
+```
+`probe-rs run` flashes the ELF, resets, and streams `defmt` over RTT. We ship the **ELF** (not the
+UF2) because defmt decodes its log strings from the ELF's symbol table. The firmware narrates:
+`== pm-kit boot ==` → `display init ok` → `parsed groove 0` → `entering main loop` →
+`alive: …` (~2×/sec). A `panic`/`HardFault` prints its location.
+
+> Building from source instead of the prebuilt ELF? `.cargo/config.toml` already sets
+> `runner = "probe-rs run --chip RP235x"`, so inside the **pm-rust build image** `cargo run --release`
+> does build+flash+log in one — but that image needs probe-rs + USB passthrough too; the toolbox
+> route above is simpler for just flashing what we ship.
+
+## Troubleshooting
+
+- **`No probe was found`** → udev rules not applied (re-plug after step 1), or the device shows
+  `nobody:nobody` in the toolbox. Quick unblock without re-plugging:
+  `sudo setfacl -m u:$USER:rw $(readlink -f /dev/serial/by-id/*Debug_Probe* 2>/dev/null)` on the host,
+  or just run `sudo probe-rs run …` inside the toolbox (it's privileged, so root can open the node).
+- **`chip RP235x not found`** → your probe-rs is too old (RP2350 support landed Feb 2025);
+  reinstall. Confirm the exact name with `probe-rs chip list | grep -i rp23`.
+- **Connects but can't halt/flash the core** → update the **probe firmware** (step 0).
+
+## References
+- Raspberry Pi Debug Probe docs — https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html
+- probe-rs install — https://probe.rs/docs/getting-started/installation/
+- probe-rs probe setup / udev — https://probe.rs/docs/getting-started/probe-setup/
+- probe-rs RP235x support — https://github.com/probe-rs/probe-rs/issues/2787
+- Toolbox USB ACL gotcha — https://discussion.fedoraproject.org/t/accessing-a-usb-device-in-toolbox-via-udev-rule/127904