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 or using git clone:
$ git clone https://github.com/themadinventor/esptool.git
  1. 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
  1. 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
  2. Go to the esptool folder, e.g.
$ cd ~/Downloads/esptool
  1. 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
  1. If everything is done right you should see the following
Connecting...
Erasing flash...
Writing at 0x00070c00... (100 %)
Leaving...
  1. 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

Troubleshooting

  • 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.

Enjoyed this Content?

Help keep it free by sending a donation or purchase something using my affiliate links. You can also subscribe to various site feeds to get notified of new posts, follow me on social media, and more.

7 Comments

jm_in_TX

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.

Poul Serek

Hi JM

Thanks for the feedback and great that it got you started! You say it has a couple of errors, can you specify what kind of errors? I have been using the commands in this post many times and they work for me. The “-fm dio” should just work fine, in fact the official readme file for esptool.py mentions it just like that without the “=”. And I am not sure why you want to flash at a slower speed, since I am flashing at a faster speed just fine (I don’t need time to get another beer :) ). And yes, the missing init.lua is by design, but it is easy to upload a default one from here if you need it.

/Poul

jm_in_TX

Hi Poul–
Being new to this particular processor, I’m spending a lot of time trying to get traction. Your original command line didn’t work for me so I googled around and found those two differences between what you had used and what had worked for others. Changing those two parameters (perhaps incorrectly identified as errors: “-baud 9600” and “-fm=dio”) made things work for me. I will go back an try and see whether it not working the first try was the result of something else. It’s not that I want to flash more slowly, just that I was not successful with 921600. I don’t know what baudrates are supported, but I’m sure there is a list out there somewhere. The good news is that I can flash and that ESPlorer works like a charm.
The goal of this exercise for me is to make a WiFi-controlled WS2812 LED controller. starting from the LED web page example floating around the internet.
The problem with getting there is this is that I cannot consistently connect to the device with my iPhone. When I do connect and am able to call up the 192.168.1.1 web page, the connection is dropped within a few seconds. Windows and a MacBook will connect without issues and not drop. There are a few posts on the expressif forum on this subject and the consensus seems to be that the firmware needs to initialize the wifi config struct completely or i-devices will have trouble connecting. I haven’t dug into the source code of the firmware I flashed to see if that is being done. If it is, I will need to look elsewhere for the solution.
Thanks, jm

Poul Serek

Hi JM

Sorry for the late reply, but just got back from vacation. I had some issues connecting to the ESP8266 using NodeMCU and Safari on OS X and IOS. I got it working using the webserver in my post here which might help. My problem was that I did not send the correct response headers back and the different browsers all reacted differently. Also I am using the development branch of NodeMCU so that might help.

/Poul

jm_in_TX

Hi Poul–
While you were enjoying your holidays, I was busy and after much experimenting also discovered that browsers (notably Safari) can be VERY picky about html. I invested some time to get the right headers and now get consistent results across the browsers that matter to me. I will take close look at your work and see if I can improve. I have read that to effectively program the ESP8266, you have to divorce yourself from a purely procedural programming paradigm – something which is difficult for me because, although I do not program a lot (or as a job), I’ve been programming for a long time (~1971) and a procedural mindset is hard to break out of.
My other challenge is getting my iPhone to connect consistently and without dropping to the ESP. I am not getting a connection consistently and it often drops. I don’t have any other phones to test it with so maybe it’s not an iPhone-only problem. Connecting when it’s in station mode is not a problem.
Thanks from Texas!

jm_in_TX

You were right about the “-fm dio”. I have discovered that I get consistently good results with this command line:
esptool.py –baud 115200 –port /dev/tty.wchusbserial1450 write_flash -fm dio -fs 32m 0x00000 ../nodemcu_integer_0.9.6-dev_20150704.bin
So you can see that I have graduated to a higher baudrate.
Live and learn.

ProfTed

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.

Leave a reply