Tuesday, June 9, 2015

ESP8266 Arduino IDE on Mac OS X Yosemite 10.10.3


How to program ESP8266 with Arduino IDE on Mac OS X Yosemite 10.10.3


This article provides a walkaround for using Arduino IDE to program ESP8266 on Mac OS X Yosemite 10.10.3.


To be able to follow this article, make sure your environment is same as below.

1. OS X Yosemite 10.10.3
2. Arduino IDE 1.6.4
3. ESP8266 Package for Arduino IDE 1.6.4-673-g8cd3697 
    *Refer to https://github.com/esp8266/Arduino for more information about this package 

FYI, I used USB to TTL Serial Cable Adapter Chipset PL2303HX' from ebay. Different chipset may produce different output.

What is problem?

If you click 'upload' on Arduino IDE, then you most likely end up with these errors and your ESP8266 won't be programmed properly.

Sketch uses 240,292 bytes (45%) of program storage space. Maximum is 524,288 bytes.
Uploading 33216 bytes from /var/folders/94/rt16wrlj14ng3z47m6q85qgr0000gn/T/build5456473246941663239.tmp/wifi-weather-sensor.cpp_00000.bin to flash at 0x00000000
error: failed reading byte
warning: espcomm_send_command: cant receive slip payload data
warning: espcomm_send_command(FLASH_DOWNLOAD_BEGIN) failed

It means that compilation has been completed successfully, but, there is an error while it is uploading compiled binaries to ESP8266. To fix the problem, we need to identify who is taking care of the 'uploading'? It's a little program, called 'esptool' and full path to it is



Since 'esptool' does not work correctly, we need to use alternative tool to upload binaries to ESP8266. One of the solution is 'esptool.py', which is a little python program for uploading and it works fine on Mac.

Follow these steps to install 'esptool.py', then, inform Arduino IDE to use 'esptool.py' instead of 'esptool' to upload binary to EPS8266.

Step 1: Close Arduino IDE completely

Step 2: Install esptool.py

Follow installation instruction at https://github.com/themadinventor/esptool

In my case, I just downloaded a single python file 'esptool.py', then, installed pySerial, which esptool.py requires to run. Make a note where you installed esptool.py. We need full path to it in Step 3.

All installation is done. Now, we just need to ask Arduino IDE to use 'esptool.py' we've just installed instead of 'esptool'

Step 3: Modify platform.txt file

By modifying 'platform.txt' file, we can specify 'esptool.py' as an uploading tool. 

In my case, I installed 'esptool.py' at /Users/$USER/tmp/esp8266/esptool/esptool.py"

Just open platform.txt located at 


and move to the end of file. Then you will se this line.

tools.esptool.upload.pattern="{path}/{cmd}" {upload.verbose} -cd {upload.resetmethod} -cb {upload.speed} -cp "{serial.port}" -ca 0x00000 -cf "{build.path}/{build.project_name}_00000.bin" -ca 0x10000 -cf "{build.path}/{build.project_name}_10000.bin"

Change it like this way

#tools.esptool.upload.pattern="{path}/{cmd}" {upload.verbose} -cd {upload.resetmethod} -cb {upload.speed} -cp "{serial.port}" -ca 0x00000 -cf "{build.path}/{build.project_name}_00000.bin" -ca 0x10000 -cf "{build.path}/{build.project_name}_10000.bin"
tools.esptool.upload.pattern="/Users/$USER/tmp/esp8266/esptool/esptool.py" --port "{serial.port}" write_flash 0x00000 "{build.path}/{build.project_name}_00000.bin"  0x10000  "{build.path}/{build.project_name}_10000.bin"

You can change the full path to esptool.py to wherever you installed esptool.py on your system.

Step 4: Open Arduino IDE and Load esp8266 example sketch

Set 'Board' to 'Generic ESP8266' and 'Port' to wherever ESP8266 connected to currently. It is '/dev/cu.usbserial/' in my case.

Click 'upload' on Arduino IDE, then you will see following message if everything goes well.

Sketch uses 240,292 bytes (45%) of program storage space. Maximum is 524,288 bytes.
/Users/$USER/tmp/esp8266/esptool/esptool.py --port /dev/cu.usbserial write_flash 0x00000 /var/folders/94/rt16wrlj14ng3z47m6q85qgr0000gn/T/build8386918307655313675.tmp/wifi-weather-sensor.cpp_00000.bin 0x10000 /var/folders/94/rt16wrlj14ng3z47m6q85qgr0000gn/T/build8386918307655313675.tmp/wifi-weather-sensor.cpp_10000.bin 
Erasing flash...

