Have you ever flashed your ESP8266 NodeMCU and ended up with a bricked board that won’t boot or connect? One of the magical aspects of playing with tech is doing the exact same thing to the exact same hardware and getting different results. Recently, I faced the frustrations of a bricked, unresponsive board with my NodeMCU Mini D1 while trying to install WLED for some “smart” lighting fun. In short, a simple flash erase using esptool.py saved the day. This is a quick guide that walks you through the process on Linux, assuming you’re on a distro like openSUSE Tumbleweed, Fedora, Ubuntu, or similar.
Bottom Line Up Front: The process has a few prerequisites and if you have already configured your computer to do the flashing, much of this article you can skip over.
Prerequisites
Before beginning this process, ensure you have Python 3 installed (most distros ship with it). Since I can’t be certain that the distribution packages will have the tool we need, we’ll use pipx to install esptool.py in an isolated environment, avoiding global Python clutter.
Installing pipx
Not all Linux distros include pipx out of the box, but it’s easy to add via your package manager. Here’s how for common ones:
openSUSE Tumbleweed (or Leap)
sudo zypper install pipxUbuntu/Debian
sudo apt update && sudo apt install pipxFedora
sudo dnf install pipxArch Linux
sudo pacman -S pipxIf your distro lacks a package, install via pip:
python3 -m pip install --user pipx
pipx ensurepathThen, log out and back in (or source ~/.bashrc). Verify with pipx –version. pipx.pypa.io +3
Installing esptool.py
With pipx ready:
pipx install esptoolThis makes esptool.py available globally.
Test it:
esptool.py version.USB Permissions
ESP8266 boards like the NodeMCU connect via USB serial (/dev/ttyUSB0 usually). Without permissions, you’ll hit “Permission denied” errors. Chances are if you are at the point where you have [soft] bricked your board or played around with any other such devices, you have already completed this step. For those in the cheap-seats that haven’t gotten this far and are planning (no one plans to do this) to brick their board, you will need to add permissions to your user. The group that provides these permissions is called dialout.
Add your user to the dialout group:
sudo usermod -a -G dialout $USERLog out and back in (or reboot). Be sure to unplug or replug in your board when you are logged back in. To check that you have access to the board now:
ls -l /dev/ttyUSB*You should see crw-rw---- with dialout group ownership.
Connecting Your ESP8266
Under normal circumstances, you should only have to plug the ESP8266 into your computer and it will be ready for flashing. If you are having trouble connecting be sure that you are using a data cable not just one for charging.
Check your documentation, but be sure you are able to enter into bootloader mode if needed. To do so, hold the FLASH button, press RESET, release RESET, then release FLASH. (For stubborn bricks, the command below handles reset.)
To confirm that the device has connected you can check using dmesg.
sudo dmesg | tail after plugging in—it should show something like
[1234.567] usb 1-1: FTDI USB Serial Device converter now attached to ttyUSB0.
Erasing the Flash (The Unbrick Brute force)
The key step: Erase the entire flash to wipe corrupted firmware. Run:
esptool.py --chip esp8266 --port /dev/ttyUSB0 --after hard_reset erase_flash--chip esp8266: Specifies your board type.
--port /dev/ttyUSB0: Your USB serial port (adjust if it’s ttyUSB1).
--after hard_reset: Resets the board post-erase for a clean start.
erase_flash: Wipes everything.
You should see output like:
Chip is ESP8266EX Features: WiFi Crystal is 26MHz MAC: xx:xx:xx:xx:xx:xx Uploading stub... Running stub... Stub running... Erasing flash (this may take a while)... Chip erase completed successfully in 5.2s Hard resetting via RTS pin...
If it connects and erases, congrats—your board is unbricked!
Flashing WLED (or Your Firmware)
With a clean slate, you are now able to flash whatever it is you want, or in my case, I intended on flashing the WLED Firmware from the web installer page.
But if you would like to do this all locally, you can install it using the command line interface. where wled.bin. Is the firmware you want to install.
esptool.py --chip esp8266 --port /dev/ttyUSB0 write_flash -z 0x00000 wled.binhttps://github.com/wled/WLED/releases
Power cycle, connect to the board’s WiFi AP, and configure via the web interface.
Final Thoughts
Unbricking an ESP8266 is straightforward once you nail the tools and permissions—total time: under 10 minutes. This saved my project; hope it rescues yours. Got tweaks or questions? Hit me up on X.
References
https://kno.wled.ge
https://install.wled.me/
https://github.com/esp8266/source-code-examples/issues/26
https://software.opensuse.org/package/python3-pipx
Leave a Reply