ESP8266: uploading code from Arduino IDE

This post explains how to upload code to ESP8266 using the Arduino IDE and a Serial-USB converter. We assume the use of an ESP-01 board, one of the cheapest and most used boards based on the device.

Hardware configuration

This tutorial assumes the use of the ESP-01 board, shown in figure 1, as the hardware. This is one of the most used boards based on the ESP8266 and can be bought for about 2 euros. If you are using another board (for example, a NodeMCU, which already has a USB connection) you can jump to the next section, which explains how to enable the ESP8266 support on the Arduino IDE.


Figure 1 – ESP-01 board. Taken from [1].

In order to allow uploading code to the device, we need to guarantee that the ESP8266 starts in flashing mode. To do so, we need to connect its GPIO0 pin to GND before powering it, as shown in figure 2.


Figure 2 – Configuration to start ESP8266 in flashing mode.

Then, we will need a Serial-USB converter to connect the ESP board to a computer. To do so, we connect the Rx and Tx pins of the board to the converter, as shown in figure 3. Besides that, the CH_PD pin should also be connected to VCC.

ESP FTDI programmer

Figure 3 – Diagram of connection between ESP-01 and Serial-USB converter.

Important: The ESP8266 is a 3.3 V device. The schematic shown in figure 3 was done under the assumption that the Serial-USB converter works with 3.3 V voltage levels. Applying 5 V levels to the UART of the ESP8266 will damage the device. A good and versatile Serial-USB converter, which allows to change between 3.3 V and 5 V levels using a jumper, can be bought for less that 2 euros.

Since the ESP-01 is not breadboard friendly, it’s a good ideia to create a simple programmer to make the process of uploading code easier. This can be done using a perf board and some female connectors. There are also some adapters to buy here.

Arduino  IDE configuration

The easiest way to configure the whole setup is to follow the guide provided here, which uses the boards manager of the Arduino IDE. As explained, we first need to install version 1.6.5 of the Arduino IDE (or greater), which can be found in Arduino’s repository of software.

Note: If we have another version of the Arduino IDE installed before and uninstall it to install version 1.6.5, an error such as “error opening file for writing: C\program Files (x86)\Arduino\java\bin\awt.dll” may occur. The solution is just simply restarting the computer.

After the installation, we need to open the Arduino IDE and access the preferences menu, as shown in figure 4.

add boards manager

Figure 4 – Location of the preferences menu in the Arduino IDE.

In the preferences menu, we need to add the following link to the Additional Boards Manager URLs field: This is shown in figure 5.

add URL

Figure 5 – Preferences menu with the ESP8266 platform link.

After that configuration, we need to do the installation of the ESP platform. To do so, we access the Boards Manager menu, as shown in figure 6.

boards manager.png

Figure 6 – Boards Manager menu localization.

On the Boards Menu manager, we search for the keyword “ESP” and the corresponding package will appear. Then we just click install, as shown in figure 7.

install esp platform

 Figure 7 – Installation of the ESP8266 platform from the Boards Manager.

Once the installation completes, we need to select the correct board options for the ESP-01 board. In the board type, in the tools tab, we choose “Generic ESP8266 Board”, as shown in figure 8.

esp01 option.png

Figure 8 – Configuration of the board for the ESP-01.

In the programmer entry of the same tab, we choose “esptool”, as shown in figure 9.

ESPTOOL programmer.png

Figure 9 – Configuration of the programmer for the ESP-01.

Finally, we can start writing code. After finishing,  we just press the upload button (same as we would do for a regular Arduino board) and it starts uploading. Figure 10 shows the result of a successful upload in the command window.

code upload

Figure 10 – Command window after a successful code upload for the ESP-01 board.

It’s important to note that after the code is uploaded, the device will start to run it. So, if we want to upload a new program, wee need to reset the power of the device, in order to guarantee that it enters flashing mode again.

First program

Since this platform is based on Arduino, we can use many of the usual functions. As an example for the first program, the code bellow starts the Serial port and prints “hello from ESP8266” every second.

void setup() {



void loop() {

  Serial.println("hello from ESP8266");


If everything is working fine, we will see the output in the serial console shown in figure 11.

Hello from esp8266.png

Figure 11 – Output of the hello world program in the serial console.

Now, we can start writing our IoT programs!




35 Replies to “ESP8266: uploading code from Arduino IDE”

  1. Hi! I’ve got a problem installing the libraries. Once I’ve installed in Board Manages ESP8266, I can’t find in the Programmer tab the option “esptool”. Why does this happen? Thanks!!

    Liked by 1 person

    1. Hi!

      Unfortunately I can not be of much help since I never ran into that issue.

      Nevertheless, this guide already has some time, maybe something has changed in the newer versions of the libraries. I haven’t yet had the opportunity to try them with a clean install.

      My suggestion is that you ask around on the GitHub page of the ESP8266 Arduino libraries:

      Let us know if you find any solution, it will certainly be helpful for others.

      Best regards,
      Nuno Santos


  2. hi I have some project but I’ve got the problem uploading my keypad+lcd program to the Generic esp8266 board. my keypad+lcd doesnt work with the new program. what should i do. thank you


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s