Setup instructions for VSCode (GIT8266O-605)

[gbaranski]

Im struggling with a lot of problems with making VSCode usable for ESP8266-RTOS-SDK, it would be nice if there would be some setup instructions for VSCode.

[Gustice]

I'm also searching for a well written instruction to configure a sophisticated setup to use VSCode. However, in the meantime I have a solution for me that is quite sufficient in some/many cases.

Perhaps this could also help you for the meantime. However there are still some issues left.

• Intelli-sense complains often when header files appear to be missing because of the ambiguous file structure in the RTOS component.
• In that case the online syntax check fails, and you have to run the compiler to see the syntax errors.
• The links behind the Issues that are collected by problem matcher are not working (i suspect because all components are compiled on their own and are later linked).
  However, the file navigation works and helps a lot, and the issues are much more cleaner than the messy compiler output. Also if you can spare the RTOS-component in a module, all convenient features work so far.

Preconditions to use

• Start a terminal and run %IDF_PATH%\export.bat (or bash) in order to setup all environment variables
• Navigate to your project (in opend terminal) and type "code ."
• VS Code starts in given path with setup environment.
  Calling code that way enables you to use the defined tasks in tasks.json

My setup is:

c_cpp_properties.json

{ // https://code.visualstudio.com/docs/cpp/c-cpp-properties-schema-reference
    "configurations": [
        {
            "name": "ESP-Win",
            // Folder with header to be included -> For intellisens engine
            //  GoTo-Reference-List and tag database ("browse") relies on same paths if not specified
            "includePath": [ 
                "${workspaceRoot}/main/**",
                "${workspaceRoot}/components/**", // comes in handy when first components are created
                "${env:IDF_PATH}/components/**",
                //"${workspaceRoot}/build/include" // After first build, this contains configured defines.
            ],
            "defines": [
                "NDEBUG", "__BSD_VISIBLE",
                "__XSI_VISIBLE=500",
                "LOG_LOCAL_LEVEL=ESP_LOG_VERBOSE",
                "CONFIG_LOG_TIMESTAMP_SOURCE_RTOS",
                "CONFIG_FREERTOS_HZ=100"
            ],
            // Path to compiler perhaps has to be adjusted
            "compilerPath": "C:/espressif/tools/xtensa-lx106-elf/esp-2020r3-49-gd5524c1-8.4.0/xtensa-lx106-elf/bin/xtensa-lx106-elf-g++.exe",
            //"browse": { // Tag-Parser for Go-To-Definition-Function or tag-database. This is same as "includePath" if omitted
            "cStandard": "c11",
            "cppStandard": "c++17",
            "intelliSenseMode": "clang-x64"
        }
    ],
    "version": 4
}

tasks.json

{
    "options": {
        "env": {}
    },
    // See https://go.microsoft.com/fwlink/?LinkId=733558 
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        { // Init by MenuConfig
            "label": "Menuconfig",
            "type": "shell",
            "command": "idf.py",
            "args": [
                "menuconfig"
            ],
            "presentation": {
                "reveal": "always",
            },
            "problemMatcher": []
        },
        { // Build Environment
            "label": "Build Project",
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "type": "shell",
            "command": "idf.py",
            "args": [
                "build"
            ],
            "presentation": {
                "reveal": "always",
                "echo": true
            },
            "options": {
                "shell": {}
            },
            // "problemMatcher": ["$gcc"] // Gcc matcher does't work here
            "problemMatcher": {
                "owner": "cpp",
                "fileLocation": "absolute",
                "pattern": {
                    "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "column": 3,
                    "severity": 4,
                    "message": 5
                }
            }
        },
        { // Flash Environment and Monitor
            "label": "Flash & Monitor",
            "group": {
                "kind": "test",
                "isDefault": true
            },
            "command": "idf.py",
            "type": "shell",
            "args": [
                "-p",
                "COM${input:ComPortNum}",
                "flash",
                "monitor"
            ],
            "presentation": {
                "reveal": "always",
            },
            // "problemMatcher": ["$gcc"] // Gcc matcher does't work here
            "problemMatcher": {
                "owner": "cpp",
                "fileLocation": "absolute",
                "pattern": {
                    "regexp": "^(.*):(\\d+):(\\d+):\\s+(warning|error):\\s+(.*)$",
                    "file": 1,
                    "line": 2,
                    "column": 3,
                    "severity": 4,
                    "message": 5
                }
            }
        },
        { // Clean Project
            "label": "Clean Project",
            "command": "idf.py",
            "type": "shell",
            "args": [
                "clean"
            ],
            "problemMatcher": []
        },
        { // Full-Clean Project
            "label": "Full-Clean Project",
            "command": "idf.py",
            "type": "shell",
            "args": [
                "fullclean"
            ],
            "problemMatcher": []
        }
    ],
    "inputs": [
        {
            "id": "ComPortNum",
            "type": "promptString",
            "description": "Type the number of used COM port" // this runs obviously only on a windows machine
        }
    ]
}

