Configure ESP8266 RTOS SDK to use ESP-IDF framework

In this post, I will explain how to configure ESP8266 SDK to use the ESP-IDF framework, along with the extension that is available for VSCode. The SDK documentation indicates that the extension is intended to be used with the framework, and the setup files are included in the SDK's repository. However, I could not find any tutorials that explain how to configure this.

Install the ESP-IDF extension

Before proceeding with the next steps, it is important to have already installed the framework in VSCode. You can find the installation instructions in the tool's repository.

In my case, I create and installed the framework in the following directory: ~/esp. I also chose to install the tools in this directory: ~/esp/.espressif. Therefore, the toolchain and the SDK will be installed in the same directory.

Download the ESP8266 RTOS SDK

Clone the repository for the SDK:

cd ~/esp
git clone -b master --recursive https://github.com/espressif/ESP8266_RTOS_SDK.git

Do not forget to write the option --recursive since git will also download the submodules the repository has.

Install the toolchain

The ESP-IDF doesn't include the toolchain for the ESP8266, so we have to download it from the ESP's server: xtensa-lx106-elf-gcc8_4_0-esp-2020r3-linux-amd64. Extract the toolchain inside the esp-idf tool's directory:

cd ~/esp.espressif/tools
tar -xzf ~/Downloads/xtensa-lx106-elf-gcc8_4_0-esp-2020r3-linux-amd64.tar.gz

Configure VSCode extension

We need to configure the extension. This involves setting the appropiate variables and specifying the location of the toolchain. Copy the cmake file for the toolchain inside the tool's directory:

cp ~/esp/ESP8266_RTOS_SDK/tools/cmake/toolchain-esp8266.cmake ~/esp/esp-idf/tools/cmake/

We have to append the toolchain's path in the ESP-IDF extension settings. In VSCode, open the extension's settings and search for: Idf: Custom Extra Paths. Append to it the ESP8266's toolchain path:

/home/ubuntu/esp/.espressif/tools/xtensa-lx106-elf/bin

Configuration for ESP8266's project

Each time you create a new project that is going to use the ESP-IDF framework and the ESP8266 SDK, you will have to create or edit the file settings.json, which is inside the directory .vscode/. This file must include the following configuration: the SDK's path, the custom microcontroller's cmake file that is going to be parsed, and the flash setup that is going to be used:

{
    "cmake.configureOnOpen": false,
    "idf.espIdfPath": "/home/ubuntu/esp/ESP8266_RTOS_SDK",
    "idf.adapterTargetName": "esp8266",
    "idf.flashType": "UART",
    "idf.port": "/dev/CH341",
    "idf.flashBaudRate": "115200"
}

It is important to set the setting "cmake.configureOnOpen": false to prevent vscode do an automatic configuration. With this change we can let the extension do the proper configuration for cmake.

In addtion, you will have to edit or create the file c_cpp_properties.json in order to set the compiling options, like the include path or the compiler's path:

{
    "configurations": [
        {
            "name": "Xtensa",
            "includePath": [
                "${workspaceFolder}/**",
                "${env:IDF_PATH}/components/**",
                "${env:IDF_PATH}/components/freertos/port/esp8266/include"
            ],
            "defines": [],
            "compilerPath": "${env.HOME}/esp/.espressif/tools/xtensa-lx106-elf/bin/xtensa-lx106-elf-gcc",
            "cStandard": "c17",
            "cppStandard": "c++17",
            "intelliSenseMode": "gcc-x64",
            "compileCommands": "${workspaceFolder}/build/compile_commands.json",
            "configurationProvider": "vector-of-bool.cmake-tools"
        }
    ],
    "version": 4
}

Install latest version of esptool.py

The ESP-IDF framework comes with an old version of esptool.py. Hence, I decided to install the laterst version of the tool, at the time of writing this article the latest version is v4.6.2. Download it from the releases page.

Rename the current esptool directory, in each setup, to have a backup of the original version:

cd ~/esp/esp-idf/components/esptool_py/
mv esptool esptool_orig
cd ~/esp/ESP8266_RTOS_SDK/components/esptool_py/
mv esptool esptool_orig

Finally, copy the new version's directory inside both directories:

cp -r esptool-4.6.2 ~/esp/esp-idf/components/esptool_py/esptool
cp -r esptool-4.6.2 ~/esp/ESP8266_RTOS_SDK/components/esptool_py/esptool

Evidence that everything works as expected

Here are some screenshots of ESP8266 RTOS SDK working with the ESP-IDF extension:

Hope you find this tutorial useful.