ESP8266: flashing NodeMCU V1.0 on Mac OS X (or ESP8266 ESP-12E in general?)

A few days ago a package arrived from SeeedStudio: the new NodeMCU board V1.0 (see picture)

The NodeMCU V1.0 (picture from here)

On paper it has some nice advantages compared to the old V0.9 version or also to other ESP8266 dev boards: you can directly connect it to your computer for programming and you won’t need an additional USB-to-Serial programmer or an external power supply. The USB connector does the job. The only problem: they must have changed something on the interface. Flashing doesn’t work out of the box anymore:

stdin:1: open a file first

is what I got when trying to upload a file with the ESPlorer to the module…

I’m programming on a Mac, so all the fancy Windows based flashing tools won’t work for me directly. I usually use the adapted Arduino IDE or the to upload new images to the device. This posts describes how you can flash the new hardware despite the problems with the esptool. Basically it shows how you can use the original Windows tool from Espressif from your Mac OS X system, even if it is made for Windows.

  1. Download and install driver for the CP2102 from here:
  2. If you don’t already have it install homebrew:
  3. Install wine:
    brew install wine 

    I had to work around some issues with brew and wine. Write a comment if you want to know how I resolved them…

  4. Download the latest Flashing tool from Espressif:
  5. Install unrar (if you don’t already have it):
    brew install unrar
  6. Unpack the flash tool:
    unrar x FLASH_DOWNLOAD_TOOLS_v1.2_150512.rar
  7. Install unrar (if you don’t already have it):
    brew install unrar
  8. Enter the directory and start the Flashing Tool:
    cd FLASH_DOWNLOAD_TOOLS_v1.2_150512
    wine flash_download_tool_v1.2_150512.exe
  9. Now that the wine directory has created enter the dosdevices folder and create a symlink to your NodeMCUs tty device:
    cd ~/.wine/dosdevices
    ln -s /dev/tty.SLAB_USBtoUART com1
  10. Select your image and adjust the settings according to this screenshot:
    ESP Flash Tool started from wine: adjust the settings accordingly
  11. Now connect the NodeMCU module using USB and press the RST button while you keep pressing the FLASH button. This will put the module into the right state for flashing
  12. Now click START in the flasher tool and wait until it is finished. Click RST again and have fun.

I hope that the esptool gets fixed quickly to work with the new hardware. I’m also not sure whether the problems comes from the USB-to-Serial converter or rather from the ESP-12E module. I suspect it is the later, but I couldn’t find anyone complaining about problems with the ESP-12E in general.

Shopping Links:

Posted by Daniel Eichhorn

Daniel Eichhorn is a software engineer and an enthusiastic maker. He loves working on projects related to the Internet of Things, electronics, and embedded software. He owns two 3D printers: a Creality Ender 3 V2 and an Elegoo Mars 3. In 2018, he co-founded ThingPulse along with Marcel Stör. Together, they develop IoT hardware and distribute it to various locations around the world.


  1. Wow, having to install Wine just for flashing the NodeMCU seems pretty insane. I hope the tools ( or other) are fixed soon!

  2. I have OS X Yosemite on a latest model MacBook Pro (Retina, 13-inch, Early 2015) and the driver worked out of the box. But I can't flash it new firmware :(.

    I'm going to try the Windows tool inside VMWare, should be simpler to set up for me than going the Wine route.

    But I'd love to hear if anyone had luck doing it with of the simpler python based tools.

  3. I can confirm that this instruction works on MacBookPro11,2 with OSX10.10.4.

    A small hint: push "FLASH" button, keep it pushed, push "RST" and then you can release both of them – there's no need to keep pushing "FLASH" while flashing 😉

  4. You may also use the esptool with the following switches:
    -fm dio -fs 32m

    like this, for example:
    python –port /dev/ttyUSB1 write_flash -fm dio -fs 32m 0x00000 "path to your bin file"

    That way, you do not need to run wine.

  5. I can't flash it under windows 10… the tool gives me a "chip sync error"… I don't know what to do… it seems that the board doesn't want to enter in flash mode..

  6. Warning: wine 3.0.4 is already installed, it’s just not linked
    You can use `brew link wine` to link this version.
    MacBook-Pro:flash_download_tools_v3.6.5 alex$ brew link wine
    Linking /usr/local/Cellar/wine/3.0.4…
    Error: Could not symlink include/wine
    /usr/local/include is not writable.

    Can someone help what’s wrong?

  7. Please help. Everything went fine till I tried to run the flash tool. I keep getting this error.

    Lord-Hoshalls-MacBook-Pro-3:FLASH_DOWNLOAD_TOOLS_v2.4_150924 jessehoshall$ wine flash_download_tools_v2.4_150924.exe
    dyld: Library not loaded: /usr/local/Cellar/wine/4.0/lib/libwine.1.dylib
    Referenced from: /usr/local/Cellar/wine/4.0/lib/../bin/wineserver
    Reason: no suitable image found. Did find:
    /usr/local/Cellar/wine/4.0/lib/libwine.1.dylib: mach-o, but wrong architecture
    /usr/local/Cellar/wine/4.0/lib/libwine.1.dylib: stat() failed with errno=1
    /usr/local/lib/libwine.1.dylib: mach-o, but wrong architecture
    /usr/local/Cellar/wine/4.0/lib/libwine.1.0.dylib: mach-o, but wrong architecture
    /usr/local/Cellar/wine/4.0/lib/libwine.1.0.dylib: mach-o, but wrong architecture

Leave a Reply