Flashing Troubleshooting

Most flashing failures fall into a small set of categories. Work through this table before assuming the device is damaged.

Symptom	Likely Cause	Fix
Device not detected by browser or OS	Charge-only USB cable; wrong USB port; missing drivers	Try a different cable (data-capable); try a different USB port; install CH340 or CP2102 drivers; try a different computer
Device detected but flash fails immediately	Not in bootloader mode	Hold BOOT while connecting (ESP32) or double-tap reset (nRF52); consult device-specific instructions
Device won’t boot after flashing	Wrong firmware build selected	Verify you selected the correct device in the flasher; re-flash with correct build
Flashed wrong variant (e.g., Repeater instead of Companion)	User error	Re-flash with correct variant; no permanent damage
ESP32 completely unresponsive / “bricked”	Corrupted flash	Hold BOOT button → connect USB → run: `esptool.py erase_flash` → re-flash firmware
nRF52 unresponsive	Corrupted firmware	Double-tap reset button to enter DFU mode → reflash via DFU
Linux: “Permission denied” on /dev/ttyUSB0	User not in dialout group	`sudo usermod -a -G dialout $USER` then log out and back in
Linux: Web flasher cannot connect	udev rules / ACL issue	`setfacl -m u:$USER:rw /dev/ttyUSB0`
macOS: Device not appearing in /dev/	Missing CH340 driver on macOS	Install CH34xVCPDriver from wch.cn or use the Homebrew formula
Flash completes but device shows wrong region or settings	Old config preserved in flash	Perform a factory reset via the app or by flashing with “erase before flash” option checked

If an ESP32 device is completely unresponsive and normal bootloader entry fails:

pip install esptool
esptool.py --port COM3 erase_flash       # Windows
esptool.py --port /dev/ttyUSB0 erase_flash  # Linux

After erasing, the chip will be blank. Re-flash the firmware normally via the web flasher.

Windows: Device Manager → Ports (COM & LPT) → look for CH340 or CP210x device. Note the COM number (e.g., COM5).

Linux: Run ls /dev/tty* before and after plugging in the device. The new entry is your device (typically /dev/ttyUSB0 or /dev/ttyACM0).

macOS: Run ls /dev/cu.*. Look for cu.usbserial-* or cu.wchusbserial*.