First commit

docs/combined-test-plan-2026-07-22.md

@@ -110,6 +110,47 @@ lands].
 2. ❑ Mobile Home: wallet card directly under My Apps (G5 from the voice epic).
 3. ❑ Mesh RF settings panel (Mesh → Device) still loads and saves.
 
+## H. LoRa radio firmware flashing (Heltec V3/V4, new — extends Section E)
+
+Full v1 scope is 3 firmware families × 2 boards (6 cells); mark each cell
+tested on real hardware vs. code-reviewed only as this is run.
+
+1. ❑ From the hot-swap modal's step 1 (device already probed), press
+   **Flash Firmware…** → new step shows firmware-family + board pickers and
+   the erase-confirmation checkbox; "Erase & Flash Now" stays disabled until
+   family, board, AND the checkbox are all set.
+2. ❑ Confirm what's currently on the test stick via the existing probe
+   BEFORE flashing it — don't flash the only known-good device without a
+   fallback board on hand.
+3. ❑ Prefer a spare Heltec V3/V4 for the first destructive erase+flash run;
+   only exercise a primary/in-use stick once the flow is proven safe.
+4. ❑ MeshCore → Heltec V3: erase + write completes, progress bar and log
+   tail update live, ends at "Flash complete".
+5. ❑ Meshtastic → Heltec V3: same, using the extracted `*.factory.bin` from
+   the esp32s3 release zip.
+6. ❑ Reticulum/RNode → Heltec V3: `archy-rnodeconf --autoinstall` path
+   completes (no raw esptool erase/write step for this family — see
+   `mesh/flash.rs` doc comment).
+7. ❑ Repeat 4-6 against a Heltec V4. Confirmed 2026-07-23 on real hardware:
+   V4 uses the ESP32-S3's native-USB JTAG/serial peripheral (vid:pid
+   303a:1001, generic to every native-USB ESP32-S3 board, not V4-specific)
+   — so unlike V3's CP2102 bridge chip, V4 is permanently NOT auto-matchable
+   by vid:pid. Board auto-detect should fail closed for it every time
+   (manual board selection required, "couldn't confirm automatically"
+   warning shown) — this is expected steady-state behavior, not a gap to
+   close later.
+8. ❑ After a successful flash, the modal automatically re-probes and shows
+   the NEW firmware's badge/details — same as unplugging and replugging
+   (Section E item 3), but without physically touching the cable.
+9. ❑ Deliberately test a failure path once (disconnect the board mid-write,
+   or point at a bad cached asset) — confirm the error surfaces in the
+   progress log AND that `docs/troubleshooting.md`'s "LoRa radio firmware
+   flash failed" recovery steps (BOOT+RST bootloader entry, manual esptool/
+   rnodeconf command) actually get the board back to a flashable state.
+10. ❑ Cancel button only appears (and only works) while still in the
+    "Downloading firmware…" stage — once erasing/writing starts, no cancel
+    affordance is offered.
+
 ---
 
 After this passes: fold the batch + other agent's work into the next release

docs/troubleshooting.md

@@ -443,6 +443,52 @@ free -h
 - Check Nginx WebSocket proxy config: `/etc/nginx/sites-available/archipelago` must include `proxy_set_header Upgrade $http_upgrade`
 - If on WiFi, try wired Ethernet for more stable connectivity
 
+### 21. LoRa radio firmware flash failed / board unresponsive
+
+**Symptoms**: The "Erase & Flash Now" flow in the mesh hot-swap modal reports
+an error, or the radio no longer enumerates as a serial device after a flash
+attempt.
+
+**Diagnosis**:
+```bash
+# Poll the flash job's last-known stage/error directly
+curl -s http://localhost:5678/rpc/v1 \
+  -H 'Content-Type: application/json' \
+  -d '{"method":"mesh.flash-status","params":{}}'
+
+# Confirm the board is still enumerating at all
+ls -la /dev/ttyUSB* /dev/ttyACM* /dev/mesh-radio 2>&1
+
+# esptool/rnodeconf binaries present?
+which esptool; ls -la /usr/local/bin/archy-rnodeconf
+```
+
+**Solutions**:
+- A failure during `erasing`/`writing` (MeshCore/Meshtastic) or
+  `autoinstalling` (Reticulum) can leave the chip erased or half-written —
+  this is expected risk of the "always erase first" default, not a bug.
+- Heltec V3/V4 boards can be forced back into bootloader mode manually: hold
+  **BOOT**, tap **RST**, then release **BOOT** — this puts the chip in a
+  state esptool can always talk to, regardless of what firmware (if any) is
+  currently on it.
+- With the board in bootloader mode, a manual recovery flash can be run
+  directly over SSH without the UI:
+  ```bash
+  esptool --chip esp32s3 --port /dev/ttyACM0 erase_flash
+  esptool --chip esp32s3 --port /dev/ttyACM0 write_flash 0x0 <known-good-image.bin>
+  ```
+- For Reticulum/RNode boards, the equivalent manual recovery is
+  `archy-rnodeconf /dev/ttyACM0 --autoinstall` (or `/usr/local/bin/archy-rnodeconf`
+  if it's not on `PATH`) — it re-runs the same fetch+erase+flash+bootstrap
+  sequence the UI triggers.
+- If `esptool`/`archy-rnodeconf` are missing entirely, they should have been
+  installed by the last `self-update.sh` run — check
+  `sudo journalctl -u archipelago-update` for install failures, or install
+  `esptool` via `sudo apt-get install esptool` directly.
+- Once a fresh image is confirmed written, unplug/replug the radio (or wait
+  for the next detection poll) — the hot-swap modal re-probes automatically
+  and shows whatever firmware is actually on the board now.
+
 ---
 
 ## General Maintenance