Create an ESP-IDF Project

[中文]

You can start a project in three ways:

  1. Using ESP-IDF: New Project

  2. Using ESP-IDF: Show Examples Projects

  3. Opening an Existing ESP-IDF Project

The first option is recommended because it allows to configure the project. The second and third options create the project with the current workspace folder configuration.

Using ESP-IDF: New Project

In Visual Studio Code:

  • Navigate to View > Command Palette.

  • Type ESP-IDF: New Project and select the command to launch the New Project wizard.

    _images/new_project_init.png

  • Choose the project name.

  • Choose the location for the new project.

  • Select the Espressif board you are using.

  • Select the serial port of the device (a list of currently connected serial devices appears in the dropdown).

    Note

    If you are not sure about the serial port name, refer to Establish Serial Communication.

    Note

    Please refer to Configuration of OpenOCD for Specific Target to select the appropriate OpenOCD configuration file based on your hardware.

  • Optionally, you can import any ESP-IDF component directory component-dir to the new project. This will copy it to the new project’s components subdirectory (<project-dir>/components/component-dir).

  • Click the Choose Template button.

  • Select ESP-IDF from the dropdown if you want to use a template.

    Note

    If you want to create a blank project, choose ESP-IDF sample_project or Extension template-app.

    _images/new_project_templates.png

  • Choose your desired template and click the Create Project Using Template <template-name> button, where <template-name> is the name of the selected template.

  • After the project is created, a notification window will appear, asking whether to open the newly created project.

_images/new_project_confirm.png

Using ESP-IDF: Show Examples Projects

In Visual Studio Code:

  • Navigate to View > Command Palette.

  • Type ESP-IDF: Show Examples Projects and select the command to create a new project from ESP-IDF examples.

  • Select ESP-IDF from the dropdown. A window will appear, showing a list of ESP-IDF examples.

  • When you select an example, the README file will appear along with a Create project using example example_name button.

  • Choose a destination for the new project. A notification will prompt you to open the folder in a new window.

_images/new_project_confirm.png

Opening an Existing ESP-IDF Project

ESP-IDF projects follow this directory structure:

ESP-IDF Example Project

- myProject/
            - CMakeLists.txt
            - sdkconfig
            - components/ - component1/ - CMakeLists.txt
                                        - Kconfig
                                        - src1.c
                          - component2/ - CMakeLists.txt
                                        - Kconfig
                                        - src1.c
                                        - include/ - component2.h
            - main/       - CMakeLists.txt
                          - src1.c
                          - src2.c

            - build/

In Visual Studio Code:

  • Navigate to View > Command Palette.

  • Type ESP-IDF: Import ESP-IDF Project and select the command to import an existing ESP-IDF project.

This command adds both Visual Studio Code configuration files (settings.json, launch.json) and Docker container files (Dockerfile and .devcontainer.json).

The next step is to Connect a device.

Adding Visual Studio Code configuration files and Docker container

In Visual Studio Code, go to File > Open Folder and open a directory containing a CMakeLists.txt file in the root (e.g., myProject), which follows the ESP-IDF structure.

  1. To add Visual Studio Code configuration files (settings.json, launch.json):

    • Navigate to View > Command Palette.

    • Type ESP-IDF: Add .vscode Configuration Folder and select the command.

  2. To open the project within the ESP-IDF Docker container:

    • Navigate to View > Command Palette.

    • Type ESP-IDF: Add Docker Container Configuration and select the command to add the .devcontainer directory to your current directory.

    • Navigate to View > Command Palette.

    • Type Dev Containers: Open Folder in Remote Container and select the command to open the existing project inside the container created from the Dockerfile in the previous step.