Esptool: update ESP8266 NodeMCU firmware on macOS

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

cd ~/Documents

We will recover esptool by cloning it from github with command.

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

Go to the esptool directory

cd esptool

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 card using an FTDI module (or a USB cable depending on the card you have).

To identify the serial port on which your card is located, you can use the Arduino IDE or enter the following command

ls /dev/tty.*

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.

esptool flash firmware macos esp8266 update

Now open your Arduino IDE and open the Serial Monitor. Press the Reset button on the card. 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

For further

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.

Subscribe to the weekly newsletter

No spam and no other use will be made of your email. You can unsubscribe anytime.

Tags:

  • Paul

    couple of points:
    1) in the section:

    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.

    you don’t point to where you can get the code!

    2) you don’t say where to put it.

    • Hello Paul. Thank’s for the tips. I update the post. You need to modify COM_PORT and BIN_PATH before to execute the command

      • Paul

        You still don’t provide a link to where to get the binary, you just say visit github. Providing the actual link to the repository will be very helpful for others

  • Mike

    Cannot get past this step!

    mint@mint:~/Documents/esptool$ sudo python setup.py install
    Traceback (most recent call last):
    File “setup.py”, line 7, in
    from setuptools import setup
    ImportError: No module named setuptools

DIY Projects