factory reset on flash

OpenPuck/OpenPuck.ino

@@ -43,6 +43,11 @@ void setup() {
   ledInit();
   rfGenSessionAddr();   // per-device unique RF session address (advertised in the host frame; isolates pucks)
   InternalFS.begin();
+#if OPK_FACTORY_RESET
+  // Build-time wipe (-DOPK_FACTORY_RESET=1): reformat ALL persistent storage before it is read, so flashing this
+  // build comes up on clean defaults. Re-flash a normal build for regular use (this wipes on every boot). See config.h.
+  factoryErase(); InternalFS.begin();
+#endif
   loadCfg(); g_xbox = !modeIsPuck(g_usbMode);   // load persisted config + decide USB presentation BEFORE registering interfaces
   g_active = controllerFor(g_usbMode);
 

OpenPuck/config.h

@@ -16,6 +16,16 @@
 #define OPK_LOG 0
 #endif
 
+// Build-time FACTORY RESET. 0 (default) = normal. Build with -DOPK_FACTORY_RESET=1 to produce a firmware that
+// reformats ALL persistent storage (cfg.bin + bonds.bin) on EVERY boot, before anything is loaded -- so flashing
+// this build wipes the board to clean defaults. It keeps wiping each boot while the flag is compiled in, so the
+// intended workflow is: flash the reset build once, let it boot (storage erased), then flash a normal build for
+// regular use. Equivalent to the serial "ERASE-ALL" / WebUSB "Factory erase" actions, but at flash time and
+// without needing a console or the panel. Re-pair the controller afterwards.
+#ifndef OPK_FACTORY_RESET
+#define OPK_FACTORY_RESET 0
+#endif
+
 // ---- USB presentation modes (g_usbMode). RF poll/relay is identical across all; only USB enumeration +
 //      report mapping differ. ----
 #define MODE_STEAM   0   // Valve puck; auto-lizard when Steam closed

docs/BUILD_AND_DEPLOY.md

@@ -92,7 +92,25 @@ arduino-cli upload `
 
 Replace `COM5` with the actual board port.
 
-## 6. Pair and verify
+## 6. Factory reset (erase persistent storage)
+
+Re-flashing firmware does **not** erase the board's internal LittleFS. The paired-controller bond (`bonds.bin`) and every saved setting (`cfg.bin`: USB mode, chord assignments, back-paddle map, mouse sensitivity) survive a fresh build and upload. To bring a board up in a truly clean state — a new unit, a hand-me-down with a stale bond, or a corrupted config — wipe the filesystem with one of:
+
+- **Build flag (wipe on flash):** compile with `-DOPK_FACTORY_RESET=1` and upload. This build reformats all persistent storage on boot, so flashing it brings the board up on clean defaults — no console or panel needed:
+
+  ```bash
+  arduino-cli compile -b adafruit:nrf52:feather52840 --build-property "build.extra_flags=-DNRF52840_XXAA {build.flags.usb} -DCFG_TUD_HID=4 -DOPK_FACTORY_RESET=1" OpenPuck
+  ```
+
+  It wipes on **every** boot while the flag is compiled in, so this is a one-shot reset tool: flash the reset build once, let it boot (storage erased), then build and flash a **normal** firmware (without the flag) for regular use.
+- **WebUSB panel (any mode):** open the panel (§8), and in the maintenance card click **⚠ Factory erase**. Confirm the two warning dialogs and type `ERASE` when prompted. The board reformats its filesystem and reboots to factory defaults. This works in every USB mode.
+- **Serial console (CDC):** connect to the board's serial port at 115200 baud and send the line `ERASE-ALL` (exact, all caps). Same effect: reformat + reboot.
+
+Both reformat the entire internal filesystem (`cfg.bin` + `bonds.bin` and anything else), so the action is irreversible and the controller must be **re-paired afterwards** (see §7).
+
+Note on the serial method: puck (Steam/Lizard) mode drops the CDC console by default to free a USB endpoint for the wake-mouse interface, so the serial port may not be present in that mode. Either arm the one-shot debug CDC first (panel debug-CDC toggle / `D` console command, which keeps the console for the next boot), or just use the WebUSB **Factory erase** button, which is available in all modes.
+
+## 7. Pair and verify
 
 1. Flash the board.
 2. Plug it into the host.
@@ -100,7 +118,7 @@ Replace `COM5` with the actual board port.
 4. Pair the controller to one of the bond slots.
 5. Verify that the slot returns `0xB4 = 0x02` when connected.
 
-## 7. Run the WebUSB app locally
+## 8. Run the WebUSB app locally
 
 WebUSB requires a secure context. `http://localhost` qualifies.
 
@@ -130,7 +148,7 @@ Open:
 http://localhost:8008
 ```
 
-## 8. Known operational details
+## 9. Known operational details
 
 - Chrome or Edge is required for WebUSB.
 - The board re-enumerates on USB mode switches.