If you are working on a windows machine you can also add a setup script that executes the export.sh script for you:
Create a file in ...msys32\etc\profile.d\export_idf_path.sh

# Generate Environment variable to IDF
export IDF_PATH="<parentPath2Idf>/ESP8266_RTOS_SDK"
# Exectues export.sh in IDF-Path
cd $IDF_PATH
. export.sh
### Note that you must run install.sh first

# Sets Startup initial working directory
cd <parentPath2EspProjects>/Projects
# Adds Compiler to path-variable ## Note: you certainly have to adopt it
PATH=$PATH':/c/espressif/tools/xtensa-lx106-elf/esp-2020r3-49-gd5524c1-8.4.0/xtensa-lx106-elf/bin'
# Adds Editor to path-variable ## Note: you certainly have to adopt it
PATH=$PATH':/c/Users/Jakob/AppData/Local/Programs/Microsoft VS Code'

[gbaranski]

I will also share my current version which seems to work fine, I'm using MacOS

c_cpp_properties.json

{
    "configurations": [
        {
            "name": "ESP8266",
            "includePath": [
                "${workspaceFolder}/**",
                "${workspaceFolder}/build/include/*",
                "${IDF_PATH}/components/**",
                "${IDF_PATH}/components/freertos/port/esp8266/include" // for some reason its required
            ],
            "browse": {
                "limitSymbolsToIncludedHeaders": true,
                "databaseFilename": ""
            },
            "defines": [
                "__ESP_FILE__"
            ],
            "compilerPath": "/usr/bin/gcc",
            "intelliSenseMode": "${default}"
        }
    ],
    "version": 4
}

settings.json

{
    "files.associations": {
        "freertos.h": "c"
    },
}

and .zshrc

export PATH=$PATH:$HOME/esp/xtensa-lx106-elf/bin
export IDF_PATH=$HOME/esp/ESP8266_RTOS_SDK
alias get_lx106="export PATH=$PATH:$HOME/esp/xtensa-lx106-elf/bin"

[Gustice]

The line "${IDF_PATH}/components/freertos/port/esp8266/include"
solves the ambiguous paths

• \components\freertos\include\freertos\private
• \components\freertos\port\esp8266\include\freertos

This way includes like #include "freertos/FreeRTOSConfig.h" (as in the file xtensa_timer.h) work.
Thank you for sharing, you solved one of my issues!

[gbaranski]

The line "${IDF_PATH}/components/freertos/port/esp8266/include"
solves the ambiguous paths

• \components\freertos\include\freertos\private
• \components\freertos\port\esp8266\include\freertos

This way includes like #include "freertos/FreeRTOSConfig.h" (as in the file xtensa_timer.h) work.
Thank you for sharing, you solved one of my issues!

😄

Actually I'm not really sure why this works because

"${IDF_PATH}/components/**"

should also match this

"${IDF_PATH}/components/freertos/port/esp8266/include"

[THKDev]

I recommend the use of CMake. This is well supported by VS Code. The extensions "ms-vscode.cpptools" and "ms-vscode.cmake-tools" must be installed.
Within the project folder inside the folder ".vscode" two files must be created (if not exists) and customized.

