Flash Firmware

Note this page describes how to flash firmware onto an ESP8266. You can flash either CircuitPython or MicroPython firmwares, just change the firmware file you're using. Note if you're flashing CircuitPython you can only use the CircuitPython API, see its documentation: http://circuitpython.readthedocs.io/en/latest/?

To flash the MicroPython firmware on the ESP8266 follow the steps below to use the excellent esptool.py script on any platform, or on Windows the GUI nodemcu-flasher tool.  Before continuing make sure you have a firmware-combined.bin file that was compiled or downloaded using the steps on the previous page!

esptool.py Flasher

The esptool.py flasher is a simple Python script that can flash firmware to an ESP8266 board.  This tool is great for running on a platform like Mac OSX, Linux, or Windows.  If you're on Windows you might consider a GUI-tool like nodemcu-flasher though--see the steps further below for more details.

Dependencies

Before you install the esptool script you first must have the following software installed:

  • Python 2.7 - You'll need the latest 2.7 version of Python to use the script.
  • PySerial Library - On Windows grab the pyserial-2.7.win32.exe installer and run it to install the library.  For Mac OSX & Linux, install pip and then run 'sudo pip install pyserial' (without quotes) to install the library.
  • Git - Again you'll need git installed to download the code for the esptool script.

Installation

To install the esptool script you just need to clone the source for it.  Inside a terminal navigate to a directory you'd like to keep the source code and run the following commands to download the source and change into its directory:

git clone https://github.com/themadinventor/esptool.git
cd esptool

Now you can run the script (using the python interpretor) with the -h parameter to see usage details printed.  Run the following:

python esptool.py -h

You should see usage information printed that starts with something like the following:

usage: esptool [-h] [--port PORT] [--baud BAUD]
           {load_ram,dump_mem,read_mem,write_mem,write_flash,run,image_info,make_image,elf2image,read_mac,flash_id,read_flash,erase_flash}
               ...
...

That's all you need to do to install and run the esptool script.  Next you'll learn how to flash the firmware using this tool.

Flash Firmware

To flash the firmware of an ESP8266 with the compiled MicroPython firmware first make sure you have the firmware-combined.bin file copied in to the directory you're working from (the esptool folder).  

Also make sure an ESP8266 board is connected to your computer using a serial to USB cable.  Find the serial port name for this device using either Device Manager on Windows or running a command like 'ls -l /dev/tty*' (without quotes) on Linux or Mac OSX.

When you're ready to flash the firmware, first put the ESP8266 into its programming mode.  With the Huzzah ESP breakout do this by holding the GPIO0 button and pressing the reset button, then releasing reset and finally releasing GPIO0.  With a bare ESP8266 breakout you'll want to follow instructions like these to manually pull the GPIO0 pin low and reset the board.

Now run the following command to use esptool.py to upload the firmware:

python esptool.py -p SERIAL_PORT_NAME --baud 460800 write_flash --flash_size=detect 0 firmware-combined.bin

Where SERIAL_PORT_NAME is the name of the serial port the ESP8266 is connected to (like COM4, /dev/ttyUSB0, etc.) and firmware-combined.bin is the path to the firmware-combined.bin file that was compiled earlier (if you've copied it to the same directory as esptool.py then you're all set with the command above, otherwise put in the full path to the file).

Note if you receive an error that detect is not a valid flash_size parameter you might be using an older version of esptool.py.  Make sure to download the latest code as shown above and try again.

After esptool.py flashes the chip you should see text like the following printed:

Connecting...
Erasing flash...
Writing at 0x0004d800... (100 %)

Leaving...

Congratulations, you've loaded the MicroPython firmware on the ESP8266!  In the future if you'd like to load the firmware again you can repeat the process above to put the ESP8266 into programming mode and run esptool.py to upload code.

Continue on to learn how to connect to and use MicroPython on the ESP8266.

nodemcu-flasher Tool (Windows Only)

The nodemcu-flasher tool is a nice little GUI tool to flash firmware to the ESP8266.  Follow the steps below to load the firmware-combined.bin file on to your ESP8266 board.  Before you get started make sure the ESP8266 is connected to your computer using a serial to USB cable!

Installation

To install the tool download either the 32-bit binary or 64-bit binary from its Github home.  Then run the program and you should see it detect the ESP8266 like follows:

Flash Firmware

To flash the firmware click the Config tab at the top and change the first line from nodemcu firmware to our custom MicroPython firmware-combined.bin file.  Click the gear icon next to the 0x00000 offset and navigate to the firmware-combined.bin file location.  You should see a configuration like follows:

It's very important that your configuration looks like the above with the firmware loaded to offset 0x00000.  If you have other firmware files or a different offset then the firmware won't work!

Now go back to the Operation tab at the top and verify the right COM port is selected for your ESP8266 board.  When you're ready to flash the firmware, first put the ESP8266 into its programming mode.  With the Huzzah ESP breakout do this by holding the GPIO0 button and pressing the reset button, then releasing reset and finally releasing GPIO0.  With a bare ESP8266 breakout you'll want to follow instructions like these to manually pull the GPIO0 pin low and reset the board.  Then click Flash to flash the firmware!  You should see the progress bar move as the firmware is flashed:

Once the firmware is flashed you should see it complete like the following:

Congratulations, you've loaded the MicroPython firmware on the ESP8266!  In the future if you'd like to load the firmware again you can repeat the process above to put the ESP8266 into programming mode and run nodemcu-flasher to upload code.

Continue on to learn how to connect to and use MicroPython on the ESP8266.

Last updated on 2017-10-18 at 03.40.06 PM Published on 2015-05-12 at 08.14.24 PM