Set up ESP8266 Open SDK on Linux

A couple of weeks ago, I tried the ESPlorer IDE for programming the esp8266, but since I wasn’t familiar with Lua scripting, I decided to switch to esp8266 open SDK toolchain, in which I can use the language C, to program the esp8266. This article will guide you on setting up the toolchain and SDK for your esp8266 on Linux.  I have also included an example of esp8266 connecting to the access point as a station. In this article, I will share some additional information and updates on tackling build and firmware flashing issues, that I had encountered during the process, along with its cause and solutions.

Follow the below steps very carefully:-

For Debian OS,

Install the Xtensa Crosstool-NG,

Did the build fail? – If yes, read below, else skip to section ‘Setting up the SDK’

build_error - esp8266 toolchain open sdk
Error Message Displayed for Build Failure

If your build is failing with an error message as shown in the above image, then as advised in the error message, let’s take a look at the ‘build.log’. Open the ‘build.log’ within the crosstool-NG directory using the ‘cat’ command, or an editor of your choice, I use ‘nano’.

build_log-esp8266 toolchain open sdk

The above image shows the ‘build.log’ and we can clearly see that the build is failing, as it is unable to connect to  “” to complete the build process. It tries to reconnect a couple of times but eventually gives up throwing an error message.

How to solve this?

After a while of searching on the Internet, I found a solution for this issue. To solve this, perform the steps shown below within the crosstool-NG directory:

Step 1

Open the shell script ‘’ and edit to replace the “” urls with as shown below:

Step 2

Open the shell script ‘’ and do the same edits as shown in Step 1.

Step 3 – Go back to crosstools-NG directory and run the ‘make’ command. You should see an output like below:

Step 4 – Build again using ‘./ct-ng build’ command. This time, it should build successfully.

For more information about the above steps, and to read the discussion regarding the above issue, please click here.

End of Build Fail Section

Setting up the SDK,


Let’s create a copy of the IoT_Demo example and rename it to ESP_Wifi as shown below. Let’s not make any direct changes in the Iot_Demo example, as it may be useful for future reference.

Installing Xtensa Liberaries and Headers

Installing the ESP Image Tool

Installing the ESP Upload Tool

Export PATH
Add the PATH variable within the Espressif directory as shown below

ESP_WIFI example
Once the SDK and toolchain are set up, we are good to go with the esp8266_wifi_station example. Currently, I am using NodeMCU, but the example will work for any esp8266 modules. Lets modify the ‘user_main.c’ file so that the esp8266 can connect to the AP as a station. Follow the below steps to make the changes.

Replace the entire code in the user_main.c with the below code, just copy and paste it. And change the SSID and password within the code to connect to your access point.

Run the ‘make’
Run the ‘make clean’ and ‘make’ command as shown below, within the ESP_Wifi directory to generate the firmware image ‘’.

Generate .bin files from the firmware image
After running the below commands, we will get two .bin files using the esptool and xtensa-lx106-elf-gcc compiler. One is ‘’ that is the SDK code and the other is ‘’ which is the application code. These .bin files should be flashed into the ESP8266.

Flash the firmware
For flashing the firmware, I  used the command with certain arguments passed along with .bin files, as shown in the source I have linked in the starting of this article. We run the script within the ‘image’ directory, to flash the files as shown below.

The above did work well with my ESP01 and ESP-WROOM-02 module. However, I had faced some flashing issue with the ESP8266EX Launcher at my work place and the NodeMCU I bought recently.

Issue: Though the flash process was successful using the above command have for some reason, the firmware did not respond i.e. neither did the LED blink nor did the station example work.

This got me wondering where did I go wrong. I tried again by reflashing, but I got the same response. Then I started some intense search on the web to see if anyone has faced this issue, and eventually, I found a discussion regarding the exact same issue here.

Solution: The reason why the firmware wasn’t responding is that I had not passed the flash arguments such as -fm (flash mode), -fs (flash size) and -ff (flash frequency). And, it has been confirmed that these arguments must be specified while flashing the ESP8266 WiFi example as shown below.

or for the LED blink example as shown below,

After flashing the firmware, reset the NodeMCU. For more information regarding the flash arguments, please click here.

The below video will show the working demo of the ESP_Wifi_station example along with the quick steps to compiling and flashing the firmware to your ESP8266/NodeMCU.

All the information and updates regarding this topic have been shared to make sure that you can get started with your ESP8266 without any problems. We can summarise them as follows:

  • Setting up the tool chain and Open SDK.
  • Build issues likely to encounter and steps to resolve it.
  • An example of esp8266 to configure as a station and connect to the access point.
  • Generating the firmware image and binary files for flashing.
  • Issues encountered during flashing using the esp tool and how to resolve it.
  • Links to contents from some important resources I used, to gather information for writing this article.
  • Lastly, a short video that shows the steps for flashing the firmware, along with a demo of the ESP_Wifi example.

If you are still facing any issues, you can comment below and I might be able to help you.

2 thoughts on “Set up ESP8266 Open SDK on Linux”

  1. I was stuck with a not responding NodeMcu on blinky sketch. It worked when I passed the flash arguments. Thanks.

Leave a Reply

Your email address will not be published. Required fields are marked *