Flashing Troubleshooting
Flashing Troubleshooting
Most flashing failures fall into a small set of categories. Work through this table before assuming the device is damaged.
Troubleshooting Table
| 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 --port COM3 erase_flash (substitute your actual port, e.g. /dev/ttyUSB0 on Linux or /dev/cu.usbserial-* on macOS) → re-flash firmware. On newer installs the command may be esptool or python -m esptool; run pip install esptool first. |
| 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 USB-serial driver (depends on the board's USB chip) | Identify the chip first. CH340/CH9102 boards: install CH34xVCPDriver from wch.cn (or the Homebrew formula). CP210x boards (many Heltec/older devices): install the Silicon Labs CP210x VCP driver. Newer boards with native USB (nRF52 DFU, ESP32-S3 native CDC, e.g. Heltec V4) need no driver and enumerate as /dev/cu.usbmodem*. Recent macOS bundles some drivers, but a missing-device symptom usually means the matching VCP driver is not installed. |
| 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 |
esptool.py Emergency Erase
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. (On newer esptool installs the command may be invoked as esptool or python -m esptool instead of esptool.py.)
Identifying Your Serial Port
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*.
No comments to display
No comments to display