AUTHORED BY
Andrew Cross
DATE
09/22/2015
CATEGORY
WORD COUNT
2337
REV
0
REFERENCE IMAGE ESP8266-the-internet-of-things-wifi-chip-part-3-flashing-custom-firmware
NOTES
  1. I recommend using the Arduino IDE for flashing custom firmware
  2. The ESP8266 has to be in bootloader mode prior to flashing
SOCIAL REACH

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 is 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).
ESP8266-ESP12 with mount for breadboard

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.

AT version:0.25.0.0(Jun  5 2015 16:27:16)
SDK version:1.1.1
Ai-Thinker Technology Co. Ltd.
Jun 23 2015 23:23:50

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.

ESP8266 ESP-12 wiring diagram required for bootloader mode for flashing

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.

ESP8266 ESP-12 wiring diagram required for bootloader mode for flashing showing optional buttons

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?

ESP8266 ESP-12 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.

ESP8266-ESP-12 Ai thinker firmware downloading

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.

ESP8266 ESP-12 Ai-thinker successful firmware update

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.

NodeMCU firmware programmer baudrate setting 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.

NodeMCU firmware programmer flash

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.

NodeMCU firmware programmer most recent version

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.

NodeMCU firmware confirmation of successful flash

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).

ESP8266 BASIC flash firmware program

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.

ESP8266 BASIC flashing firmware results

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.

ESP8266 BASIC confirming the flash by seeing the SSID broadcast

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:

  1. Start the Arduino IDE and navigate to File > Preferences window.
  2. Under Additional Boards Manager URLs: enter this URL: http://arduino.esp8266.com/package_esp8266com_index.json
  3. Close the preferences window and navigate to Tools > Board > Board Manager
  4. Scroll to the esp8266 line item, select it, then click Install at the bottom right hand corner
  5. Confirm the board’s setting for your specific ESP8266 variant as shown below

Note that the Programmer option at the bottom of the selector makes no difference as of an update from ~April 2015
Configuring-the-Arduino-IDE-to-be-compatible-with-the-ESP8266

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.

// Import required libraries
#include "ESP8266WiFi.h"
int ledPin = 2; //On the ESP-12, the onboard LED is connected to pin 2

// WiFi parameters
const char* ssid = "<redacted>";
const char* password = "<redacted>";

void setup(void)
{ 
// Start Serial
Serial.begin(115200);

// Connect to WiFi
WiFi.begin(ssid, password);
while (WiFi.status() != WL_CONNECTED) {
delay(500);
Serial.print(".");
}
Serial.println("");
Serial.println("WiFi connected");

// Print the IP address
Serial.println(WiFi.localIP());

pinMode(ledPin, OUTPUT);       // Initialize the BUILTIN_LED pin as an output
}

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)
}

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!

Flashing custom firmware to the ESP8266 with Arduino IDE

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

Profile picture of Andrew standing at the Southern-most point in the United States.
Andrew Cross

Andrew is currently a university research engineer with a post-grad degree in mechanical engineering. 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?

  • Mike Taylor

    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.