Building Examples in ESP8266 RTOS SDK (Linux)

Download the ESP8266 RTOS SDK

Head over to Espressif homepage and locate the ESP8266 resources page. There, under the SDKs and Demos section, you should find the relevant RTOS SDK for programming the ESP8266.

In this article, we demonstrate the process of compiling an example project in ESP8266 RTOS SDK v1.4.0. Note that for future versions of the SDK, the process may be different.

This article is valid only if you are programming the ESP8266 using the Lubuntu development environment provided by Espressif Systems. Please search for and download the ESP8266 Getting Started Guide for more on this resource.

Extract the RTOS SDK

The downloaded ESP8266 RTOS SDK should be a ZIP file. To proceed, you must extract the ZIP file to an appropriate location. In this article, we create a folder called iotbits on the desktop and use this folder for all our programming and compiling tasks.

Place the ZIP in iotbits and “extract here” to get a folder called ESP8266_RTOS_SDK_V1.4.0 and a release_notes file. Rename this ESP8266_RTOS_SDK_V1.4.0 folder to RTOS_SDK.

extract-esp8266-rtos-sdk

This folder, RTOS_SDK, will be the “SDK root directory”, as it contains all the contents of the ESP8266 RTOS SDK.

Compile an example project

To compile an example project, head over to the example projects directory (RTOS_SDK/examples). In this example, we will compile the project_template as it is a general project setup and can be modified to create your own projects.

To compile the project, you need to run the shell script gen_misc.sh. This can be done as follows:

  • The first step is to modify the gen_misc.sh file according to your RTOS SDK directory location. To do this, open the gen_misc.sh file and right click and open it in the editor to edit the contents.
    Edit the SDK_PATH to point to wherever you have extracted the RTOS_SDK directory (in this case, /home/esp8266/Desktop/iotbits/RTOS_SDK)
  • The BIN_PATH specifies where the compiled BIN file is placed when you build the project. We set this to be in RTOS_SDK/BIN_dir. You can freely choose any location for the output BIN files.
    esp8266-rtos-sdk-example-sdk-path-setting-gen_misc-sh
  • Save these changes to gen_misc.sh.
  • Open the command terminal (ctrl + alt + T).
  • Change the directory to this project directory. In this case, the command would be:
    cd /home/esp8266/Desktop/iotbits/RTOS_SDK/examples/project_template
  • Execute the script gen_misc.sh using the command:
    ./gen_misc.sh
    You may get the permission denied error. To fix that, use command
    chmod +x gen_misc.sh
    Now, execute the script again by
    ./gen_misc.sh
    esp8266-rtos-sdk-genmisc-sh-permisson-denied-error
  • Press ‘Y’ to start the process. Enter options that suit your ESP8266 configuration (see BIN generation parameters below) and complete the process.
  • BIN_dir should now contain the appropriate BIN files depending on your compilation parameters you entered into the script.

esp8266-rtos-sdk-example-successfully-compiled

BIN generation parameters

  • STEP 1: use boot_v1.2+ by default
    boot mode: new
    This boot file is forced by default in the RTOS SDK. Users cannot opt for another version of boot.bin

  • STEP 2: choose bin generate(0=eagle.flash.bin+eagle.irom0text.bin, 1=user1.bin, 2=user2.bin)
    enter (0/1/2, default 0):
    Choose option 0 if your firmware does not use FOTA feature (updates over Wi-Fi). Use options 1/2 for firmware with FOTA enabled.

  • STEP 3: choose spi speed(0=20MHz, 1=26.7MHz, 2=40MHz, 3=80MHz)
    enter (0/1/2/3, default 2):
    Use the appropriate SPI flash chip access speed that suits your flash memory. It is recommended to use 40MHz or lower for best compatibility.

  • STEP 4: choose spi mode(0=QIO, 1=QOUT, 2=DIO, 3=DOUT)
    enter (0/1/2/3, default 0):
    Type of flash chip and how it is connected to the ESP8266. This would be QIO for standard modules like the ESP-01 or ESP-12 series.

  • STEP 5: choose spi size and map
        0= 512KB( 256KB+ 256KB)
        2=1024KB( 512KB+ 512KB)
        3=2048KB( 512KB+ 512KB)
        4=4096KB( 512KB+ 512KB)
        5=2048KB(1024KB+1024KB)
        6=4096KB(1024KB+1024KB)
    enter (0/2/3/4/5/6, default 0):
    This is relevant only for FOTA firmware that uses user1.bin and user2.bin.

As an example, a set of working configurations for the ESP-12E or ESP-12F module would be as follows for non-FOTA applications:
Step 1: new
Step 2: option 0
Step 3: option 2
Step 4: option 0
Step 5: option 4