Now it’s time to have some fun with the ESP8266! In the last post, we talked about AT commands and how they’re used to interact with the ESP8266; more specifically, how they’re used to interact with its stock firmware. But if you remember, AT commands are only used for wireless functionalities. To take advantage of the chip’s really cool general purpose input/output (GPIO) pins, or some of its more advanced networking capabilities, you’re going to have to replace the stock firmware through a process known as flashing.

Here’s where things get a little murky, particularly for new developers. It’s probably easiest for you to think about firmware in terms of it being a simple operating system. Firmware are generally released for specific purposes. For example, the stock firmware was build specifically to facilitate AT commands and completing simple wireless tasks. NodeMCU was built to provide a framework that would run Lua scrips. Similarly, MicroPython allows you to run a stripped-down version of Python. You can even write your own firmware as if the ESP8266 were an Arduino! I don’t want to bury the lede too much here, but if you’d like to skip the background information and get right to writing/uploading custom firmware, jump down here.

Released Firmwares

As of September 2015, there are a handful of companies/individuals that have released firmware to the public. This list isn’t exhaustive, but I’ll do my best here to summarize some of the more popular releases.

Ai-thinker

If you take a close look at the cover on my ESP8266 ESP-12, you’ll see that it’s branded as an Ai-thinker (under the cover is the actual ESP8266 with the Espressif markings).

Additionally, from the last post, you’ll notice that when I requested my chip’s firmware version, it reported back that my firmware was created by Ai-thinker.

NodeMCU

This is one of the popular firmwares out there for the ESP8266, likely because the documentation is well written and there are plenty of examples. NodeMCU was written specifically to run Lua scripts, and gives the developer access to all the ESP8226’s microcontroller functionalities – PGIO/i2c/spi/etc in addition to more advanced networking capabilities. It functions a little bit differently than the Ai-thinker firmware in that it includes a filesystem. This allows you to upload Lua scripts that can be run, rather than flashing a new firmware every time you want to change something.

Official Espressif

Don’t forget, the actual manufacturer of the ESP8266 is the Chinese company Espressif. They’ve provided plenty of tools, including an SDK, for developing firmware for their product. However, if you’re not a native Chinese speaker, you’re probably going to have a difficult time using their tools efficiently. After a ton of searching, I finally found a “developer zone” forum that they use to release new updates and provide documentation. You can check that out here: http://bbs.espressif.com.

Fairly recently, Espressif made the decision to close their source code. The last open version they released is v0.20_14_11_28 and can be downloaded on their forum. They’ve also provided a flashing tool that’s relatively popular.

MicroPython

MicroPython is, broadly, a stripped-down implementation of Python 3 that’s been built for embedded systems. As such, the vast majority of Python libraries aren’t compatible with MicroPython, but the syntax is familiar to those that have used Python. Several months ago, a group of MicroPython fans decided to port the framework so that it would run on an ESP8266. The project is still very much in its beta phase, so many of the functionalities that are built into MicroPython aren’t available on the ESP8266. For those of you keeping track, that means very little Python is actually part of MicroPython for the ESP8266. At this point, it can basically just access GPIO pins and do some simple networking.

In my opinion, there isn’t much point in flashing MicroPython at this point given the alternatives.

ESP8266 Basic

This is exactly what it sounds like. It’s a BASIC interpreter that’s really easy to flash. It runs the ESP8266 in access point (AP) mode, and BASIC programs are uploaded to the device via a simple in-browser interface. If I were a high school teacher, or someone trying to get kids into electronics and programming, this is exactly the firmware I’d use!

Arduino IDE

For the vast majority of ESP8266 users, using the Arduino IDE to write custom firmware is going to be their bread and butter. One of the coolest things about the ESP8266 is that it’s 100% compatible with the Arduino IDE! That means that code written for an Arduino is 100% compatible with an ESP8266! If you’re getting antsy after that hype-up, jump down below to see how to go about writing custom firmware for your ESP8266 with the Arduino IDE.

Flashing!

The first step to flashing any firmware is to first prepare the ESP8266 by placing it in bootloader mode. Here’s the bad news if you’ve previously been using an Arduino as your serial converter – Ardunios cannot be used to flash ESP8266 chips. You’re going to need an FTDI USB-to-serial converter to do this. If you’ve already been using an FTDI converter, the good news is that to put the ESP8266 in bootloader mode, all you need do to is tie GPIO0 and GPIO15 (for the ESP-12 model; other versions will vary) to ground and reset the chip.

