Esptool.py is a python script that retrieves information about your ESP8266 module and flashes its firmware. In the previous article we used ESPFlasher to install a NodeMCU firmware on an ESP8266-based board (and even install a custom firmware through nodemcu-build), but ESPFlasher is only available for Windows (32 or 64 Bits) while esptool can run on all platforms that can run Python.
Prepare the ESP8266
If you are a beginner, we will use the Terminal to perform all the steps of this tutorial. You can find it in applications, in the Utilities folder, or by entering Terminal in Spotlight.
Provide an FTDI module (or cable) if your module is equipped with a programming interface via a COM port.
Esptool.py requires Python 2.7 which is normally the default on Mac OS X. To find out if python is already present on your machine, simply type the python command in the Terminal. If everything is properly installed you should have a message like this
Python 2.7.10 (default, Aug 22 2015, 20:33:39) [GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.1)] on darwin Type "help", "copyright", "credits" or "license" for more information.
If this is not the case install python 2.7 by visiting here. Do not forget to leave python by entering exit (), quit () or Ctrl + D before continuing.
Let’s now go to the Document directory (or the directory of your choice, it is equal) like this
We will recover esptool by cloning it from github with command.
git clone https://github.com/themadinventor/esptool.git
Go to the esptool directory
Now we will execute the script setup.py which allows to add the necessary dependencies (in particular pySerial). You will need to enter your password to allow the command to run.
sudo python setup.py install
Update firmware ESP8266 NodeMCU with esptool.py on macOS
Now that esptool is ready, download the latest firmware NodeMCU ESP8266 by visiting github. Download the version that corresponds to your project. By default, take the integer version. To write this article, I used the binary nodemcu_integer_0.9.6-dev_20150704.bin.
Connect your ESP8266 NodeMCU board using an FTDI module (or a USB cable depending on the board you have).
To identify the serial port on which your board is located, you can use the Arduino IDE or enter the following command
The command returns the list of devices connected to your Mac. In my case it is connected to /dev/tty.usbserial-A1048DR2
All that remains is to prepare the command to flash the firmware. It is thus composed. Don’t forget to modify PORT_COM and BIN_PATH before to execute the command
sudo python esptool.py --baud 921600 --port COM_PORT write_flash -fm dio 0x00000 BIN_PATH.BIN
In the present case
sudo python esptool.py --baud 921600 --port /dev/tty.usbserial-A1048DR2 write_flash -fm dio 0x00000 ~/Downloads/nodemcu_integer_0.9.6-dev_20150704.bin
Depending on your ESP8266 module, you may need to bootload this mode. Small reminder how to do for those who discover
- Press and hold the GPIO0 button. The LED lights up at full power
- Press the Reset button
- Release Reset
- Release the GPIO button. The led illuminates by half. The ESP8266 is in “bootload mode”
Now run the update command. If everything is correct, esptool starts by erasing the flash memory and then downloads the firmware. You can track the progress of the update from the terminal. The blue LED on the antenna will blink throughout the operation.
Now open your Arduino IDE and open the Serial Monitor. Press the Reset button on the board. You should get a message indicating the firmware version and an error message
NodeMCU 0.9.6 build 20150704 powered by Lua 5.1.4 lua: cannot open init.lua
If you need a custom firmware, for example a module only available on the development version, save space … you can read this previous article that shows how to get a custom firmware through frightanic nodemcu_build.
Firmware flashing is an energy consuming operation (with peaks between 200 and 300mA). Even if everything seems to have gone smoothly (the blue LED blinks during the operation, esptool does not indicate any error), it may happen that the firmware is incorrectly installed. Do not panic, simply add a complementary power supply, for example a LiPo battery 3.7 Volts by connecting it to the pin V+ and GND of your module then start again.