How to Re-flash Your ESP8266

As you work with and learn Lua on the ESP8266, it is likely, because of some quirks in the language and processor implementatoin, that you'll eventually create a tight loop in your init.lua file. That, or an infinite loop. Either one will brick your ESP8266. Hint: if you need to do something repeatedly and quickly (like checking the sensor state on a door/window open sensor), use the built-in timer function to set an interrupt with a callout function! Failing to understand that constraint is how I bricked my first ESP8266 and consequently learned how to re-flash the device.

Step 1 - Getting the firmware

Now, you could go and build the complete toolchain necessary to cross-compile the firmware for the ESP8266. I might do that sometime just for the experience. Also, you could go to the nodemcu.com web site and try to download the current firmware. I, however, found the organization of the FTP site confusing and I couldn't find the right firmware.

Don't despair, though! A fantastic individual named Marcel Stor has created an interactive web page that allows you to build your own custom ESP8266 firmware! Just click that link and it will take you to the firmware configuration page.

Enter your e-mail address so you can receive notificatin when your bild is done and ready for download. Then scroll down to the configuration section. This is what it looks like:

Build from the Master branch unless you absolutely know you need dev for some reason. Also, I leave the Miscellaneous Options unchecked. In addition to the defaults, I think you'll want to add:

  • ADC
  • Bit
  • MQTT
  • Perf
  • PWM

As you play more with the ESP8266 and Lua, and become ever more enamored of the platform, you'll probably want to return to this page and build specific firmware for sensors you'd like to deploy outside of the security system project.

Once you have the options configured to your satisfaction, click the blue "Start your build" link at the bottom of the page. The site will send you e-mail when your build starts, and again when it's ready to download.

There will be two firmware files: a hardware float version and an integer version. I download both, but I only use the float version.

Next you'll need to flash the firmware onto your device.

Step 2 - Getting the tool to flash an ESP8266

As I mentioned, I'm on a Mac, and the most convenient tool for me to use is called esptool. This is a Python program (so it shold run on any platform that supports Python) that you can clone from its GitHub repository. I put my firmware builds in the same directory as esptool.py, just for convenience.

Step 3 - Flash the ESP8266

If you are using a Feather M0 ESP8266 or Huzzah ESP8266 Breakout, you'll need to wire Pin 0 to Ground  This puts the device in bootloader mode. I use a female-female DuPont wire for this. Some boards from other vendors do not require this (in fact, many of the boards I've found arrive without any firmware at all, so the first thing you have to do is flash them.)

Once the board is ready to flash, you need to run esptool.py with the correct arguments. On the Mac, the correct command is

Download: file
python ./esptool.py --port /dev/tty.SLAB_USBtoUART write_flash 0x00000 <path to firmware>

Of course, replace <path to firmware> with your actual firmware path. It takes less than a minute to load the new firmware into flash memory on the ESP8266.  Once you're done with that, you'll have a working board (or, a working board again) and you can get on with your project!

This guide was first published on Jun 23, 2016. It was last updated on Jun 23, 2016. This page (How to Re-flash Your ESP8266) was last updated on Jun 23, 2019.