HowTo: Flashing NodeMCU Firmware to ESP8266

NodeMCU Firmware#

From time to time, you should take a look into the official NodeMCU Firmware repository. It is under heavy development and new modules and features are added constantly. Since version 0.9.6, there are no binary releases available, because the large amount of available module will not fit into the flash. Instead, you can create your custom firmware by using the web-based firmware build service.

To upload the firmware into the module, the recommend tool is esptool.py – it is pretty easy to use and is highly stable

Install Python + PIP Package Manager#

The esptool.py is written in Python and can be downloaded using pip. On Linux (Ubuntu/Debian), you can install python as well as pip by using the apt package manager:

apt-get install python python-pip

Install esptool.py#

By default, pip will install packages in global context, but maybe you want to use your home directory as storage. Just append the –user flag to the pip command

$ pip install esptool --user

The executable file is now located in ~/.local/lib/python2.7/site-packages/esptool.py – please read the documentation before running the tool! You need to adjust the command to match your specific ESP8266 Module (flash size).

Create Helper Script#

The following script will simplify your development workflow by storing the module related settings into a single script file. The settings below are adjusted to match NodeMCU DEVKIT v1.0 with 32MBit of flash! Just copy the content in a file named esptool within your project:

#!/bin/bash

# the tool location
esptool=~/.local/lib/python2.7/site-packages/esptool.py

# run the tool with options matching NodeMCU Dev Kit 1.0
# all script arguments are passed to the tool
python $esptool  -p /dev/ttyUSB0 write_flash -fm dio -fs 32m 0x00000 $@

Upload the Firmware to your ESP8266#

Finally you can upload any new firmware file like this:

./esptool nodemcu-master-9-modules-2016-07-25-12-16-08-float.bin

Well that’s it! The result should look like this:

$ ./esptool .firmware/nodemcu-master-9-modules-2016-07-25-12-16-08-float.bin
esptool.py v1.1
Connecting...
Running Cesanta flasher stub...
Flash params set to 0x0240
Writing 409600 @ 0x0... 409600 (100 %)
Wrote 409600 bytes at 0x0 in 35.5 seconds (92.3 kbit/s)...
Leaving...