Electronics,how to

Flash NodeMCU firmware to the ESP8266 on a Mac – Guide

30 Aug , 2015  

Flashing NodeMCU firmware to the ESP8266 modules is straightforward using nodemcu-flasher on Windows. On other platforms some command line tools have to be used. Here are my notes with steps to flash NodeMCU to ESP8266 on a Mac.


Regardless of the method used for flashing, the ESP8266 module must be connected to an USB to serial converter in order to communicate with the computer. I have used a FTDI Basic Breakout with the addition of a jumper to select 3.3v operation. This is very important in order not to fry the ESP.

ESP8266 pinout

ESP8266 pinout

The connections are as follows:


ESP8266 (esp-01) FTDI Basic interface
RESET floating
CH_PD VCC 3.3v
GPIO-2 floating

The GPIO-0 pin must be connected to ground when the module is started in order to enter the bootloader. On other boards where it is broken out, the GPIO-15 pin has also to be pulled low to enter the bootloader.

The RESET PIN can be left floating. In order to reset the board it must be connected to GND and then disconnected.

The CH_PD must be connected to VCC, and disconnecting and reconnecting it seems to have the same effect of the reset pin. In some cases it may be necessary to cycle this pin to enter the bootloader.

Obtain the binaries

Compiling the images yourself can be time consuming, and requires installing several packages with macports or fink in order to be able to compile and use the full espressiv stack. After installing all packages, I got stuck on the makefile not liking the particular sed flavour installed on my mac.

Instead of compiling NodeMCU yourself, the images can be obtained from the nodemcu-flasher github page, inside the Resources folder. At the time of writing (august 2015) the latest image is nodemcu_integer_0.9.5_20150318.bin.

Alternatively there is a nice web service that builds the images on the fly at frigtanic.com where you can customise the image content to the features of the application and get some more space for your program by excluding unnecessary modules.

Flash images

I have used esptool, a little python script, in order to flash the boards.

After all the connections are ok test it by reading the mac address of the module:

python esptool.py --port /dev/tty.usbserial-A9CFZPXP --baud 115200 read_mac

where the /dev/tty.usbserial-xxxxxxxx is the name of the USB to Serial device. I usually find mine by ls /dev | grep usb

If you don’t see the board replying check your connections, make sure that the GPIO-0 is connected to GND and do a reset and a CH_PD cycle. Also try to experiment with different baud rates, 9600 could be a good next try.

If you see the board reply with its mac address, its time to upload a new image:

python esptool.py --port /dev/tty.usbserial-A9CFZPXP --baud 115200 write_flash 0x0 ./nodemcu-master-10-modules-2015-08-29-11-33-14-float.bin

Where the .bin file is obviously the image of NodeMCU to flash on the ESP.

Test the image

There is a nice cross-platform IDE to interface to NodeMCU once the firmware is flashed, called ESPlorer.

From the program you can set the connection parameters with the same serial interface as before and the NodeMCU baud rate (I found mine to be 9600).

After power cycling or resetting the module, this time with the GPIO-0 (and GPIO-15) pin disconnected, you should see success messages on the console of ESPlorer, and you should be able to send simple commands to interrogate the board, such as getting the chip id or the chip info, and if all went ok see the replies from the module.

From there you can program the ESP8266 in LUA, so why not upload an hello world blinking program?



Leave a Reply

Your email address will not be published. Required fields are marked *