Writing at 0x00000000... (3 %) 
Writing at 0x00000400... (6 %) 
Writing at 0x00000800... (9 %) 
Writing at 0x00007400... (90 %) 
Writing at 0x00007800... (93 %) 
Writing at 0x00007c00... (96 %) 
Writing at 0x00008000... (100 %)
Erasing flash...

Writing at 0x00010000... (0 %) 
Writing at 0x00010400... (0 %) 
Writing at 0x00010800... (1 %) 
Writing at 0x00041c00... (98 %) 
Writing at 0x00042000... (99 %) 
Writing at 0x00042400... (99 %) 
Writing at 0x00042800... (100 %)


Now, ESP8266 starts to run with newly installed sketch.

In the following post, I will describe how I made a wifi weather monitoring system using ESP8266, DHT22 sensor, data.sparktfun.com, and Google Chart APIs.




  1. Wow thanks for the post! There is an update to the library (1.6.5-947-g39819f0) so the paste in code changed a little:

    tools.esptool.upload.pattern="{runtime.platform.path}/tools/esptool.py" --port "{serial.port}" write_flash 0x00000 "{build.path}/{build.project_name}.bin"

    I places the esptool.py with the espota.py which is in a folder called tools in the same directory as platform.txt

    1. this does not work in 1.6.5. Try remove it and roll back to 1.6.4 : http://arduino.esp8266.com/versions/1.6.4-673-g8cd3697/package_esp8266com_index.json .

  2. This comment has been removed by the author.

  3. Hi there. Thanks for the post. I am not sure what I am doing wrong here. I have pyserial installed for sure as it works from the command line python and importing it via repl. However I get this error when launching from the context of arduino IDE

    Sketch uses 199,418 bytes (19%) of program storage space. Maximum is 1,044,464 bytes.
    Global variables use 32,712 bytes (39%) of dynamic memory, leaving 49,208 bytes for local variables. Maximum is 81,920 bytes.
    Traceback (most recent call last):
    File "/Users/ril3y/Development/esp8266/esp-open-sdk/source-code-examples/blank_project/tools/esptool/esptool.py", line 22, in
    import serial
    ImportError: No module named serial

    Any ideas? I think this is a ENV issue? But I am stumped.

    1. I fixed it by manually editing the platforms.txt file (located in /Users/yourusername/Library/Arduino15/packages/wemos/hardware/esp8266/1.0.4/)

      I use python with brew, so my python environment is in /usr/local

      Therefore I replaced the lines 82 and 99:


      do the same with whatever location your python is, which you can get by doing:

      $ which python

  4. Hi
    I have a Problem, I don't understand how/where instal the esptool.py. I dowloaded pyserial-3.0 3 and esptool master but know?
    can you help me? thanks

  5. Hi All,

    Thanks for this article. With Arduino IDE 1.6.7 and esp8266 board manager 2.0.0., I had an error with missing .bin files.

    I replace the config line in platform.txt with this one :

    tools.esptool.upload.pattern="/Users/$USER/tmp/esp8266/esptool/esptool.py" --port "{serial.port}" write_flash 0x00 "{build.path}/{build.project_name}.bin"

    And my first blink test just work fine.


    1. i have problem with esptool on macbook but this recipe dont work for my. can you help?


      A fatal error occurred: Failed to connect to ESP8266

    2. forgot that i try flash nodemcu 0.9

  6. Hi every one, I solved the problem here, change a little of this configuration in platform.txt
    Here in my MAC and Arduino IDE 1.6.6 and Arduino Board Esp8266 version 2.1.0,

    My bin files don t create with the nomenclature:
    Here the correct name is:

    without "_00000"

    then you can change for this:
    tools.esptool.upload.pattern="/Users/$USER/tmp/esp8266/esptool/esptool.py" --port "{serial.port}" write_flash 0x00000 "{build.path}/{build.project_name}.bin" 0x10000 "{build.path}/{build.project_name}.bin"

    without the suffix in the filename pattern.

    other tip is, enable the compiler and upload messages:
    Arduino > Preferences
    Check the options: Compiler and Upload (Show output messages during:)

    There, you can find where your compiled files are create, and if your esptool.py command line is run correctly.

    I hope you can fix this problem.

    1. Hey there Alex,

      This thing you pointed out solved some of my problems. Thank you.

      However, now I get another error when trying to upload the code, here is the error I get;


      A fatal error occurred: Failed to connect to ESP8266

      I pulled down the GPIO0 to ground with 10k resistor and power cycled the esp8266. Once it worked, code is uploaded, it was blink example, but the led did not blink. So, I tried again but never managed to upload another code again, I all the time get this error.

      Any ideas?

    2. Hi!
      I'm having same issues. Did you find the answer so far?

  7. This is how it works for me :)

    -El Capitain 10.11.4
    -Arduino 1.6.4
    -ESP8266 Package for Arduino IDE 2.1.0
    -PySerial installed
    -_00000 and _10000 removed in platform.txt

    -Arduino Mega 2560
    -ESP8266 (generic)

    ESP8266 <-to-> Arduino
    TXD <--> TX0
    RXD <--> RX0
    VCC <--> 3.3Volts
    CH_PD <--> 3.3Volts
    GND <--> GND
    GPIO0's Switch to ground <--> GND (switch push = GND )
    RST's Switch to ground <--> GND (switch push = GND )

    Arduino's setup:
    RESET connect GND

    Arduino Tools config:
    Types de cartes : Generic ESP8266
    Flash mode : X
    Flash frequency: 40 MHz
    Upload using: Serial
    CPU frequency: 80 MHz
    Flash size: 512K (64K SPIFFS)
    Debug port: X
    Debug Level: X
    Reset Method: ck

    HANDLING to upload sketch
    1. Set configs for Arduino and ESP8266
    2. Make sure that Arduino’s board is in reset mode (RESET connected to GND on Arduino board)
    3. This is the tricky part:
    - Push GPIO0's button
    - Click on upload sketch button on arduino's IDE
    - When you see upload : click on Reset quickly (Blue LED will flash)
    - Finally, release GPIO0's button

    I hope this will help you

  8. Hi Brian T.S.,
    Thanks for the article.
    I am successfully able to upload sketch to my ESP8266-01 using USB to Serial module FT232R but program does not seems to be run after upload.
    I tried many sketches from ESP8266 example also.
    Please help.

  9. Hi All,

    I've come into a limitation with modifying the plateform.txt with this command:
    tools.esptool.upload.pattern="/Users/$USER/tmp/esp8266/esptool/esptool.py" --port "{serial.port}" write_flash 0x00 "{build.path}/{build.project_name}.bin"

    By default, esptool.py will assume the flash size is 512kB. As such, you will get errors if you try to write the flash above the 512KB limit.

    It's a very short limit if you try to use Over-The-Air firmware upgrade. You need enough space for both old and new sketches at the same time. See: OTA

    I recommand to add -fs (flash size), -ff (flash frequency), -fm (flash mode) options. See Esptool.py.

    With my Huzzah board (4MByte flash = 32Mbit flash), I modified the command like this:
    tools.esptool.upload.pattern="{runtime.platform.path}/tools/esptool.py" --port "{serial.port}" write_flash -fs 32m -ff 80m -fm dio 0x00000 "{build.path}/{build.project_name}.bin"

    It fixes my OTA issues.


  10. Hello, I followed all the steps, and I am still getting the same error. What are some other possible causes? Are there any other known fixes? Thanks!

  11. This continues to fail for me even on a windows computer. Are there any fixes for windows? Thanks!

  12. Hi there, I read your blogs on a regular basis. Reading this post reminds me of my previous room mate! He always kept chatting about this. Thanks for sharing.
    Video player for Mac

  13. On Arduino 1.16.12 I have implemented the above but now get the following error when upload tries to start
    (I had to find the path to platform.txt which on my system is

    [Errno 2] No such file or directory: '/var/folders/x3/1p_rcdv90233vsqm0qszzqq80000gn/T/arduino_build_703821/esp2866_blink.ino_00000.bin'
    [Errno 2] No such file or directory: '/var/folders/x3/1p_rcdv90233vsqm0qszzqq80000gn/T/arduino_build_703821/esp2866_blink.ino_00000.bin'

    Has anyone tried this on 1.6.12 on OS/X? Evidently it is not giving the right build.path / build.project.name
    Not sure what these should be on this installation.

    1. It turns out that the filename where the binary is saved is actually


      I am looking at how to fix the script to pick that up correctly

  14. 您好

    可是重新上傳時 還是出現這個狀況

  15. I've installed esptool.py on os x el capitan, arduino 1.6.13, correct python version,

    updated the platform.txt to :
    tools.esptool.upload.pattern="/usr/local/bin/esptool.py" --port "{serial.port}" write_flash 0x00000 "{build.path}/{build.project_name}.bin" 0x10000 "{build.path}/{build.project_name}.bin"

    It doesn't upload the bin files correctly ... I get fatal exceptions during the execution of sketches.

    It also still doesn't successfully upload to the ESP8266-01 board ... it does upload on the ESP8266-12E board, but the sketch gets fatal executions

    When I restore the platform.txt file to original version, the fatal exceptions go away (Of course, I still can't upload to the ESP8266-01 board.

    Thank you for your efforts here ... I'm still looking for help being able to upload to ESP8266-01. I've tried FTDI cable, FTDI breakout, Using arduino UNO as ISP. In each case, I'm able to program other processors, just not the ESP8266.

    I suspect it's something due to having to get it wired correctly, but I've tried every variation of pulling the CH-PD, GPI0/GPI02, RST to ground or high before and after and during compiling, I still can't get the stuff to upload.

    I don't know if it's software or my wiring :)

    I've got a voltage divider cutting the 5v to 3.3 v, measured on the input power, using a separate 2AMP power supply for the ESP board, tied grounds together.

    I'm getting a package with logic level converters allegedly in the mail tomorrow, i'll set that up on the rx/tx.

    In all cases, when I upload the sketch, the blue lights blink on the ESP board in a pattern matching the attempts to connect shown on the log...


  16. Arduino: 1.8.2 (Mac OS X), Board: "NodeMCU 1.0 (ESP-12E Module), 80 MHz, 115200, 4M (3M SPIFFS)"

    Archiving built core (caching) in: /var/folders/8s/ym8p58157qg_p9tjk89g65500000gn/T/arduino_cache_508140/core/core_esp8266_esp8266_nodemcuv2_CpuFrequency_80,UploadSpeed_115200,FlashSize_4M3M_9eee7b619a79e3d8ef9ec157bc0d029f.a
    Sketch uses 227777 bytes (21%) of program storage space. Maximum is 1044464 bytes.
    Global variables use 32016 bytes (39%) of dynamic memory, leaving 49904 bytes for local variables. Maximum is 81920 bytes.
    java.io.IOException: Cannot run program "/Users/vladdracul/Library/Arduino15/packages/esp8266/tools/esptool/0.4.9/esptool.py” -cd nodemcu -cb 115200 -cp "COM1": error=2, No such file or directory
    at java.lang.ProcessBuilder.start(ProcessBuilder.java:1048)
    at java.lang.Runtime.exec(Runtime.java:620)
    at java.lang.Runtime.exec(Runtime.java:485)
    at processing.app.helpers.ProcessUtils.exec(ProcessUtils.java:11)
    at cc.arduino.packages.Uploader.executeUploadCommand(Uploader.java:129)
    at cc.arduino.packages.uploaders.SerialUploader.uploadUsingPreferences(SerialUploader.java:207)
    at cc.arduino.UploaderUtils.upload(UploaderUtils.java:78)
    at processing.app.SketchController.upload(SketchController.java:713)
    at processing.app.SketchController.exportApplet(SketchController.java:686)
    at processing.app.Editor$DefaultExportHandler.run(Editor.java:2135)
    at java.lang.Thread.run(Thread.java:745)
    Caused by: java.io.IOException: error=2, No such file or directory
    at java.lang.UNIXProcess.forkAndExec(Native Method)
    at java.lang.UNIXProcess.(UNIXProcess.java:247)
    at java.lang.ProcessImpl.start(ProcessImpl.java:134)
    at java.lang.ProcessBuilder.start(ProcessBuilder.java:1029)
    ... 10 more
    An error occurred while uploading the sketch

    This report would have more information with
    "Show verbose output during compilation"
    option enabled in File -> Preferences.

  17. Woot!! thank you... Fought with the SiLab bs for a while, tried their legacy driver w/o success.
    I installed the esptool using "pip install esptool" and noted that the platform.txt file looked VERY different, and was referencing espota.py without my changing anything.
    So I ran Arduino and it uploaded BLINK just fine.
    Big Mahalo!!
    now to get neopixel/wifi running for Burning Man!!

    1. Would you mind explaining what you did with "pip install esptool" ....
      I am following Becka's IoT instructable Class and can't load the BLINK example onto the adafruit Huzzah esp8266.

  18. This comment has been removed by the author.

  19. nice, we do work on it too. Check it out serfone.com