c_cpp_properties.json

{
    "configurations": [
        {
            "name": "Xtensa",
            "includePath": [
                "${workspaceFolder}/**"
            ],
            "defines": [],
            "compilerPath": "${env.HOME}/xtensa-lx106-elf-5.2.0/bin/xtensa-lx106-elf-gcc",
            "cStandard": "c99",
            "cppStandard": "c++11",
            "intelliSenseMode": "gcc-x64",
            "compileCommands": "${workspaceFolder}/build/compile_commands.json",
            "configurationProvider": "vector-of-bool.cmake-tools"
        }
    ],
    "version": 4
}

The file "compile_commands.json" is created by CMake.

cmake-kits.json

[
    {
        "name": "Xtensa Toolchain",
        "toolchainFile": "${env.HOME}/ESP8266_RTOS_SDK/tools/cmake/project.cmake",
        "environmentVariables": {
            "CC": "${env.HOME}/xtensa-lx106-elf-5.2.0/bin/xtensa-lx106-elf-g++",
            "CXX": "${env.HOME}/xtensa-lx106-elf-5.2.0/bin/xtensa-lx106-elf-gcc",
            "IDF_PATH": "${env.HOME}/ESP8266_RTOS_SDK",
            "PATH": "${env.HOME}/xtensa-lx106-elf-5.2.0/bin:${env.PATH}"
        },
        "compilers": {
            "CC": "${env.HOME}/xtensa-lx106-elf-5.2.0/bin/xtensa-lx106-elf-g++",
            "CXX": "${env.HOME}/xtensa-lx106-elf-5.2.0/bin/xtensa-lx106-elf-gcc"
        }
    }
]

When opening the project for the first time, you should be asked for a toolchain. Select Xtensa when doing so. If not, use command "CMake: Select a Kit".
After that CMake should automatically perform the configuration. If not, this can be done with the command "CMake: Configure".
With "F7" the project can be build. Errors are automatically highlighted and auto complete works too.

[ndunks]

This my minimal c_cpp_proptertios.json for build and run Blink App with Task

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                // "${workspaceRoot}/include",
                "${workspaceRoot}/build/config",
                "${env:IDF_PATH}/components/esp_common/include",
                "${env:IDF_PATH}/components/spi_flash/include",
                "${env:IDF_PATH}/components/heap/include",
                "${env:IDF_PATH}/components/heap/port/esp8266/include",
                "${env:IDF_PATH}/components/esp8266/include",
                "${env:IDF_PATH}/components/freertos/include",
                "${env:IDF_PATH}/components/freertos/include/freertos/private",
                "${env:IDF_PATH}/components/freertos/port/esp8266/include",
                "${env:IDF_PATH}/components/freertos/port/esp8266/include/freertos"
            ],
            "defines": [
                "__ESP_FILE__=\"${workspaceRoot}/main/main.c\""
            ],
            "compilerPath": "${env:HOME}/app/xtensa-lx106-elf/bin/xtensa-lx106-elf-gcc",
            "cStandard": "gnu17",
            "cppStandard": "gnu++14",
            "intelliSenseMode": "linux-gcc-x86"
        }
    ],
    "version": 4
}

[Hypnotriod]

Here is how I made my setup for windows, hope it is not outdated yet:
https://github.com/Hypnotriod/esp8266-rtos-sdk-i2c-bme280

[arduinka55055]