I’ve seen several people online construct little “jigs” for flashing. All they really are is a button to tie the GPIO pins to ground, and a button to tie the reset to ground. If you want to streamline your flashing process, you might want to go ahead and expand your circuit as shown below. One recommendation if you do go this route is to go ahead and add in a capacitor and resistor to tie the RESET pin to GPIO16. This will come in handy later as it allows the ESP8266 to reset itself after entering low-power sleep mode.

The thing to remember here is that as long as GPIO0 and GPIO15 are tied to ground when power is given to the ESP8266 (or the RESET button is released), the chip will boot up into bootloader mode. At that point, GPIO0 and GPIO15 no longer need to be tied to ground.

Flashing Ai-thinker Firmware

Remember how I mentioned that my ESP8266 ESP-12 was shipped with Ai-thinker firmware?

The strange thing about this particular firmware is that Ai-thinker hasn’t publicly released it. Granted, it’s a bare-bones firmware, and there’s really no need for you to have it installed on your chip given the other options available, but if you want to return your ESP8266 to the “stock” firmware, this is the way to do it.

Unless you’re fluent in Chinese, the Ai-thinker forum is going to be impossible to navigate. It’s entirely possible that they share firmware updates here, but there’s no way for me to know. Fortunately, there are a pair of Google drives out there (I’m not sure who maintains it, or how frequently they do so) that share the Ai-thinker firmware and their flashing tool. At the moment, the newest firmware version is 0.952 with support for SmartLink, and the flashing program is ESP8266 Flash Downloader.

This flashing process is almost too simple share. After extracting both folders, it’s as easy as running esp8266_flasher.exe, specifying the location of the firmware’s .bin file, and hitting upload (after you’ve put the chip into bootloader mode, of course). It’ll take 30 seconds or so to complete.

To confirm that the flash was successful, I fired up PuTTY and ran the previously discussed AT+GMR command. You’ll notice that it’s an older version of what I had shipped to me, and interestingly, it’s also void of the friendly Ai-thinker message. I’m purely speculating here, but I’m guessing Ai-thinker just compiled Espressif’s release and added in their own branding.

Flashing NodeMCU

If you remember from the Primer, NodeMCU actually sells development kits that are basically just ESP8266 ESP-12E’s with convenient breakouts, buttons, connectors, etc. To help sell their product, and altruistically help out the whole community, they’ve also released a convenient flashing tool that works with both NodeMCU and custom-brewed firmware.

The NodeMCU git can be found here. It’s a well-written git that includes a helpful wiki. The flasher can be downloaded from the appropriate 32-bit or 64-bit folders located here. Once you have ESP8266Flasher.exe, you don’t even need to download an additional firmware file. Simply run the .exe. If it doesn’t auto-detect the correct COM port, be sure to get that set properly. You’ll also want to make sure to view the Advanced tab and ensure that the baud rate corresponds to the rate the ESP8266 is communicating at prior to the flash. In my case, it needed to be changed to 115200.

Additionally confirm that the flash size is appropriate, as the different ESP8266 variants will feature differing storage sizes. After all that, go back to the Operation tab and hit the ‘Flash’ button.

On the other hand, if you don’t want to flash the firmware that’s built into the flashing program and would rather flash a more recently released version, navigate to the Config tab, ‘X’ the firmware you’d like to flash, set its location, and make sure to place the memory offset location at 0x00000. Then just flash normally.

To double check and make sure that NodeMCU flashed successfully, open up a serial connection to your COM port at a 9600 baud rate, then restart your ESP8266. It will attempt to run the Lua initialization script, but since that doesn’t exist, it stops right there.

Flashing the Official Espressif Firmware

This is actually the only firmware I’m not going to cover at this point, admittedly because it’s more effort than I think it’s worth given the alternatives. However, I’ll mention that Espressif offers source files that you can compile, and then flash to your device. For the vast majority of people looking to get going with the ESP8266, this is way too involved. If you do decide to go this route, the program is named ESP FLASH DOWNLOAD TOOL, and can be downloaded from Espressif’s developers’ forum.

Flashing MicroPython

Given its current level of development, flashing MicroPython is an involved process. First you have to build the firmware from source (unless you find pre-compiled versions), then flashing can be done either from the command line through the use of esptool.py, or via the NodeMCU flasher discussed above. Adafruit actually has a really good tutorial for flashing MicroPython, so instead of rehashing it here, I’ll refer you to Adafruit.

Flashing ESP8266 BASIC

Flashing the BASIC interpreter is about as easy as it possibly gets, and I give a ton of credit to the author Michael Molinari. Navigate to the Download portion of esp8266basic.com, and download the executable file. Simply run it, select your COM port, and the size of your chip’s storage, then hit the oversized Firmware Flash button (after putting your chip into bootloader mode, obviously).

