2021/12/25 vscode-esp-idf-extension/SETUP.

md at e80c37e14833851afcf8b7d24026a60e8a2dea2e · espressif/vscode-esp-idf-extension · Git…

espressif / vscode-esp-idf-extension Public

Code Issues 4 Pull requests 4 Actions Projects

e80c37e148

vscode-esp-idf-extension / docs / SETUP.md

brianignacio5 fix docs links and show prerequisites link in setup wizard (#528) …

1 contributor

169 lines (116 sloc) 10.1 KB

ESPRESSIF IDF extension for Visual Studio

Code

Table Of Contents (TOC)

1. Self-configuration
2. Setup wizard
3. Extension manual configuration using Preferences: Open Settings (JSON)
4. Extension manual configuration using Preferences: Open Settings (UI)
5. Extension configuration example

NOTE: Make sure to install the extension prerequisites and, if using WSL2, the
required packages specified in WSL Documentation.

Extension activation self configuration

https://github.com/espressif/vscode-esp-idf-extension/blob/HEAD/docs/SETUP.md 1/6
2021/12/25 vscode-esp-idf-extension/SETUP.md at e80c37e14833851afcf8b7d24026a60e8a2dea2e · espressif/vscode-esp-idf-extension · Git…

When you start ESP-IDF extension, it will try to self-configure by looking for existing
ESP-IDF directory in IDF_PATH environment variable, $HOME/esp/esp-idf on
MacOS/Linux and %USERPROFILE%\esp\esp-idf or %USERPROFILE%\Desktop\esp-idf in
Windows. It will look for ESP-IDF Tools and ESP-IDF Python virtual environment in
IDF_TOOLS_PATH environment variable, $HOME\.espressif on MacOS/Linux and
%USERPROFILE%\.espressif on Windows.

If ESP-IDF and corresponding ESP-IDF tools are found, these paths will be saved as
Visual Studio Code Configuration settings, which are located in Command Palette (F1 or
View Menu -> Command Palette) and type Preferences: Open Settings (UI) or
Command Palette (F1 or View Menu -> Command Palette) and type Preferences: Open
Settings (JSON) .

These settings, as described in ESP-IDF Specific Settings, are:

idf.espIdfPath for IDF_PATH,

idf.customExtraPaths for ESP-IDF Tools paths to be appended to environment

variable PATH,
idf.pythonBinPath for absolute virtual environment python path and

idf.customExtraVars for additional environment variables from ESP-IDF tools such

as OPENOCD_SCRIPTS.

NOTE: Visual Studio Code has many places where to set configuration settings.
This extension uses the idf.saveScope configuration setting to determine where
to save settings, Global (User Settings), Workspace and WorkspaceFolder. Please
review the visual studio code settings precedence.

If ESP-IDF and ESP-IDF tools are not available, you can use the Setup Wizard to
download them and configure the extension for you or manually configure the
extension as explained in JSON Manual Configuration or Settings UI Manual
Configuration .

Setup Wizard
With Visual Studio Code Command Palette (F1 or View Menu -> Command Palette) and
type ESP-IDF: Configure ESP-IDF extension.

Setup wizard provides 3 choices:

Express install: Fastest option.

i. Choose to either download selected ESP-IDF version or find ESP-IDF in your
system.
ii. Download and install ESP-IDF Tools. This step will use the existing value in
idf.toolsPath or idf.toolsPathWin as ESP-IDF Tools directory.

https://github.com/espressif/vscode-esp-idf-extension/blob/HEAD/docs/SETUP.md 2/6
2021/12/25 vscode-esp-idf-extension/SETUP.md at e80c37e14833851afcf8b7d24026a60e8a2dea2e · espressif/vscode-esp-idf-extension · Git…

iii. Create python virtual environment with required packages on existing ESP-IDF
Tools directory.
Advanced install: Configurable option.
i. Choose to either download selected ESP-IDF version or find ESP-IDF in your
system.
ii. Download or use existing ESP-IDF Tools:
Choose directory for ESP-IDF Tools and install ESP-IDF Tools. This step will
update the existing value in idf.toolsPath or idf.toolsPathWin .
Specify directory than contains executable for each required ESP-IDF tool
with matching version.
iii. Create python virtual environment with required packages in chosen ESP-IDF
Tools directory.
Use existing setup: This option will use an existing setup if:
i. esp-idf.json is found in the current idf.toolsPath (MacOS/Linux users) or
idf.toolsPathWin (Windows users). This file is generated when you install
ESP-IDF with the IDF Windows installer or using IDF-ENV.
ii. ESP-IDF is found in idf.espIdfPath or idf.espIdfPathWin , IDF_PATH
environment variable, $HOME/esp/esp-idf on MacOS/Linux and
%USERPROFILE%\esp\esp-idf or %USERPROFILE%\Desktop\esp-idf in Windows.

iii. ESP-IDF Tools and ESP-IDF Python virtual environment for the previos ESP-IDF
are found in idf.toolsPath or idf.toolsPathWin , IDF_TOOLS_PATH
environment variable, $HOME\.espressif on MacOS/Linux and
%USERPROFILE%\.espressif on Windows.

NOTE: Make sure that IDF_PATH and IDF_TOOLS_PATH doesn't have any spaces to
avoid any build issues.

After choosing any of the previous options, a status page is displayed showing ESP-IDF,
tools and python environment setup progress status. When the setup is finished, a
message is shown that "All settings have been configured. You can close this window."

NOTE: Check the troubleshooting section if you have any issue.

JSON Manual Configuration

The user can manually configure the extension by setting the following configuration
settings with corresponding values. Please take a look at Configuration settings for
more information.

1. With Visual Studio Code Command Palette (F1 or View Menu -> Command
Palette) and type Preferences: Open Settings (JSON). This will open the user
global settings for Visual Studio Code.

https://github.com/espressif/vscode-esp-idf-extension/blob/HEAD/docs/SETUP.md 3/6
2021/12/25 vscode-esp-idf-extension/SETUP.md at e80c37e14833851afcf8b7d24026a60e8a2dea2e · espressif/vscode-esp-idf-extension · Git…

NOTE: The user could choose to modify its workspace settings.json for a
workspace limited configuration or a project limited configuration in the
project's .vscode/settings.json . Please take a look at Working with multiple
projects.

2. Your settings.json should look like:

MacOS/Linux

{
"idf.espIdfPath": "path/to/esp-idf",
"idf.customExtraPaths": "UPDATED_PATH",
"idf.customExtraVars": "{\"OPENOCD_SCRIPTS\":\"OPENOCD_FOLDER/share/openocd/scr
"idf.pythonBinPath": "PYTHON_INTERPRETER",
"idf.openOcdConfigs": [
"interface/ftdi/esp32_devkitj_v1.cfg",
"board/esp32-wrover.cfg"
],
"idf.port": "DEVICE_PORT"
}

Windows

{
"idf.espIdfPathWin": "path/to/esp-idf",
"idf.customExtraPaths": "UPDATED_PATH",
"idf.customExtraVars": "{\"OPENOCD_SCRIPTS\":\"OPENOCD_FOLDER/share/openocd/scr
"idf.pythonBinPathWin": "PYTHON_INTERPRETER",
"idf.openOcdConfigs": [
"interface/ftdi/esp32_devkitj_v1.cfg",
"board/esp32-wrover.cfg"
],
"idf.portWin": "DEVICE_PORT"
}

where:

UPDATED_PATH is the "Updated PATH variable" generated by

$IDF_PATH/export.sh ,

PYTHON_INTERPRETER is the "Using Python interpreter in" value generated by

$IDF_PATH/export.sh ,

DEVICE_PORT is your device serial port (i.e. COM1, /dev/cu.usbserial-1433401 or

/dev/ttyUSB1)
idf.openOcdConfigs are the config files used for OpenOCD for your device
(relative paths to OPENOCD_SCRIPTS directory of OpenOCD-ESP32 tool).

https://github.com/espressif/vscode-esp-idf-extension/blob/HEAD/docs/SETUP.md 4/6
2021/12/25 vscode-esp-idf-extension/SETUP.md at e80c37e14833851afcf8b7d24026a60e8a2dea2e · espressif/vscode-esp-idf-extension · Git…

DO NOT USE ~, $HOME OR %USERPROFILE% ENVIRONMENT VARIABLES ARE NOT

RESOLVED IN THIS CONFIGURATION SETTINGS. You must use ${env:HOME} instead
of $HOME (Linux/MacOS) or %HOME% (Windows).

NOTE: Make sure that your configurations settings doesn't have any spaces to
avoid any build issues.

Make sure to install the extension and extension debug adapter Python requirements
by running the following commands in your terminal:

PYTHON_INTERPRETER -m pip install --upgrade -r EXTENSION_PATH/requirements.txt

PYTHON_INTERPRETER -m pip install --upgrade -r

EXTENSION_PATH/esp_debug_adapter/requirements.txt

where EXTENSION_PATH is

%USERPROFILE%\.vscode\extensions\espressif.esp-idf-extension-VERSION on
Windows
$HOME/.vscode/extensions/espressif.esp-idf-extension-VERSION on Linux/MacOS

UI Manual Configuration
This is the same as JSON Manual Configuration but the name of each configuration
setting is the description given in the ESP-IDF Settings. This method also need to install
extension and debug adapter requirements.txt as shown in the previous section.

Example configuration setting values

An example ESP-IDF path is to set idf.espIdfPath to /home/myUser/to/esp-idf
(MacOS/Linux) or set idf.espIdfPathWin to C:\Users\myUser\esp\esp-idf (Windows)

An example python path for idf.pythonBinPath (MacOS/Linux) is

/home/myUser/.espressif/python_env/idf4.0_py3.5_env/bin/python

An example python path for idf.pythonBinPathWin (Windows) is

C:\Users\myUser\.espressif\python_env\idf4.0_py3.5_env\Scripts\python.exe

For example if required ESP-IDF Tools are:

https://github.com/espressif/vscode-esp-idf-extension/blob/HEAD/docs/SETUP.md 5/6
2021/12/25 vscode-esp-idf-extension/SETUP.md at e80c37e14833851afcf8b7d24026a60e8a2dea2e · espressif/vscode-esp-idf-extension · Git…

OpenOCD executable path is /home/myUser/.espressif/tools/openocd-

esp32/version/openocd-esp32/bin/openocd or
C:\Users\myUser\.espressif\tools\openocd-esp32\version\openocd-
esp32\bin\openocd (Windows)

XtensaEsp32 executable path is /home/myUser/.espressif/tools/xtensa-

esp32/version/xtensa-esp32/bin/xtensa-esp32-gcc or
C:\Users\myUser\.espressif\tools\xtensa\version\xtensa-esp32\bin\xtensa-
esp32-gcc (Windows)

you need to set in idf.customExtraPaths :

Linux/MacOS

/home/myUser/.espressif/tools/openocd/version/openocd-
esp32/bin:/home/myUser/.espressif/tools/xtensa-esp32/version/xtensa-esp32/bin

Windows

C:\Users\myUser\.espressif\tools\openocd-esp32\version\openocd-
esp32\bin;C:\Users\myUser\.espressif\tools\xtensa-esp32\version\xtensa-
esp32\bin

idf.customExtraVars is an stringified JSON object saved in Visual Studio Code's

settings.json (Make sure to replace ${TOOL_PATH} with the existing tool directory
path):

"idf.customExtraVars": "
{\"OPENOCD_SCRIPTS\":\"/home/myUser/.espressif/tools/openocd-
esp32/version/openocd-esp32/share/openocd/scripts\"}"

The list of required ESP-IDF Tools ( idf.customExtraPaths ) and environment variables

( idf.customExtraVars ) can be found in $IDF_PATH/tools/tools.json

NOTE: Make sure to replace ${TOOL_PATH} of $IDF_PATH/tools/tools.json

in idf.customExtraPaths and idf.customExtraVars with existing ESP-IDF tool
directory path.

idf.openOcdConfigs use openOCD Configuration files depending on your board and

chip target. More information here.

https://github.com/espressif/vscode-esp-idf-extension/blob/HEAD/docs/SETUP.md 6/6