I get weird errors
C:/msys32/mingw32/bin/python.exe -m pip install --user -r C:/Espressif/ESP8266_RTOS_SDK/requirements.txt
Collecting setuptools>=44.0.0 (from -r C:/Espressif/ESP8266_RTOS_SDK/requirements.txt (line 4))
Downloading https://files.pythonhosted.org/packages/e1/b7/182161210a13158cd3ccc41ee19aadef54496b74f2817cc147006ec932b4/setuptools-44.1.1-py2.py3-none-any.whl (583kB)
100% |UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU| 583kB 6.0MB/s
Collecting click>=5.0 (from -r C:/Espressif/ESP8266_RTOS_SDK/requirements.txt (line 8))
Using cached https://files.pythonhosted.org/packages/d2/3d/fa76db83bf75c4f8d338c2fd15c8d33fdd7ad23a9b5e57eb6c5de26b430e/click-7.1.2-py2.py3-none-any.whl
Requirement already satisfied: pyserial>=3.0 in c:\msys32\mingw32\lib\python2.7\site-packages (from -r C:/Espressif/ESP8266_RTOS_SDK/requirements.txt (line 9)) (3.4)
Requirement already satisfied: future>=0.15.2 in c:\msys32\mingw32\lib\python2.7\site-packages (from -r C:/Espressif/ESP8266_RTOS_SDK/requirements.txt (line 10)) (0.16.0)
Requirement already satisfied: cryptography<35,>=2.1.4 in c:\msys32\mingw32\lib\python2.7\site-packages (from -r C:/Espressif/ESP8266_RTOS_SDK/requirements.txt (line 11)) (2.3.1)
Requirement already satisfied: pyparsing<2.4.0,>=2.0.3 in c:\msys32\mingw32\lib\python2.7\site-packages (from -r C:/Espressif/ESP8266_RTOS_SDK/requirements.txt (line 12)) (2.2.0)
Collecting pyelftools>=0.22 (from -r C:/Espressif/ESP8266_RTOS_SDK/requirements.txt (line 13))
Using cached https://files.pythonhosted.org/packages/88/56/0f2d69ed9a0060da009f672ddec8a71c041d098a66f6b1d80264bf6bbdc0/pyelftools-0.31.tar.gz
Missing build requirements in pyproject.toml for pyelftools>=0.22 from https://files.pythonhosted.org/packages/88/56/0f2d69ed9a0060da009f672ddec8a71c041d098a66f6b1d80264bf6bbdc0/pyelftools-0.31.tar.gz#sha256=c774416b10310156879443b81187d182d8d9ee499660380e645918b50bc88f99 (from -r C:/Espressif/ESP8266_RTOS_SDK/requirements.txt (line 13)).
This version of pip does not implement PEP 517 so it cannot build a wheel without 'wheel'.
Installing build dependencies ... error
Complete output from command C:/msys32/mingw32/bin/python.exe -m pip install --ignore-installed --no-user --prefix c:\users\denis\appdata\local\temp\pip-build-env-zvvmci --no-warn-script-location --no-binary :none: --only-binary :none: -i https://pypi.org/simple -- "setuptools >= 46.4.0":
Collecting setuptools>=46.4.0
Could not find a version that satisfies the requirement setuptools>=46.4.0 (from versions: VERY LONG LIST OF VERSIONS
No matching distribution found for setuptools>=46.4.0

---

Command "C:/msys32/mingw32/bin/python.exe -m pip install --ignore-installed --no-user --prefix c:\users\denis\appdata\local\temp\pip-build-env-zvvmci --no-warn-script-location --no-binary :none: --only-binary :none: -i https://pypi.org/simple -- "setuptools >= 46.4.0"" failed with error code 1 in None

[Wichamir]

For anyone wondering about this in 2025, the setup for Linux that seems to work perfectly is quite simple:

{
  "name": "Linux",
  "includePath": [
    "${workspaceFolder}/**", // some configuration files are written to build directory
    "${env:IDF_PATH}/components/**" // SDK libraries
  ],
  "defines": [
     "__ESP_FILE__" // variable parsing doesn't work in defines section, so using ${file} here won't work
  ],
  "compilerPath": "${env:HOME}/esp/xtensa-lx106-elf/bin/xtensa-lx106-elf-gcc", // if you set the compiler path right, then it takes care of include ambiguities
  "cStandard": "c17",
  "cppStandard": "gnu++17",
  "intelliSenseMode": "linux-gcc-x86" // the xtensa compiler is a variant of gcc, however there is no perfect match for the architecture, but x86 should be good enough, since ESPs use 32-bit architecture
}