Tutorial: flashing a program to the ESP-8266 microcontroller

The following is a technical post showing how to write a program to the ESP-8266 (a small, cheap WiFi-connected microcontroller), using a Mac and a USB-to-Serial adapter. I was having trouble flashing my ESP-8266 using an Arduino, so I bought this adapter on Amazon:

Definitely recommend. This is much simpler than trying to use the Arduino and a home-made flashing circuit.

But this adapter came without instructions, and there wasn't a ton of guidance on the internet about how to use it. What I did find seemed to assume I knew a lot more than I did about bootloaders and firmware and binaries, etc.

After figuring out how to flash the ESP-8266 manually, I learned that you can just do it within the Arduino IDE. I'll share both methods.

Flashing with the Arduino IDE

Set up the IDE:

1) Open the Arduino IDE, and under "Arduino >Preferences", add the following URL to the "Additional Boards Manager URLs" list: "http://arduino.esp8266.com/stable/package_esp8266com_index.json". Click OK.

2) Under "Tools > Board > Boards Manager" install the boards manger esp8266.

3) Under "Tools > Board" select "Generic ESP8266 Module."

Insert the Adapter into the USB Port

1) Insert the ESP8266 into the adapter (so that it's pointing toward the USB connector on the adapter).

2) Flip the switch on the adapter to "prog" mode, and insert the adapter into your USB port.

3) Click "Upload" to flash your Arduino code to the ESP8266.

To Manually Flash Code

Install a bootloader: esptool.py

Firmware refers to the code that runs on the microcontroller right when it turns on. A bootloader is a program that will run on your computer, and load the firmware onto the ESP-8266.

Install esptool using pip...

Type the following to download esptool using pip:

sudo pip3 install esptool

Note the path to where pip installs esptool.py. For example, mine was:

/usr/local/lib/python3.7/site-packages/esptool.py

...or install esptool using git

You can also get the code from github. Move to the directory you store code in, and type:

git clone https://github.com/espressif/esptool.git

Create the firmware (an executable, .bin file)

Now you need to create a compiled binary for esptool to load onto the ESP-8266.

You can do this in the Arduino IDE. I started with the blink program and saved it as ESP01_blink.ino:

void setup() {
  // initialize digital esp8266 gpio 2 as an output.
  pinMode(2, OUTPUT);
}

// the loop function runs over and over again forever
void loop() {
  digitalWrite(2, HIGH);   // turn the LED on (HIGH is the voltage level)
  delay(500);              // wait for a second
  digitalWrite(2, LOW);    // turn the LED off by making the voltage LOW
  delay(500);              // wait for a second
}

In the Arduino menu, select Sketch > Export Compiled Binary:

It will export the binary file to the same folder that contains ESP01_blink.ino.

Flashing the ESP-8266 (loading the code onto it)

The last step is to use esptool to load the .bin file you just created.

First, flip the switch on the USB-to-Serial adapter board to be in the "PROG" position, and plug the board (with ESP-8266 inserted) into a USB port. This will power up the ESP-8266, in Flash mode. Flash mode means it will be waiting for you to load a program, rather than executing a program.

Adapter in USB port; switch set to PROG mode.

Run esptool.py with the write_flash command:

python3 /PATH/TO/esptool.py write_flash 0x00000 /PATH/TO/ESP01_blink.bin

The 0x00000 specifies an address to write to in the ESP-8266's memory. I did not try any others, but this appears to work.

Done!

Unplug the adapter, flip its switch back to UART (running mode), and plug back into your computer to power up the ESP-8266. It should now run the code, and blink once per second.