Notes on using the ESP8266 with the Arduino IDE · GitHub

Jovan Stosic March 21, 2017

Using ESP8266 with Arduino IDE

Methods for getting ESP82666 support into the Arduino IDE

FTDI_Basic_Hookup_for_ESP-01.jpg

There are several ways you can get ESP8266 support into your Arduino IDE.

As of May 2015, I recommend using Arduino 1.6.4+ and taking advangtage of the contributed board support from the Arudino ESP8266 project, Sparkfun and others. That way lies the future.

Hooking up the ESP-01 module

The ESP-01 is probably the most common ESP8266 module available right now. No one is really happy with the breadboard-unfriendlypin setup, the lack of an integrated voltage regulator, the number of pins broken out (two GPIO pins only?!?), or the fact that the board isn’t FCC/CE certified. But it’s cheap, was first to market and what folks could get their hands on. Fortunately, new boards are coming on the market, such as the Adafruit HUZZAH ESP8266 breakout and the Sparkfun ESP8266 Things.

There are a bunch of resources for how to hook this board up for both bootloading and use, but they’re a little confusing. See the diagram showing the connection of a Sparkfun FTDI Basic 3.3v to the ESP-01 included in this gist for a basic hookup that will work for reading and programming the board (something like the Adafruit FTDI Friend would work almost the same; just be 100% sure it’s set up for 3.3v power or put a regulator into the circuit). In that ciruit, holding down the button while cycling power on the ESP-01 will put the board in bootloader mode so you can upload new sketches.

Some useful resources

Alasdair Allan has written a nice walkthrough of getting things up and running with an ESP-01. I found that this article really helped me get over some issues I was waving getting the Arudino environment to work with the ESP-01.

Adafruit has several tutorials for the ESP8266, using either the ESP-01 or their own HUZZAH ESP8266 breakout board.

Resources, Wikis & Forums

Other Development tools

Arduino IDE support for the ESP8266 is still pretty new and maybe a little unstable. And perhaps you don’t like the Arduino IDE. Here are some other tools you can use to program an ESP8266.

  • nodeMCU — Lua scripting for the ESP8266
  • esptool.py — a handy little utility for flashing the ESP8266. Really great, saved one of my boards (see the story below). Also check out this short video on how to use esptool to flash your ESP8266.
  • esptool-ck — confusingly, there’s a second tool called esptool. This is the one that’s bundled into the Arduino ESP8266 support (though there have some requests to change this to esptool.py)
  • esp-open-sdk — the preferred method for installing an ESP8266 toolchain, if you want something more low-level than Arduino
  • embedXcode — a template for embedded/microcontroller development for Xcode

A little story about frustration

Check out the footnotes for some updates to the story, and a more or less happy ending to this tale!

I ran into an issue with one of my ESP-01 boards while trying to install a sketch with the Arduino IDE. I had the board hooked up to my Mac using an Adafruit TTL USB serial cable, with the TX, RX and GND connected to the ESP-01 and the 5V disconnected. The ESP-01 was powered from a 3.3V regulator. The board was already set up to run a sketch loaded from Arduino, but wouldn’t flash, even though I had ground GPIO0 to put it into programming mode.

As it turns out, there may be an issue with using the TTL USB cable as a programmer1. I never did get it to work (at least not until I switched to using an FTDI cable and/or FTDI breakout). But somehow, during all this, I did get a partial flash and it screwed up the board. I could flash it with various sketchs, but it just wouldn’t work. Pulling out another ESP-01, I confirmed that my setup was fine; the new board accepted the sketches and ran as expected. So I figured I’d do some troubleshooting.

The best way that I’ve seen to diagnose issues on an ESP8266 board is to take a look at the bootloader messages. This is a little tricky, since the board boots with its UART set to a baudrate of 74880, which is non-standard. I first attempted to connect to the board using screen in the terminal, but it couldn’t handle the weird bit rate and I just got garbage. The solution was to pull out CoolTerm, create a baudrates.ini file so I could define the custom rate, then connect to the chip.

Lo and behold, something was indeed wrong!

After the standard checksums, the board was throwing an error, system param error, then dumping a bunch of hex code. Apparently I’d screwed something up during that bad flashing.

My first thought was to try the Arduino IDE again, but to no avail: the board accepted the uploaded program, then went right back to not working. It occurred to me that Arduino might not be flashing the board completely, so I decided to try another solution. I was going to install the ESP8266 toolchain and SDK again, and try building the AT firmware. Then I remembered that building the toolchain takes forever. Instead, I ended up grabbing the Electrodragon update to the AT firmware and the ever-useful esptool.py. Esptool is a little utility for flashing the ESP8266. It can do all sorts of nifty stuff, such as reading the MAC address of the chip, dumping its memory or flash to files, and uploading new firmware.

With these tools in hand, I was able to flash the board directly with the AT firmware. A quick restart and…

…everything worked. Yay!

After all this I was able to use the AT commands to talk to the board. And replacing that firmware with Arduino sketches started working again, too.

That’s my little tale. This whole thing cost me a few hours of frustration, first at the TTL USB cable, and then at the unflashable ESP-01. But now I’m wiser, using FTDI Friends to program my boards, and I know how I can restore a board to working order if this happens again. And I’ve written this all down, on the chance that it might help someone else solve a similar issue in the future.

  1. See this thread on the Adafruit forum regarding describing upload issues use the USB TTL cable. I should note that I’m using the older revision of the Adafruit USB TTL cable. According to the product page, the black-body version that I use has the PL2303HX chipset in it. It’s possible the newer version, with the PL2303TA chipset, works as an ESP8266 programmer. I’ll snag a newer cable next time I order from Adafruit. Update: Nope, the newer cable doesn’t make a difference. I’ve got some Adafruit HUZZAH boards on the way, based on the ESP-12 module; we’ll see if they work with the console cables
  2. Another update, and this one matters: the problem was a combination of the version of esptool (not esptool.py!) that ships with the Arduino IDE. For some reason or another, the serial console cable can’t be used to program the board. But if you switch over to esptool.py, it works like a charm.
  3. Update on 1/3/17: I was able to flash an ESP-01 module using a PL2303 serial console cable,on macOS Sierra with Arduino 1.8.0 and the mac-usb-serial PL2303 driver (which I find is much more stable than the offical Prolific driver, and worth the $).
Raw
esp8266_useful_esptool_commands.md

Useful esptool.py commands

Reading the MAC address of the board

$ python ./esptool.py --port [serial port address] -b 115200 read_mac

Reading the flash ID

Gives some information about the current board setup

python ./esptool.py --port [serial port address] -b 115200 flash_id

Erasing the board

I found that doing this allowed me to re-flash the board after it got into some weird states

python ./esptool.py --port [serial port address] -b 115200 erase_flash

Flashing the board

Flashing an ESP8266 board with NodeMCU firmware (You can/should build your own firmware with NodeMCU custom builds)

python esptool.py -p [serial port address] write_flash 0x00 nodemcu_integer_0.9.5_20150318.bin -fs 32m -fm dio -ff 40m

Or here’s flashing it with the latest Electrodragon AT Command firmware

python ./esptool.py -p [serial port address] write_flash 0x00000 AI-v0.9.5.0\ AT\ Firmware.bin

Source: Notes on using the ESP8266 with the Arduino IDE · GitHub

Notes on using the ESP8266 with the Arduino IDE · GitHub was last modified: July 13th, 2017 by Jovan Stosic