Skip to content

Latest commit

 

History

History
92 lines (58 loc) · 7.23 KB

ONBOARDING.md

File metadata and controls

92 lines (58 loc) · 7.23 KB

Onboarding ESP-IDF Extension

When you start ESP-IDF extension, the onboarding window can help you set up ESP-IDF, ESP-IDF Tools and their Python requirements to easily start working on your projects.

Prerequisites

Install ESP-IDF Prerequisites for your operating system.

For this extension you also need Python 3.5+ and Git. If you are on MacOS and Linux, you also need to preinstall CMake and Ninja-build (and add them to idf.customExtraPaths in Step 4). For Windows users, CMake and Ninja are downloaded in step 3 Tools Downloads.

Installed ESP-IDF following the Espressif documentation and want to reuse it in the extension.

If you installed ESP-IDF and ESP-IDF Tools following ESP-IDF Get Started then you can configure the extension following these steps:

Directly modify settings.json

  1. In Visual Studio Code press F1 and type "Preferences: Open Settings (JSON)". This will open your user global settings for Visual Studio Code. You could choose to modify your workspace settings.json if you want these settings for a specific workspace or within a specific project .vscode/settings.json.
  2. Your settings.json should look like:
{
    ...,
    "idf.espIdfPath": "path/to/esp-idf",
    "idf.customExtraPaths": "UPDATED_PATH",
    "idf.customExtraVars": "{\"OPENOCD_SCRIPTS\":\"OPENOCD_FOLDER/share/openocd/scripts\"}",
    "idf.pythonBinPath": "PYTHON_INTERPRETER",
    "idf.port": "DEVICE_PORT",
    "idf.openOcdConfigs": [
        "interface/ftdi/esp32_devkitj_v1.cfg",
        "board/esp32-wrover.cfg"
    ],
}

where UPDATED_PATH is the "Updated PATH variable" generated by $IDF_PATH/export.sh, PYTHON_INTERPRETER is the "Using Python interpreter in" generated by $IDF_PATH/export.sh, the device port is your device serial port (COM1, /dev/cu.usbserial-1433401, etc) and idf.openOcdConfigs are the config files used for OpenOCD for your device (they are relative to OPENOCD_SCRIPTS directory).

Using Preferences: Open Settings (UI)

This is the same as previous sections but the name of each configuration setting is the description given in the Readme ESP-IDF Settings section.

Using ESP-IDF: Configure ESP-IDF extension window

Follow the next section steps without downloading the ESP-IDF Tools. On Step 3, Skip Tools download and manually set them. First set PYTHON_INTERPRETER in the first input, UPDATED_PATH in the second input (make sure CMake and Ninja-build directories are part of these paths) and the correct value for OPENOCD_SCRIPTS (replace ${TOOL_PATH} with OpenOCD directory) as well as other variables shown.

How to configure this extension from zero using ESP-IDF: Configure ESP-IDF extension window

  1. Press START on the onboarding window and check that git is installed. Also select the Python executable to use in this extension. The python executable is persisted for the current onboarding session to create a python virtual environment in step 3, sub-item 1.

  2. Go to Configure ESP-IDF to download ESP-IDF or select an existing ESP-IDF folder in your system. In this window you can select the version you wish to download and the path to install it or you can select ESP-IDF directory, which will be validated. This path is saved as idf.espIdfPath which is used to replace system environment variable IDF_PATH (inside Visual Studio Code only) before running extension commands.

  3. Go to Configure ESP-IDF Tools will allow you to download required ESP-IDF Tools or manually set them.

    1. If you are downloading them, choose the directory where to install them (Default directory is $HOME/.espressif for Linux/MacOS users or %USER_PROFILE%.espressif for Windows users) which will saved as idf.toolsPath. After installing the ESP-IDF Tools, a python virtual environment will be created for ESP-IDF in ${idf.toolsPath}/python_env and the virtualenv python full path executable will be saved in idf.pythonBinPath or idf.pythonBinPathWin for Windows users. This python executable will be used to execute all python dependent commands in this ESP-IDF extension. After you download the ESP-IDF Tools, their bin folder directories will be set in idf.customExtraPaths and their required environment variables in idf.customExtraVars (such as OPENOCD_SCRIPTS).

  4. The next step is to verify each installed tool version is correct for the idf.espIdfPath ESP-IDF. If you skipped ESP-IDF tools download, you need to manually set each tool bin directory in idf.customExtraPaths by typing all required tools executable location separated by ; (Windows users) or : (Linux/MacOS users), the virtual environment python executable absolute path, which is saved in idf.pythonBinPath and is used to test all ESP-IDF requirements.txt are fulfilled as well; and the idf.customExtraVars with correct values for environment variables such as OPENOCD_SCRIPTS, which is used to find the OpenOCD configuration files specified in idf.openOcdConfigs.

DO NOT USE ~, $HOME OR %USERPROFILE%, ENVIRONMENT VARIABLES ARE NOT RESOLVED IN THIS CONFIGURATION SETTINGS.. You could use ${env:HOME} to refer to $HOME (Linux/MacOS) or %HOME% (Windows).

An example python path for idf.pythonBinPath is /home/myUser/.espressif/python_env/idf4.0_py3.5_env/bin/python for MacOS/Linux users or C:\Users\myUser.espressif\python_env\idf4.0_py3.5_env\Scripts\python.exe for Windows users.

For example if

  • OpenOCD executable path is /home/myUser/.espressif/tools/openocd/version/openocd-esp32/bin/openocd or C:\Users\myUser.espressif\tools\openocd\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:

  • /home/myUser/.espressif\tools\openocd\version\openocd-esp32\bin:/home/myUser//.espressif/tools/xtensa-esp32/version/xtensa-esp32/bin (Linux/MacOS users) or
  • C:\Users\myUser.espressif\tools\openocd\version\openocd-esp32\bin;C:\Users\myUser.espressif\tools\xtensa-esp32\version\xtensa-esp32\bin (Windows users).

idf.customExtraVars is an object saved in Visual Studio Code's settings.json that looks like this (Make sure to replace ${TOOL_PATH} with the tool path):

{
    ...,
    OPENOCD_SCRIPTS: "...",
    OTHER_ENV_VAR: "...",
    ...
}

The list of required idf.customExtraVars will be shown in the current step (Verify ESP-IDF Tools) and they should be filled for the extension to work properly.

  1. After verifying ESP-IDF tools and required python packages, the extension has been configured correctly. An option to open ESP-IDF: Show examples is shown.

Here is diagram to configure ESP-IDF extension:

Onboarding

Notes

If you try to download ESP-IDF in a directory where a folder esp-idf already exists an error will be shown. Please delete this esp-idf folder or choose another destination directory.