# 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
