Update ESP8266 development kit NodeMCU firmware using OS X

I have previously written a small guide to getting started programming the ESP8266 development kit with the NodeMCU firmware. This post assumes that you have a fully working setup. Specifically I use the Seeedstudio NodeMCU v2 – Lua based ESP8266 development kit (affiliate link). I will flash to the latest version of NodeMCU.

Update the firmware

  1. Connect the ESP8266 via a micro-usb cable to the computer
  2. Make sure no program is using the serial port to the ESP8266
  3. Download and unpack esptool, either as a zip file og using git clone:
    git clone https://github.com/themadinventor/esptool.git
  4. OS X (Yosemite) already comes with python 2.7, but we need to install the pySerial dependency. Open a terminal and type
    sudo python setup.py install
  5. Download the latest ESP8266 NodeMCU firmware from here. Get the nodemcu_integer_*.bin file if you are unsure, for this example the newest version was nodemcu_integer_0.9.6-dev_20150704.bin
  6. Go to the esptool folder, e.g.
    cd ~/Downloads/esptool
  7. Flash the firmware using the following command. Replace /dev/tty.SLAB_USBtoUART with the name of the serial port you are using and ~/Downloads/nodemcu_integer_0.9.6-dev_20150704.bin with the path to the firmware you downloaded in step 5.
    sudo python esptool.py --baud 921600 --port /dev/tty.SLAB_USBtoUART write_flash -fm dio 0x00000 ~/Downloads/nodemcu_integer_0.9.6-dev_20150704.bin
  8. If everything is done right you should see the following
    Erasing flash...
    Writing at 0x00070c00... (100 %)
  9. Reconnect to the ESP8266 using ESPlorer or any other similar software and confirm that the ESP8266 is updated to the newest version. Using the RST button will restart the device and print the version at the boot


  • If unable to connect to the board after successfully flashing it you might try to remove the -fm dio parameter in step 7 and re-run it. For this particular version of NodeMCU and board from Seeedstudio I needed to add the parameter as explained here (search for DIO in the comments)
  • If using python3 you will run into many error messages about invalid print statements. Apparently the introduced stricter enforcement of how to create print statements in python3 and the esptool source code using an invalid version. Downgrade to python 2.7 seems to be the easy way out unless you want to fix the code (should be easy)
  • If you can not reconnect after flashing using baud 9600, but you see the boot loader at baud 74880, then sometimes you need to reflash the old AT firmware. Go to https://github.com/esp8266/esp8266-wiki/tree/master/sdk and download esp_iot_sdk_v0.9.5_15_01_23.zip. Unpack the zip file and follow the instruction in the bin/at/readme.txt file. Specifically I refreshed the device using the following 4 commands:
    sudo python esptool.py --baud 921600 --port /dev/tty.SLAB_USBtoUART write_flash -fm dio 0x00000 ~/Downloads/esp_iot_sdk_v0.9.5/bin/boot_v1.2.bin
    sudo python esptool.py --baud 921600 --port /dev/tty.SLAB_USBtoUART write_flash -fm dio 0x01000 ~/Downloads/esp_iot_sdk_v0.9.5/bin/at/user1.512.new.bin
    sudo python esptool.py --baud 921600 --port /dev/tty.SLAB_USBtoUART write_flash -fm dio 0x3e000 ~/Downloads/esp_iot_sdk_v0.9.5/bin/blank.bin
    sudo python esptool.py --baud 921600 --port /dev/tty.SLAB_USBtoUART write_flash -fm dio 0x7e000 ~/Downloads/esp_iot_sdk_v0.9.5/bin/blank.bin

    Then retry step 7 to 9 in the guide with the selected NodeMCU firmware.

  • If unable to flash with the Exception: Failed to connect error message, then try to remove all components connected to the ESP8266. I get this error when trying to flash the module with the RST and D2 pin connected which is needed for deep sleep.

Leave a Reply

7 Comments on "Update ESP8266 development kit NodeMCU firmware using OS X"

Sort by:   newest | oldest
December 22, 2016 17:03

Thanks so much. This worked when I changed the line to –baud 9600. Maybe it was my cheap knockoff board, but it couldn’t connect at 921600 baud.

May 5, 2016 05:59

Thanks for this, it was a great help to getting me started.
Only one thing: the command line to flash has a couple of errors in it.
It should be “–baud 9600” and “-fm=dio”. The baudrate could probably be higher (from what I’ve read) but 9600bd give me time to get another beer.
Another tip would be to re-name the folder to esptool from esptool-master — maybe that’s a newbie thing, but it’s fewer characters to type.
Also, the flashing leaves the device without a init.lua — which is probably a by-design thing. Live and learn from the efforts of others.