A command prompt will open, and after around 30 seconds (no longer than it takes any of the other flash methods), the accompanying window will open and let you know of its success.

Since ESP8266 BASIC puts the chip into AP mode, we’ll just need to double check and make sure that the device is broadcasting. I fired up my laptop and searched for an SSID that started with ESP. There it is! After connecting to the ESP8266, if you navigate your browser to http://192.168.4.1, you’ll be greeted with the interface that will allow you to program all kinds of BASIC scripts.

Flashing With the Arduino IDE

You should already have the Arduino IDE software, but if you don’t download it here. Then follow these steps:

Note that the Programmer option at the bottom of the selector makes no difference as of an update from ~April 2015

At this point you’ve essentially made your Arduino IDE an ESP8266 IDE! There are plenty of how-to-write-firmware examples out around the web, so I’ll just mimic those efforts and make the on-board LED blink. Below is a little piece of code (modified to work with the ESP-12) that I found somewhere, and cannot for the life of me relocate it to get it properly cited it. If anyone can fill me in, I’d appreciate it.

void loop() {
digitalWrite(ledPin, LOW); // Turn the LED on (Note that LOW is the voltage level
// but actually the LED is on; this is because
// it is acive low on the ESP-01)
delay(1000); // Wait for a second
digitalWrite(ledPin, HIGH); // Turn the LED off by making the voltage HIGH
delay(2000); // Wait for two seconds (to demonstrate the active low LED)
}
[/code]

It’s as simple as copy/pasting that into the Arduino IDE, entering your SSID/password, placing your ESP8266 in bootloader mode, and uploading the firmware!

If this was helpful to you, or if I screwed up a detail or two, please let me know in the comments below!

Andrew is currently a mechanical R&D engineer for a medical imaging company. He enjoys good food, motivated people, and road biking. He has still not completely come to terms with the fact he will never play center field for the Kansas City Royals.

Dave

Hi Andrew
Thank you!!!!!!
I am a newb to 8266 and have been trying to understand flashing and what all of the different systems do and how they differ, its a mine field.
you have taken the time to research each of the firmwares and present an easy to understand explanation of each, you got me off the ground and on the way to getting an understanding. I am having problems with my Sparkfun things but now I’m on the way to understanding why
Dave

Anthony Robertson

Hi Andrew,
Thanks for putting this together. It is by far the most comprehensive guide to the available firmwares that I have found, including reasons why developers might choose one or the other.
I also found it helpful how you elaborated on the process for putting the chip into bootloader mode. People often gloss over how to do the reset, or how long the GPIO0 needs to be pulled LOW after the reset in order to successfully enter bootloader mode.
I will doubtlessly be referring back to this post when I’m ready to give nodeMCU a shot.

AutoDoc

Hello. First of all thank you for adding clarity to all the stuff that’s floating around the internet regarding ESPs. Your work is much appreciated.

In testing some Arduino logic found elsewhere (basically sniffs for particular WiFi SSID and connects to it), I was able to upload it and get the expected behavior (answering a ping) from the ESP as soon as the sketch finished loading (well, maybe 10 seconds after it finished), but here’s the rub: On my 12E development ESP (the one with the integrated flash and reset buttons) all is well, IOW, I can upload the sketch and it works. I can also reset or cycle power to the ESP and it still works. This is the expected behavior, but…If I use a stripped down ESP 12E (basically just the chip, no reset and flash buttons), I can do the hokey-pokey to get it into flash mode, upload the sketch and it works properly just like the development ESP does. If I remove the flash pins from ground to get back into normal mode, and then reset (or power cycle) the ESP, it seems as though it lost the sketch just uploaded to it (symptom is that it will no longer answer the ping). I must be missing something. Any ideas?

Sam Rusling

Took me a while to figure this one out too, I’m guessing we’re not the only ones so here’s what to do:

An excellent series of articles. I have a custom designed board that refuses to yield a MAC address in spite of my efforts to ensure correct boot conditions at power up. Reading this series of blogs has given me some potential solutions to try. I’ll post again if and when I find a solution. One anomaly I’ve already discovered is that connecting GPIO15 directly to ground gives a different boot result than that when it is pulled down to ground through a resistor.

Mohammad Faraz

Can you write a tutorial for custom firmware flash for esp8266-01 through arduino.

Gotta say, I'm pretty thrilled to see Hosmer gone. Obviously don't hate the guy, but the #Royals baseball I grew up on was not hinged on signing expensive FA. I'm excited to watch the youngsters play ball!