From 7862bbf23c2dcddc9b2bd147c983a5c04351bf22 Mon Sep 17 00:00:00 2001 From: shenmengjing Date: Tue, 5 Nov 2024 11:46:59 +0800 Subject: [PATCH] docs: Provide CN translation for README.md --- README.md | 195 ++++++++-------- README_CN.md | 621 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 719 insertions(+), 97 deletions(-) create mode 100644 README_CN.md diff --git a/README.md b/README.md index 897dbcd2c..349527239 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,9 @@ espressif logo -# ESP-IDF Extension for VSCode +# ESP-IDF Extension for VS Code + +[中文](./README_CN.md) [![Tutorials](https://img.shields.io/badge/-Tutorials-red)](./docs/tutorial/toc.md) [![Espressif Documentation](https://img.shields.io/badge/Documentation-red)](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/) @@ -14,7 +16,7 @@ Develop, build, flash, monitor, debug and [more](./docs/FEATURES.md) with Espressif chips using Espressif IoT Development Framework [(ESP-IDF)](https://github.com/espressif/esp-idf). -**Latest master installer** for Visual Studio Code. You can use this VSIX to test the current github master of the extension by pressing F1 or click menu `View` -> `Command Palette...`, type `Install from VSIX` and then select the previously downloaded `.vsix` file to install the extension. +**Latest master installer** for Visual Studio Code. You can use this VSIX to test the current github master of the extension by pressing F1 or click menu `View` -> `Command Palette...`, type `Install from VSIX` and then select the previously downloaded `.vsix` file to install the extension. Make sure to review our [Espressif documentation](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/) or [Github documentation](./docs/ONBOARDING.md) first to properly use the extension. @@ -22,25 +24,24 @@ Make sure to review our [Espressif documentation](https://docs.espressif.com/pro ## Install -1. Download and install [Visual Studio Code](https://code.visualstudio.com/). +1. Download and install [Visual Studio Code](https://code.visualstudio.com/). -2. Install ESP-IDF system prerequisites for your operating system: +2. Install ESP-IDF system prerequisites for your operating system: -- Prerequisites for [MacOS](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/macos-setup.html#install-prerequisites) -- Prerequisites for [Linux](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-setup.html#install-prerequisites) +- Prerequisites for [MacOS and Linux](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/macos-setup.html#install-prerequisites). - For Windows there is no additional prerequisites. -3. In Visual Studio Code, Open the **Extensions** view by clicking on the Extension icon in the Activity Bar on the side of Visual Studio Code or the **View: Extensions** command (shortcut: ⇧ ⌘ X or Ctrl+Shift+X. +3. In Visual Studio Code, Open the **Extensions** view by clicking on the Extension icon in the Activity Bar on the side of Visual Studio Code or the **View: Show Extensions** command (shortcut: ⇧ ⌘ X or Ctrl+Shift+X). 4. Search for [ESP-IDF Extension](https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension). -5. Install the extension. After you install the extension, the ![Espressif icon](./media/readme/espressifIcon.png) should appear in the VS Code Activity bar (left side set of icons). When you click the Espressif icon you can see a list of the basic commands provided by this extension. +5. Install the extension. After you install the extension, the ![Espressif icon](./media/readme/espressifIcon.png) should appear in the VS Code Activity bar (left side set of icons). When you click the Espressif icon, you can see a list of basic commands provided by this extension.

Commands list

-6. From the command list select **Configure ESP-IDF Extension** or press F1 and type `Configure ESP-IDF Extension`. After, choose the **ESP-IDF: Configure ESP-IDF Extension** option. +6. From the command list, select **Configure ESP-IDF Extension** or press F1 and type `Configure ESP-IDF Extension`. After, choose the **ESP-IDF: Configure ESP-IDF Extension** option. > **NOTE:** For versions of ESP-IDF < 5.0, spaces are not supported inside configured paths.

@@ -49,20 +50,20 @@ Make sure to review our [Espressif documentation](https://docs.espressif.com/pro 7. Choose **Express** and select the download server: -- Espressif: Faster speed in China using Espressif Download servers links. +- Espressif: Faster speed in China using Espressif download servers links. - Github: Using github releases links. 8. Pick an ESP-IDF version to download or the `Find ESP-IDF in your system` option to search for existing ESP-IDF directory. 9. Choose the location for ESP-IDF Tools (also known as `IDF_TOOLS_PATH`) which is `$HOME\.espressif` on MacOS/Linux and `%USERPROFILE%\.espressif` on Windows by default. -10. If your operating system is MacOS/Linux, choose the system python executable to create ESP-IDF virtual environment inside ESP-IDF Tools and install ESP-IDF python package there. +10. If your operating system is MacOS/Linux, choose the system Python executable to create ESP-IDF virtual environment inside ESP-IDF Tools and install ESP-IDF Python package there. - > **NOTE:** Windows users don't need to select a python executable since it is going to be installed by this setup. + > **NOTE:** Windows users don't need to select a Python executable since it is going to be installed by this setup. 11. Make sure that `IDF_TOOLS_PATH` doesn't have any spaces to avoid any build issues. Also make sure that `IDF_TOOLS_PATH` is not the same directory as `IDF_PATH`. -12. You will see a page showing the setup progress status showing ESP-IDF download progress, ESP-IDF Tools download and install progress as well as the creation of a python virtual environment. +12. You will see a page showing the setup progress status, including ESP-IDF download progress, ESP-IDF Tools download and install progress as well as the creation of a Python virtual environment. 13. If everything is installed correctly, you will see a message that all settings have been configured. You can start using the extension. @@ -80,29 +81,29 @@ These icons will be used in the steps below showing common ESP-IDF use cases: 1. Press F1 and type **ESP-IDF: Show Examples Projects** to create a new project from ESP-IDF examples. Select ESP-IDF and choose an example to create a new project from. -2. Once the project is created and opened in VS Code, Set the serial port of your device by pressing status bar icon ![serial port](./media/readme/serialport.png) or F1, typing **ESP-IDF: Select Port to Use:** and choosing the serial port your device is connected. +2. Once the project is created and opened in VS Code, set the serial port of your device by clicking status bar icon ![serial port](./media/readme/serialport.png). Alternatively, press F1, type **ESP-IDF: Select Port to Use**, and choose the serial port to which your device is connected. -3. Select an Espressif target (esp32, esp32s2, etc.) by pressing status bar icon ![IDF Target](./media/readme/target.png) or F1 and type **ESP-IDF: Set Espressif Device Target** command. +3. Select an Espressif target (esp32, esp32s2, etc.) by clicking status bar icon ![IDF Target](./media/readme/target.png). Alternatively, press F1 and type **ESP-IDF: Set Espressif Device Target** command. -4. Next configure your ESP-IDF project by pressing status bar icon ![sdkconfig editor](./media/readme/sdkconfig.png) or press F1 and typing **ESP-IDF: SDK Configuration Editor** command (CTRL E G keyboard shortcut ) where you can modify the ESP-IDF project settings. After all changes are made, click save and close this window. You can see the output in the menu `View` -> `Output` and choose `ESP-IDF` from the dropdown list. +4. Next, configure your ESP-IDF project by clicking status bar icon ![sdkconfig editor](./media/readme/sdkconfig.png) or press F1 and typing **ESP-IDF: SDK Configuration Editor** command (CTRL E G keyboard shortcut) where you can modify the ESP-IDF project settings. After all changes are made, click `Save` and close this window. You can see the output in the menu `View` -> `Output` and choose `ESP-IDF` from the dropdown list. -5. (OPTIONAL) Run **ESP-IDF: Run idf.py reconfigure task** to generate the compile_commands.json file so language support works. Additionally you can configure the `.vscode/c_cpp_properties.json` as explained in [C/C++ Configuration](./docs/C_CPP_CONFIGURATION.md) documentation. +5. (OPTIONAL) Run **ESP-IDF: Run idf.py reconfigure task** to generate the `compile_commands.json` file so language support works. Additionally, you can configure the `.vscode/c_cpp_properties.json` as explained in [C/C++ Configuration](./docs/C_CPP_CONFIGURATION.md) documentation. -6. At this point you can modify the code and when the project is completed, build your project by pressing status bar icon ![build](./media/readme/build.png) or press F1 and typing **ESP-IDF: Build your Project**. +6. At this point, you can modify the code. When the project is completed, build your project by clicking status bar icon ![build](./media/readme/build.png) or pressing F1 and typing **ESP-IDF: Build your Project**. -7. Flash to your device by pressing status bar icon ![flash](./media/readme/flash.png) or F1 and typing **ESP-IDF: Flash your project** to select either `UART`, `DFU` or `JTAG` depending on your serial connection, and start flashing the application to your device. +7. Flash to your device by clicking status bar icon ![flash](./media/readme/flash.png), or pressing F1 and typing **ESP-IDF: Flash your project**. From there, select `UART`, `DFU` or `JTAG` depending on your serial connection, and start flashing the application to your device. -8. Change the flash method pressing status bar icon ![flash method](./media/readme/flashmethod.png) or F1 and typing **ESP-IDF: Select Flash Method** to select either `UART`, `DFU` or `JTAG`. You can alternatively use the **ESP-IDF: Flash (UART) your Project**, **ESP-IDF: Flash (with JTag)** or **ESP-IDF: Flash (DFU) your project**. +8. Change the flash method by clicking status bar icon ![flash method](./media/readme/flashmethod.png), or pressing F1 and typing **ESP-IDF: Select Flash Method** to select from `UART`, `DFU` or `JTAG`. You can alternatively use one of the commands **ESP-IDF: Flash (UART) your Project**, **ESP-IDF: Flash (with JTAG)** or **ESP-IDF: Flash (DFU) your project**. -9. Start a monitor by pressing status bar icon ![monitor](./media/readme/monitor.png) or F1 and typing **ESP-IDF: Monitor Device** which will log the device activity in a Visual Studio Code terminal. +9. Start a monitor by clicking status bar icon ![monitor](./media/readme/monitor.png), or pressing F1 and typing **ESP-IDF: Monitor Device**, which will log the device activity in a Visual Studio Code terminal. 10. Make sure to configure your drivers as mentioned in ESP-IDF [Configure JTAG Interface](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html) documentation. -11. Before debugging your device, select the device OpenOCD board configuration files by pressing F1 and typing **ESP-IDF: Select OpenOCD Board Configuration**. You can test the connection by pressing status bar icon ![openocd](./media/readme/openocd.png) or F1 and typing **ESP-IDF: OpenOCD Manager**. The output is shown in the menu `View` -> `Output` and choose `ESP-IDF` from the dropdown list. +11. Before debugging your device, select the device OpenOCD board configuration files by pressing F1 and typing **ESP-IDF: Select OpenOCD Board Configuration**. You can test the connection by clicking status bar icon ![openocd](./media/readme/openocd.png) or pressing F1 and typing **ESP-IDF: OpenOCD Manager**. The output is shown in the menu `View` -> `Output` and choose `ESP-IDF` from the dropdown list. - > **NOTE:** you can start or stop the OpenOCD from Visual Studio Code using the **ESP-IDF: OpenOCD Manager** command or from the `OpenOCD Server (Running | Stopped)` button in the visual studio code status bar. + > **NOTE:** You can start or stop the OpenOCD in Visual Studio Code using the **ESP-IDF: OpenOCD Manager** command or by clicking the `OpenOCD Server (Running | Stopped)` button in the status bar. -12. If you want to start a debug session, just press `F5` (make sure you had at least build, flash and OpenOCD is connecting correctly so the debugger works correctly). The debug session output can be seen in the menu `View` -> `Debug Console`. +12. If you want to start a debug session, just press F5 (ensure the project is built, flashed, and OpenOCD is properly connected for the debugger to function correctly). The debug session output can be seen in the menu `View` -> `Debug Console`. Check the [Troubleshooting](#Troubleshooting) section if you have any issues. @@ -114,58 +115,59 @@ You can find a list of tutorials, commands and documentation about all features - Check all the extension [tutorials](./docs/tutorial/toc.md). -- Check all the extension [github documentation](./docs/ONBOARDING.md). +- Check all the extension [GitHub documentation](./docs/ONBOARDING.md). -## All Available commands +## All Available Commands -Click F1 or click menu `View` -> `Command Palette...` to show Visual studio code commands, then type **ESP-IDF** to see all possible extension commands. +Press F1 or click menu `View` -> `Command Palette...` to show Visual Studio code commands, then type **ESP-IDF** to see all available extension commands. - + - + - + + + Dev Containers extension. - + - + - + - - @@ -173,20 +175,19 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual - + - + - + @@ -204,20 +205,20 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual - + - + - + @@ -229,45 +230,44 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual - + - + - + - + - + - + - + @@ -292,13 +292,13 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual - + - - + + @@ -310,27 +310,27 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual - + - + - + - + @@ -356,7 +356,7 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual - + @@ -368,7 +368,7 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual - + @@ -393,103 +393,103 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual - + - + - + - + - + - - - + + - + - + - + - - + + - + - + - + - + - + @@ -501,7 +501,7 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual - + @@ -519,7 +519,7 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual - + @@ -536,14 +536,15 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual + - + - + @@ -552,24 +553,24 @@ Click F1 or click menu `View` -> `Command Palette...` to show Visual ## Commands for tasks.json and launch.json -We have implemented some utilities commands that can be used in tasks.json and launch.json that can be used like: +We have implemented some utilities commands that can be used in `tasks.json` and `launch.json` like: ```json "miDebuggerPath": "${command:espIdf.getToolchainGdb}" ``` - `espIdf.getExtensionPath`: Get the installed location absolute path. -- `espIdf.getOpenOcdScriptValue`: Return the value of OPENOCD_SCRIPTS computed from ESP-IDF Tools path or from `idf.customExtraVars` or from system OPENOCD_SCRIPTS environment variable. +- `espIdf.getOpenOcdScriptValue`: Return the value of OPENOCD_SCRIPTS computed from ESP-IDF Tools path, `idf.customExtraVars`, or the system's OPENOCD_SCRIPTS environment variable. - `espIdf.getOpenOcdConfig`: Return the openOCD configuration files as string. Example `-f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp32-wrover.cfg`. - `espIdf.getProjectName`: Return the project name from current workspace folder `build/project_description.json`. -- `espIdf.getToolchainGcc`: Return the absolute path of the toolchain gcc for the ESP-IDF target given by current IDF_TARGET in sdkconfig. +- `espIdf.getToolchainGcc`: Return the absolute path of the toolchain GCC for the ESP-IDF target given by current IDF_TARGET in sdkconfig. - `espIdf.getToolchainGdb`: Return the absolute path of the toolchain gdb for the ESP-IDF target given by current IDF_TARGET in sdkconfig. See an example in the [debugging](./docs/DEBUGGING.md) documentation. ## Available Tasks in tasks.json -A template Tasks.json is included when creating a project using **ESP-IDF: Create Project from Extension Template**. These tasks can be executed by running F1, writing `Tasks: Run task` and selecting one of the following: +A template tasks.json is included when creating a project using **ESP-IDF: Create Project from Extension Template**. These tasks can be executed by pressing F1, writing `Tasks: Run task` and selecting one of the following: 1. `Build` - Build Project 2. `Set Target to esp32` @@ -578,13 +579,13 @@ A template Tasks.json is included when creating a project using **ESP-IDF: Creat 5. `Flash` - Flash the device 6. `Monitor` - Start a monitor terminal 7. `OpenOCD` - Start the OpenOCD server -8. `BuildFlash` - Execute a build followed by a flash command. +8. `BuildFlash` - Execute a build followed by a flash command -Note that for OpenOCD tasks you need to define `OpenOCD_SCRIPTS` in your system environment variables with OpenOCD scripts folder path. +Note that for OpenOCD tasks, you need to define `OpenOCD_SCRIPTS` in your system environment variables with OpenOCD scripts folder path. # Troubleshooting -If something is not working please check for any error on one of these: +If something is not working, please check for any error on one of these: > **NOTE:** Use `idf.OpenOCDDebugLevel` configuration setting to 3 or more to show debug logging in OpenOCD server output. @@ -597,17 +598,17 @@ If something is not working please check for any error on one of these: - Windows: `%USERPROFILE%\.vscode\extensions\espressif.esp-idf-extension-VERSION\esp_idf_vsc_ext.log` - Linux & MacOSX: `$HOME/.vscode/extensions/espressif.esp-idf-extension-VERSION/esp_idf_vsc_ext.log` -4. In Visual Studio Code, select menu **Help** > `Toggle Developer Tools` and copy any error in the Console tab related to this extension. +4. In Visual Studio Code, select menu **Help** > **Toggle Developer Tools** and copy any error in the Console tab related to this extension. -5. Make sure that your extension is properly configured as described in [JSON Manual Configuration](./docs/SETUP.md#JSON-Manual-Configuration). Visual Studio Code allows you to configure settings at different levels: **Global (User Settings)**, **Workspace** and **Workspace Folder** so make sure your project has the right settings. The `ESP-IDF: Doctor command` result might give the values from user settings instead of the workspace folder settings. +5. Make sure that your extension is properly configured as described in [JSON Manual Configuration](./docs/SETUP.md#JSON-Manual-Configuration). Visual Studio Code allows you to configure settings at different levels: **Global (User Settings)**, **Workspace** and **Workspace Folder**, so make sure your project has the right settings. The `ESP-IDF: Doctor command` result might give the values from user settings instead of the workspace folder settings. -6. Review the [OpenOCD troubleshooting FAQ](https://github.com/espressif/OpenOCD-esp32/wiki/Troubleshooting-FAQ) related to the `OpenOCD` output, for application tracing, debug or any OpenOCD related issues. +6. Refer to the [OpenOCD troubleshooting FAQ](https://github.com/espressif/OpenOCD-esp32/wiki/Troubleshooting-FAQ) for help with application tracing, debugging, or other OpenOCD-related issues that may appear in the OpenOCD output. -7. In some cases that the default shell (Powershell, zsh, sh, .etc) configured in VS Code could affect the behavior of the extension. Make sure that MSYS/MinGW is not set in the environment and the variables don't conflict with terminal behavior. The `ESP-IDF: Doctor Command` shows which shell is detected by the extension when running tasks like build flash and monitor. More information in [here](https://code.visualstudio.com/docs/terminal/profiles). +7. In some cases, the default shell (Powershell, zsh, sh, .etc) configured in VS Code could affect the behavior of the extension. Make sure that MSYS/MinGW is not set in the environment and the variables don't conflict with terminal behavior. The `ESP-IDF: Doctor Command` shows which shell is detected by the extension when running tasks like building, flashing and monitoring. More information in [here](https://code.visualstudio.com/docs/terminal/profiles). -If there is any Python package error, please try to reinstall the required python packages with the **ESP-IDF: Install ESP-IDF Python Packages** command or running the setup again with the **ESP-IDF: Configure ESP-IDF Extension** command. +If there is any Python package error, please try to reinstall the required Python packages with the **ESP-IDF: Install ESP-IDF Python Packages** command or running the setup again with the **ESP-IDF: Configure ESP-IDF Extension** command. -> **NOTE:** When downloading ESP-IDF using git cloning in Windows if you receive errors like "unable to create symlink", enabling `Developer Mode` while cloning ESP-IDF could help resolve the issue. +> **NOTE:** When downloading ESP-IDF using git cloning in Windows, if you receive errors like "unable to create symlink", enabling `Developer Mode` while cloning ESP-IDF could help resolve the issue. If you can't resolve the error, please search in the [github repository issues](http://github.com/espressif/vscode-esp-idf-extension/issues) for existing errors or open a new issue [here](https://github.com/espressif/vscode-esp-idf-extension/issues/new/choose). diff --git a/README_CN.md b/README_CN.md new file mode 100644 index 000000000..d02e1e507 --- /dev/null +++ b/README_CN.md @@ -0,0 +1,621 @@ + + espressif logo + + +# 适用于 VS Code 的 ESP-IDF 扩展 + +[英文](./README.md) + +[![使用教程](https://img.shields.io/badge/-使用教程-red)](./docs/tutorial/toc.md) +[![乐鑫文档](https://img.shields.io/badge/文档中心-red)](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/) +[![故障排除](https://img.shields.io/badge/故障排除-red)](./README.md#Troubleshooting) +[![ESP32](https://img.shields.io/badge/适用芯片-red)](./docs/HARDWARE_SUPPORT.md) +![版本](https://img.shields.io/github/package-json/v/espressif/vscode-esp-idf-extension) +[![发布](https://img.shields.io/badge/Github-发布-blue)](https://github.com/espressif/vscode-esp-idf-extension/releases) +[![论坛](https://img.shields.io/badge/论坛-esp32.com-blue)](https://esp32.com/viewforum.php?f=40) + +基于乐鑫芯片，可通过乐鑫物联网开发框架 [(ESP-IDF)](https://github.com/espressif/esp-idf) 来开发、构建、烧录、监控、调试项目，详情请参见[主要特性](./docs/FEATURES.md)。 + +**最新的 master 安装包**适用于 Visual Studio Code。请下载此 VSIX 文件，按 F1 或点击 VS Code 菜单栏中的`查看` -> `命令面板`，输入`从 VSIX 安装`，选择下载好的 `.vsix` 文件来安装此扩展。 + +此扩展的操作指南可参考[乐鑫文档](https://docs.espressif.com/projects/vscode-esp-idf-extension/en/latest/)或 [Github 文档](./docs/ONBOARDING.md)。 + +# 使用指南 + +## 安装 + +1. 下载并安装 [Visual Studio Code](https://code.visualstudio.com/)。 + +2. 在操作系统中安装 ESP-IDF 所需的软件包： + +- 适用于 [MacOS 和 Linux](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/get-started/macos-setup.html#install-prerequisites) 的软件包。 +- Windows 系统无需额外安装软件包。 + +3. 打开 VS Code，点击左侧活动栏中的扩展图标，或使用**查看：显示扩展**命令（快捷键：⇧⌘X 或 Ctrl+Shift+X）。 + +4. 搜索 [ESP-IDF 扩展](https://marketplace.visualstudio.com/items?itemName=espressif.esp-idf-extension)。 + +5. 安装上述扩展。安装成功后，![Espressif 图标](./media/readme/espressifIcon.png) 会出现在 VS Code 左侧活动栏中。点击该图标，可以看到该扩展提供的基本命令列表。 + +

+ 命令列表 +

+ +6. 从命令列表中选择 **配置 ESP-IDF 扩展** 或按 F1 输入 `Configure ESP-IDF Extension`，然后选择 **ESP-IDF：配置 ESP-IDF 扩展** 选项。 + > **注意：** 对于 ESP-IDF 5.0 之前的版本，配置路径中不可出现空格。 + +

+ 选择 ESP-IDF +

+ +7. 选择 **Express** 后可自行切换下载服务器： + +- Espressif：该服务器链接在中国的下载速度更快。 +- Github：使用 Github 发布链接。 + +8. 选择要下载的 ESP-IDF 版本，或选择 `Find ESP-IDF in your system` 选项查找系统中已有的 ESP-IDF 目录。 + +9. 选择 ESP-IDF 工具的存放位置（即 `IDF_TOOLS_PATH`），默认情况下在 MacOS/Linux 系统中是 `$HOME\.espressif`，Windows 系统中是 `%USERPROFILE%\.espressif`。 + +10. 如果使用 MacOS/Linux 操作系统，请选择系统 Python 可执行文件来在 ESP-IDF 工具内创建 ESP-IDF 虚拟环境，并安装 ESP-IDF Python 包。 + + > **注意：** Windows 用户不需要选择 Python 可执行文件，因为此设置过程会自动安装所需文件。 + +11. 确保 `IDF_TOOLS_PATH` 中不包含空格，避免构建过程中出现问题，且 `IDF_TOOLS_PATH` 与 `IDF_PATH` 不能相同。 + +12. 此时应出现安装界面，显示设置进度状态，包括 ESP-IDF 下载进度、ESP-IDF 工具的下载和安装进度，以及 Python 虚拟环境的创建过程。 + +13. 如果一切正常，将收到所有设置已配置完成的消息，此时可开始使用扩展。 + +如有问题，请参阅[故障排除](#Troubleshooting)部分。 + +## 在 VSCode 中使用 ESP-IDF 扩展 + +ESP-IDF 扩展在 VS Code 底部蓝色窗口的状态栏中提供了一系列命令图标，将鼠标悬停在图标上时，会看到可执行的命令。 + +

+ 状态栏 +

+ +以下步骤展示了这些图标的常见用例： + +1. 按 F1 并输入 **ESP-IDF：展示示例项目**，可以基于 ESP-IDF 示例创建新项目。在命令面板中选择 ESP-IDF，搜索想使用的示例并创建新项目。 + +2. 创建好新项目并在 VS Code 中打开后，点击状态栏图标 ![串口](./media/readme/serialport.png) 设置设备的串口。也可以按 F1 输入 **ESP-IDF：选择要使用的端口**，选择设备连接的串口。 + +3. 点击状态栏图标 ![IDF 目标](./media/readme/target.png) 选择使用的芯片设备（如 esp32、esp32s2 等），或按 F1 输入 **ESP-IDF：设置乐鑫设备目标** 命令。 + +4. 接下来，通过点击状态栏图标 ![sdkconfig 编辑器](./media/readme/sdkconfig.png) 或按 F1 输入 **ESP-IDF：SDK 配置编辑器** 命令（快捷键：CTRLEG），修改 ESP-IDF 项目设置。完成所有更改后，点击 `Save` 并关闭此窗口。可以在菜单栏中的`查看` -> `输出`中选择下拉列表里的 `ESP-IDF` 来查看输出信息。 + +5. （可选）**ESP-IDF：运行 idf.py reconfigure 任务** 命令生成 `compile_commands.json` 文件，以便启用语言支持。也可以按照 [C/C++ 配置](./docs/C_CPP_CONFIGURATION.md) 文档中的说明配置 `.vscode/c_cpp_properties.json`。 + +6. 请自行对代码进行必要修改。完成项目后，点击状态栏图标 ![构建](./media/readme/build.png) 或按 F1 输入 **ESP-IDF：构建项目** 来构建项目。 + +7. 点击状态栏图标 ![烧录](./media/readme/flash.png) 或按 F1 输入 **ESP-IDF：烧录项目**，依据使用的接口类型，在命令面板中选择 `UART`、`DFU` 或 `JTAG`，将应用程序烧录到设备上。 + +8. 点击状态栏图标 ![烧录方式](./media/readme/flashmethod.png) 或按 F1 输入 **ESP-IDF：选择烧录方式**，从 `UART`、`DFU` 或 `JTAG` 中选择想要更改的烧录方式。也可以直接使用命令 **ESP-IDF：通过 UART 接口烧录项目**、**通过 JTAG 接口烧录项目** 或 **ESP-IDF：通过 DFU 接口烧录项目**。 + +9. 点击状态栏图标 ![监视器](./media/readme/monitor.png) 或按 F1 输入 **ESP-IDF：监视设备** 启动监视器，在 VS Code 终端中记录设备活动。 + +10. 根据 ESP-IDF 文档中的要求来配置驱动程序，详情请参考[配置 JTAG 接口](https://docs.espressif.com/projects/esp-idf/zh_CN/latest/esp32/api-guides/jtag-debugging/configure-ft2232h-jtag.html)。 + +11. 在调试设备之前，先按 F1 输入 **ESP-IDF：选择 OpenOCD 开发板配置**，选择设备的 OpenOCD 开发板配置文件。点击状态栏图标 ![openocd](./media/readme/openocd.png) 或按 F1 输入 **ESP-IDF：OpenOCD 管理器** 命令来测试连接。可以在菜单栏中的`查看` -> `输出`里选择下拉列表中的 `ESP-IDF` 来查看输出信息。 + + > **注意：** 可以使用 **ESP-IDF：OpenOCD 管理器** 命令或者点击 VS Code 状态栏中的 `OpenOCD Server (Running | Stopped)` 按钮来启动或停止 OpenOCD。 + +12. 确保项目已经构建并烧录，OpenOCD 连接正常，调试器能正常工作。按 F5 启动调试会话。调试会话的输出可在菜单栏中选择`查看` -> `调试控制台`进行查看。 + +如有问题，请参阅[故障排除](#Troubleshooting)部分。 + +# 拓展阅读 + +您可以在下面找到关于所有功能的教程、命令和文档的详细列表。 + +- 查看有关 ESP-IDF 扩展的[乐鑫文档](https://docs.espressif.com/projects/vscode-esp-idf-extension/zh_CN/latest/)。 + +- 查看 ESP-IDF 扩展的[使用教程](./docs/tutorial/toc.md). + +- 查看有关 ESP-IDF 扩展的 [GitHub 文档](./docs/ONBOARDING.md). + +# 可用命令列表 + +按 F1 或点击菜单栏中的`查看` -> `命令面板`，输入 **ESP-IDF** 即可查看 ESP-IDF 扩展所支持的所有命令。 + +
CategoryCommand DescriptionCommand Description Keyboard Shortcuts (Mac)Keyboard Shortcuts (Windows/ Linux)Keyboard Shortcuts (Windows/Linux)
Add Docker Container ConfigurationSettingsAdd Docker Container Configuration Add the .devcontainer files to the currently opened project directory, necessary to use a ESP-IDF project in a Docker container with Visual Studio Code - Remote - Containers extension
Add vscode configuration folderAdd .vscode files to the currently opened project directory. These include launch.json (for debugging), settings.json and c_cpp_properties.json for syntax highlight.Add .vscode files to the currently opened project directory. This includes launch.json (for debugging), settings.json and c_cpp_properties.json (for syntax highlight).
Configure ESP-IDF extensionOpen a window with a setup wizard to install ESP-IDF, IDF Tools and python virtual environment.Open a window with a setup wizard to install ESP-IDF, IDF Tools and Python virtual environment.
Select output and notification modeThis extension shows many notifications and output in the Output window ESP-IDF. This command allows you to set if to show notifications, show output, both or none of them.This extension shows many notifications and output in the Output window ESP-IDF. This command allows you to set if to show notifications only, output only, both notifications and output, or neither.
Select where to save configuration settingsIn Visual Studio Code settings can be saved in 3 places: User Settings (global settings), workspace ( .code-workspace file) or workspace folder (.vscode/settings.json). + In Visual Studio Code, settings can be saved in 3 places: User Settings (global settings), workspace ( .code-workspace file) or workspace folder (.vscode/settings.json). More information in working with multiple projects.
Pick a workspace folderwhen using a Visual Studio Code workspace with multiple workspace folders, this command allow you to select which workspace folder to use for this extension commands. + When using a Visual Studio Code workspace with multiple folders, this command allows you to choose which workspace folder to apply this extension’s commands to. More information in working with multiple projects.
Basic Show Examples ProjectsLaunch UI to show examples from selected framework and allow you to create a project from them. This command will show frameworks already configured in the extension so if - you want to see ESP-Rainmaker examples you need to run the Install ESP-Rainmaker first (or set the equivalent setting idf.espRainmakerPath) and then execute this command to see the examples.Launch UI to show examples from selected framework and allow you to create a project from them. This command will show frameworks already configured in the extension, so to view ESP-Rainmaker examples, you need to run the Install ESP-Rainmaker first (or set the equivalent setting idf.espRainmakerPath), and then execute this command to see the examples.
Set Espressif device targetThis will set the target for the current project (IDF_TARGET). Similar to idf.py set-target. For example if you want to use ESP32 or ESP32-C3 you need to execute this command.This will set the target for the current project (IDF_TARGET). Similar to idf.py set-target. For example, if you want to use ESP32 or ESP32-C3, you need to execute this command.
SDK Configuration editorLaunch a UI to configure your ESP-IDF project settings. This is equivalent to idf.py menuconfigLaunch a UI to configure your ESP-IDF project settings. This is equivalent to idf.py menuconfig. ⌘ I G Ctrl E G
Select port to useSelect which serial port to use for ESP-IDF tasks like flashing or monitor your device.Select which serial port to use for ESP-IDF tasks, such as flashing or monitoring your device. ⌘ I P Ctrl E P
Flash your projectWrite binary data to the ESP’s flash chip from your current ESP-IDF project. This command will use either UART, DFU or JTAG based on idf.flashTypeWrite binary data to the ESP’s flash chip from your current ESP-IDF project. This command will use either UART, DFU or JTAG based on idf.flashType. ⌘ I F Ctrl E F
Monitor deviceThis command will execute idf.py monitor to start serial communication with Espressif device. - Please take a look at the IDF Monitor Documentation.This command will execute idf.py monitor to start serial communication with Espressif device. + Please take a look at the IDF Monitor. ⌘ I M Ctrl E M
Select OpenOCD Board ConfigurationSelect the OpenOCD configuration files that match your Espressif device target. For example if you are using DevKitC or ESP-Wrover-Kit. This is necessary for flashing with JTAG or debugging your device.Select the OpenOCD configuration files that match your Espressif device target, such as DevKitC or ESP-Wrover-Kit. This is necessary for flashing with JTAG or debugging your device.
Build, Flash and start a monitor on your deviceBuild the project, write binaries program to device and start a monitor terminal with a single command. Similar to `idf.py build flash monitor`Build the project, write binaries program to device and start a monitor terminal with a single command. Similar to idf.py build flash monitor. ⌘ I D Ctrl E D
Project creation Show Examples ProjectsLaunch UI to show examples from selected framework and allow you to create a project from them. This command will show frameworks already configured in the extension so if - you want to see ESP-Rainmaker examples you need to run the Install ESP-Rainmaker first (or set the equivalent setting idf.espRainmakerPath) and then execute this command to see the examples.Launch UI to show examples from selected framework and allow you to create a project from them. This command will show frameworks already configured in the extension, so to view ESP-Rainmaker examples, you need to run the Install ESP-Rainmaker first (or set the equivalent setting idf.espRainmakerPath), and then execute this command to see the examples.
Create project from Extension TemplateCreate ESP-IDF using one of the extension template projects.Create an ESP-IDF project using one of the extension template projects. ⌘ I C Ctrl E C
Create New ESP-IDF ComponentCreate a new component in the current directory based on ESP-IDF component templateCreate a new component in the current directory based on ESP-IDF component template.
Import ESP-IDF ProjectImport an existing ESP-IDF project and add .vscode and .devcontainer files to a new location and also able to rename the project.Import an existing ESP-IDF project, add .vscode and .devcontainer files to a new location, and optionally rename the project.
New ProjectLaunch UI with a ESP-IDF project creation wizard using examples templates from ESP-IDF and additional frameworks configured in the extension.Launch UI with a ESP-IDF project creation wizard using example templates from ESP-IDF and additional frameworks configured in the extension. ⌘ I N Ctrl E N
Flash (UART) your projectWrite binary data to the ESP’s flash chip from your current ESP-IDF project using esptool.pyWrite binary data to the ESP’s flash chip from your current ESP-IDF project using esptool.py.
Flash (with JTag)Write binary data to the ESP’s flash chip from your current ESP-IDF project using OpenOCD JTAGFlash (with JTAG)Write binary data to the ESP’s flash chip from your current ESP-IDF project using OpenOCD JTAG.
Erase Flash Memory from DeviceExecute esptool.py erase_flash command to erase flash chip (set to 0xFF bytes)Execute esptool.py erase_flash command to erase flash chip (set to 0xFF bytes). ⌘ I R Ctrl E R
Code coverage Add Editor coverageParse your project GCOV Code coverage files to add color lines - representing code coverage on currently opened source code fileParse your project GCOV code coverage files to add color lines + representing code coverage on currently opened source code file.
Configure Project SDKConfig for CoverageSet required values in your project SDKConfig to enable Code CoverageSet required values in your project SDKConfig to enable code coverage analysis.
Get HTML Coverage Report for projectParse your project GCOV Code coverage files to generate a HTML coverage report.Parse your project GCOV code coverage files to generate a HTML coverage report.
Install ESP-IDF Python Packages (DEPRECATION NOTICE)Install extension python packages. Deprecated will be removed soon. Install extension Python packages. Deprecated will be removed soon.
Install ESP-MatterClone ESP-Matter and set idf.espMatterPath. The ESP-IDF: Set ESP-MATTER Device Path (ESP_MATTER_DEVICE_PATH) is used to define the device path for ESP-Matter. ESP-Matter is not supported in Windows. Make sure to install Matter system prerequisites first.Clone ESP-Matter and set idf.espMatterPath. ESP-Matter is not supported in Windows. Make sure to install Matter system prerequisites first.
eFuse Get eFuse SummaryGet list of eFuse and values from currently serial port chip.Retrieve a list of eFuses and their corresponding values from the chip currently connected to the serial port.
Clear eFuse SummaryClear the eFuse Summary tree from ESP Explorer EFUSEEXPLORERClear the eFuse Summary tree from ESP Explorer EFUSEEXPLORER.
QEMU Launch QEMU ServerAs described in QEMU documentation this command will execute ESP32 QEMU from the project Dockerfile with the current project binaries.As described in QEMU documentation, this command will execute ESP32 QEMU from the project Dockerfile with the current project binaries.
Launch QEMU Debug SessionAs described in QEMU documentation this command will start a debug session to ESP32 QEMU from the project Dockerfile with the current project binaries.As described in QEMU documentation, this command will start a debug session to ESP32 QEMU from the project Dockerfile with the current project binaries.
Monitor QEMU DeviceAs described in QEMU documentation this command will start a terminal to monitor the ESP32 QEMU from the project Dockerfile with the current project binaries.As described in QEMU documentation, this command will start a terminal to monitor the ESP32 QEMU from the project Dockerfile with the current project binaries.
Monitoring Monitor deviceThis command will execute idf.py monitor to start serial communication with Espressif device. + This command will execute idf.py monitor to start serial communication with Espressif device. Please take a look at the IDF Monitor Documentation. ⌘ I M Ctrl E M
Launch IDF Monitor for CoreDump / GDB-Stub ModeLaunch ESP-IDF Monitor with websocket capabilities. If you has configured the panic handler to gdbstub or core dump, the monitor will launch a post mortem debug session of the chip.Launch IDF Monitor for CoreDump/GDB-Stub ModeLaunch ESP-IDF Monitor with WebSocket capabilities. If you has configured the panic handler to gdbstub or core dump, the monitor will launch a post-mortem debug session of the chip.
Monitor QEMU DeviceAs described in QEMU documentation this command will start a terminal to monitor the ESP32 QEMU from the project Dockerfile with the current project binaries.As described in QEMU documentation, this command will start a terminal to monitor the ESP32 QEMU from the project Dockerfile with the current project binaries.
Editors NVS Partition EditorLaunch UI to create a CSV file for ESP_IDF Non Volatile StorageLaunch UI to create a CSV file for ESP-IDF Non-Volatile Storage Library.
Partition Table EditorLaunch UI to manage custom partition table as described in ESP_IDF Partition TableLaunch UI to manage custom partition table as described in ESP-IDF Partition Tables.
SDK Configuration editorLaunch a UI to configure your ESP-IDF project settings. This is equivalent to idf.py menuconfigSDK Configuration EditorLaunch a UI to configure your ESP-IDF project settings. This is equivalent to idf.py menuconfig. ⌘ I G Ctrl E G
Unit Testing Unit Test: Build and flash unit test app for testingCopy the unit test app in the current project, build the current project and flash the unit test application to the connected device. More information in Unit testing documentationCopy the unit test app in the current project, build the current project and flash the unit test application to the connected device. More information in Unit testing documentation.
Unit Test: Install ESP-IDF PyTest requirementsInstall the ESP-IDF Pytest requirements packages to be able to execute ESP-IDF Unit tests. More information in Install the ESP-IDF Pytest requirements packages to be able to execute ESP-IDF Unit tests. More information in Unit testing documentation.
Scripts and Tools Run idf.py reconfigure taskThis command will execute idf.py reconfigure (CMake configure task). Useful when you need to generate compile_commands.json for the C/C++ language support.This command will execute idf.py reconfigure (CMake configure task), which is useful for generating compile_commands.json for the C/C++ language support.
Erase Flash Memory from DeviceExecute esptool.py erase_flash command to erase flash chip (set to 0xFF bytes)Execute esptool.py erase_flash command to erase flash chip (set to 0xFF bytes). ⌘ I R Ctrl E R
Dispose Current SDK Configuration Editor Server ProcessIf you already executed the SDK Configuration editor, a cache process will remain in the background for faster re opening. This command will dispose of such cache process.If you already executed the SDK Configuration Editor, a cache process will remain in the background for faster reopening. This command will dispose of such cache process.
Troubleshoot FormLaunch UI for user to send a troubleshoot report with steps to reproduce, run a diagnostic of the extension setup settings and extension logs to send to telemetry backend.Launch UI for user to send a troubleshoot report with steps to reproduce. Run a diagnostic of the extension setup settings and extension logs to send to telemetry backend.
Show Ninja Build SummaryExecute the Chromium ninja-build-summary.py Execute the Chromium ninja-build-summary.py.
Cleanup Clear ESP-IDF Search ResultsClear results from ESP Explorer Documentation Search ResultsClear results from ESP Explorer Documentation Search Results.
Clear Saved ESP-IDF SetupsClear existing esp-idf setups saved by the extension.Clear existing ESP-IDF setups saved by the extension.
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
类别命令描述快捷键（Mac）快捷键（Windows/Linux）
设置添加 Docker 容器配置将 .devcontainer 文件添加到当前打开的项目目录中，从而能借助 Dev Containers 扩展 + 在 Docker 容器中使用 ESP-IDF 项目。
添加 vscode 配置文件夹将 .vscode 文件添加到当前打开的项目目录中。这些文件包括 launch.json（用于调试）、settings.json 和 c_cpp_properties.json（用于语法高亮）。
配置 ESP-IDF 扩展打开一个带有安装向导的窗口，可以安装 ESP-IDF、IDF 工具和 Python 虚拟环境。
选择输出和通知模式此扩展会在输出窗口 ESP-IDF 中显示通知和输出。此命令可设置是否只显示通知、只显示输出、两者都显示或都不显示。
选择设置存储范围VS Code 中的设置可存储在三处：用户设置（全局设置）、工作区（.code-workspace 文件）或工作区文件夹（.vscode/settings.json）。 + 更多信息请参见处理多个项目。
选择工作区文件夹在使用包含多个工作区文件夹的 VS Code 工作区时，此命令会让此扩展的命令应用于指定文件夹。 + 更多信息请参见处理多个项目。
基础命令展示示例项目启动 UI 以显示所选框架的示例，可从中创建新项目。此命令将显示扩展中已配置的框架，如果想查看 ESP-Rainmaker 示例，需要先运行 安装 ESP-Rainmaker 命令（或设置相应的 idf.espRainmakerPath），然后执行此命令以查看示例。
设置乐鑫设备目标该命令为当前项目设置目标 (IDF_TARGET)，效果等同于 idf.py set-target。例如，若想使用 ESP32 或 ESP32-C3，则需执行此命令。
SDK 配置编辑器启动 UI，进行 ESP-IDF 项目设置。该命令效果等同于 idf.py menuconfig。⌘ I GCtrl E G
构建项目使用 CMake 和 Ninja-build 来构建项目，具体说明请参见 ESP-IDF 构建系统直接使用 CMake。若想修改构建任务的行为，可以在配置 Cmake 时使用 idf.cmakeCompilerArgs 命令，或在配置 Ninja 时使用 idf.ninjaArgs 命令。例如，可以使用 [-j N] 来设置并行作业数，其中 N 是并行作业的数量。⌘ I BCtrl E B
二进制文件大小分析启动 UI 以显示 ESP-IDF 项目的二进制文件大小信息。⌘ I SCtrl E S
选择任务串口选择用于 ESP-IDF 任务（如烧录或监视设备）的串口。⌘ I PCtrl E P
烧录项目将当前项目生成的二进制文件烧录至目标设备。此命令将根据 idf.flashType 使用 UART、DFU 或 JTAG 接口。⌘ I FCtrl E F
监视设备此命令将执行 idf.py monitor，与乐鑫设备进行串行通信。 + 详情请参见 IDF 监视器。⌘ I MCtrl E M
打开 ESP-IDF 终端启动一个配置了 ESP-IDF 扩展设置的终端窗口，效果类似于 ESP-IDF CLI 的 export.sh 脚本。⌘ I TCtrl E T
选择 OpenOCD 开发板配置选择与使用的乐鑫设备目标相匹配的 OpenOCD 配置文件。例如，可以选择 DevKitC 或 ESP-Wrover-Kit。使用 JTAG 接口进行烧录或对设备进行调试时，此步骤必不可缺。
构建、烧录项目并监视设备此命令可用于构建项目、将二进制程序写入设备，并启动监视终端，效果类似于 idf.py build flash monitor。⌘ I DCtrl E D
创建项目展示示例项目启动 UI 以显示所选框架的示例，可从中创建新项目。此命令将显示扩展中已配置的框架，如果想查看 ESP-Rainmaker 示例，需要先运行 安装 ESP-Rainmaker 命令（或设置相应的 idf.espRainmakerPath），然后执行此命令以查看示例。
基于模板创建新项目使用扩展中的项目模板来创建一个新的 ESP-IDF 项目。⌘ I CCtrl E C
创建新 ESP-IDF 组件在当前目录下，基于 ESP-IDF 组件模板创建新组件。
导入 ESP-IDF 项目导入现有的 ESP-IDF 项目，在新位置添加 .vscode 和 .devcontainer 文件，同时可以重命名项目。
新项目启动 UI，通过 ESP-IDF 项目创建向导，使用 ESP-IDF 中的示例模板和扩展中配置的其他框架。⌘ I NCtrl E N
烧录选择烧录方式选择用于 烧录项目 命令的烧录方法，可选择 DFU、JTAG 或 UART 接口。
烧录项目将当前项目生成的二进制文件烧录至目标设备。此命令将根据 idf.flashType 使用 UART、DFU 或 JTAG 接口。⌘ I FCtrl E F
通过 DFU 接口烧录项目通过 DFU，将当前 ESP-IDF 项目的二进制文件写入 flash 芯片，此方案仅适用于 ESP32-S2 和 ESP32-S3。
通过 UART 接口烧录项目通过 esptool.py，将当前 ESP-IDF 项目的二进制文件写入 flash 芯片。
通过 JTAG 接口烧录项目使通过 OpenOCD JTAG，将当前 ESP-IDF 项目的二进制文件写入 flash 芯片。
加密并烧录项目执行项目烧录，同时为需要加密的分区添加 --encrypt。
擦除设备 flash 数据执行 esptool.py erase_flash 命令，擦除 flash，将芯片重置为 0xFF 字节。⌘ I RCtrl E R
代码覆盖率添加编辑器覆盖率解析项目的 GCOV 代码覆盖率文件， + 并在源代码文件中用彩色高亮代码覆盖行。
配置 SDKConfig 文件以启用代码覆盖率在项目的 SDKConfig 文件中设置必要的值，启用代码覆盖率分析。
生成 HTML 格式的代码覆盖率报告解析项目的 GCOV 代码覆盖率文件，生成 HTML 格式的覆盖率报告。
移除编辑器覆盖率移除因添加编辑器覆盖率命令而产生的彩色高亮代码行。
可集成软件框架安装 ESP-ADF在所选目录中克隆 ESP-ADF，并配置 idf.espAdfPath（Windows 系统中为 idf.espAdfPathWin）。
添加 Arduino ESP32 为 ESP-IDF 组件将 Arduino-ESP32 + 添加为当前目录中的 ESP-IDF 组件（${CURRENT_DIRECTORY}/components/arduino）。
安装 ESP-IDF Python 包（弃用通知）请安装扩展 Python 包。本命令已弃用，即将被移除。
安装 ESP-MDF在所选目录中克隆 ESP-MDF，并配置 idf.espMdfPath（Windows 系统中为 idf.espMdfPathWin）。
安装 ESP-Matter克隆 ESP-Matter 并配置 idf.espMatterPath。Windows 系统不支持 ESP-Matter。运行该命令前请确保已安装 Matter 系统依赖项。
设置 ESP-MATTER 设备路径 (ESP_MATTER_DEVICE_PATH)ESP-IDF：设置 ESP-MATTER 设备路径 (ESP_MATTER_DEVICE_PATH) 命令用于定义 ESP-Matter 的设备路径。Windows 系统不支持 ESP-Matter。
安装 ESP-Rainmaker克隆 ESP-Rainmaker，并配置 idf.espRainmakerPath（Windows系统中为 idf.espRainmakerPathWin）。
安装 ESP-HomeKit-SDK在所选目录中克隆 ESP-HomeKit-SDK，并配置 idf.espHomeKitSdkPath（Windows 系统中为 idf.espHomeKitSdkPathWin）。
eFuse获取 eFuse 总结从当前连接到串口的芯片中获取 eFuse 列表及其对应的数值。
清除 eFuse 总结从 ESP Explorer 的 EFUSEEXPLORER 中清除 eFuse 摘要集。
QEMU启用 QEMU 服务器如 QEMU 文档中所述，此命令将使用项目的 Dockerfile 和二进制文件执行 ESP32 QEMU。
启用 QEMU 调试回话如 QEMU 文档中所述，此命令将使用项目的 Dockerfile 和二进制文件启动 ESP32 QEMU 的调试会话。
监视 QEMU 设备如 QEMU 文档中所述，此命令将启动终端，通过使用项目的 Dockerfile 和二进制文件来监视 ESP32 QEMU。
监视监视设备该命令将执行 idf.py monitor，启动计算机与乐鑫设备之间的串行通信。 + 详情请参阅 IDF 监视器。⌘ I MCtrl E M
启用 IDF 监视器以支持 CoreDump/GDB-Stub 模式启动支持 WebSocket 的 ESP-IDF 监控器。如果紧急处理程序已经配置为 gdbstub 或核心转储，监控器将启动芯片的事后调试会话。
监视 QEMU 设备如 QEMU 文档中所述，此命令将启动终端，通过使用项目的 Dockerfile 和二进制文件来监视 ESP32 QEMU。
编辑器NVS 分区编辑器启动 UI，创建 ESP-IDF 非易失性存储库 的 CSV 文件。
分区表编辑器启动 UI，如 ESP-IDF 分区表 中所述，管理自定义分区表。
SDK 配置编辑器启动 UI，进行 ESP-IDF 项目设置。该命令效果等同于 idf.py menuconfig。⌘ I GCtrl E G
单元测试单元测试：构建并烧录单元测试应用程序复制当前项目中的单元测试应用程序，构建当前项目并将单元测试应用程序烧录到连接的设备上。详情请参阅单元测试。
单元测试：安装 ESP-IDF PyTest 依赖项安装 ESP-IDF Pytest 依赖项，以便能够执行 ESP-IDF 单元测试。详情请参阅单元测试。
脚本和工具运行 idf.py reconfigure 任务此命令将执行 idf.py reconfigure（CMake 配置任务），能够帮助生成 compile_commands.json 文件以支持 C/C++ 语言特性。
擦除设备 flash 数据执行 esptool.py erase_flash 命令，擦除 flash，将芯片重置为 0xFF 字节。⌘ I RCtrl E R
清理当前 SDK 配置编辑器服务器进程若先前执行过SDK 配置编辑器命令，则后台将保留缓存进程，以便下次更快打开编辑器。此命令将清理此类缓存进程。
诊断命令诊断扩展设置及扩展日志，提供故障排除报告。
故障排除表单启动 UI，以便用户发送故障排除报告，报告中需包含重现问题的步骤。同时系统将诊断扩展设置及扩展日志，并将信息发送到遥测后端。
运行 ESP-IDF-SBOM 漏洞检查为使用 ESP-IDF 开发框架生成的应用程序创建 SPDX 格式的软件物料清单（SBOM）文件。
保存默认的 SDKCONFIG 文件 (save-defconfig)使用当前项目的 sdkconfig 文件，生成 sdkconfig.defaults 文件。
显示 Ninja 构建摘要运行 Chromium ninja-build-summary.py。
在文档中搜索...从源代码文件中选择文本，并在 ESP-IDF 文档中进行搜索，搜索结果将显示在 VSCode ESP-IDF Explorer 选项卡中。⌘ I QCtrl E Q
搜索错误提示输入文本，在 ESP-IDF 提示库中搜索匹配的错误。
 清理清除 ESP-IDF 搜索结果清除 Explorer 中 Documentation Search Results 选项卡中的所有搜索结果。
清除已保存的 ESP-IDF 设置清除扩展中保留的现有 ESP-IDF 设置。
+ +## 针对 tasks.json 和 launch.json 的命令 + +扩展中实现了一些实用工具命令，可以在 `tasks.json` 和 `launch.json` 文件中按照如下方式使用： + +```json +"miDebuggerPath": "${command:espIdf.getToolchainGdb}" +``` + +- `espIdf.getExtensionPath`：获取已安装位置的绝对路径。 +- `espIdf.getOpenOcdScriptValue`：返回从 ESP-IDF 工具路径、`idf.customExtraVars` 或系统 OPENOCD_SCRIPTS 环境变量中计算出的 OPENOCD_SCRIPTS 的值。 +- `espIdf.getOpenOcdConfig`：以字符串形式返回 openOCD 配置文件。例如 `-f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp32-wrover.cfg`。 +- `espIdf.getProjectName`：从当前工作区文件夹的 `build/project_description.json` 文件中提取项目名称。 +- `espIdf.getToolchainGcc`：根据 sdkconfig 文件中指定的 IDF_TARGET，该命令将返回相应 GCC 工具链的绝对路径。 +- `espIdf.getToolchainGdb`：根据 sdkconfig 文件中指定的 IDF_TARGET，该命令将返回相应 GDB 工具链的绝对路径。 + +在[调试](./docs/DEBUGGING.md)文档中查看示例。 + +## tasks.json 中可用的任务 + +使用 **ESP-IDF：基于模板创建新项目** 命令创建项目时，会包含 tasks.json 模板。按 F1 并输入 `Tasks: Run task`，选择执行以下任一任务： + +1. `Build` - 构建项目 +2. `Set Target to esp32` - 选择 ESP32 为对象 +3. `Set Target to esp32s2` - - 选择 ESP32-S2 为对象 +4. `Clean` - 清除项目 +5. `Flash` - 烧录设备 +6. `Monitor` - 启动监视终端 +7. `OpenOCD` - 启动 OpenOCD 服务器 +8. `BuildFlash` - 执行构建后烧录命令 + +请注意，对于 OpenOCD 任务，需要在系统环境变量中定义 `OpenOCD_SCRIPTS`，并将其设置为 OpenOCD 脚本文件夹的路径。 + +# 故障排除 + +如果遇到问题，请检查以下方面是否有错误： + +> **注意：** 将 `idf.OpenOCDDebugLevel` 配置项设为 3 或更高值，OpenOCD 服务器将输出调试日志。 + +> **注意：** 将 `/.vscode/launch.json` 文件中的 `logLevel` 配置项设为 3 或更高值，调试适配器将输出详细日志。 + +1. 在 VS Code 菜单栏中选择**查看** > **输出** > **ESP-IDF**。此输出信息有助于了解扩展的运行状况。 +2. 在 VS Code 菜单栏中选择**查看** > **命令面板...**，输入 `ESP-IDF：诊断命令`，该命令将生成环境配置的报告并复制到剪贴板中，报告内容可粘贴至任意位置。 +3. 检查日志文件。文件路径如下所示： + +- Windows: `%USERPROFILE%\.vscode\extensions\espressif.esp-idf-extension-VERSION\esp_idf_vsc_ext.log` +- Linux & MacOSX: `$HOME/.vscode/extensions/espressif.esp-idf-extension-VERSION/esp_idf_vsc_ext.log` + +4. 在 VS Code 菜单栏中选择**帮助** > **切换开发人员工具**，Console 选项卡中会显示与扩展相关的错误信息，可自行复制。 + +5. 确保扩展按照 [JSON 手动配置](./docs/SETUP.md#JSON-Manual-Configuration)中的要求进行正确配置。VS Code 支持不同级别的设置，如：**全局（用户设置）**、**工作区** 和 **工作区文件夹**，请确保项目配置正确。运行 `ESP-IDF：诊断命令`得到的结果可能来自于用户设置，而非工作区文件夹。 + +6. 查看 [OpenOCD 故障排除 FAQ](https://github.com/espressif/OpenOCD-esp32/wiki/Troubleshooting-FAQ)，可帮助进行应用追踪及调试，并解决 `OpenOCD` 输出中显示的其他相关问题。 + +7. 有时 VS Code 中配置的默认 shell（Powershell、zsh、sh 等）可能会影响扩展的行为。请确保环境中未设置 MSYS/MinGW，且变量与终端行为不冲突。`ESP-IDF：诊断命令`会显示运行构建、烧录和监视任务时扩展检测到的 shell。详情请参考[此处](https://code.visualstudio.com/docs/terminal/profiles)。 + +如果出现 Python 包错误，请尝试使用 **ESP-IDF：安装 ESP-IDF Python 包** 命令重新安装所需的 Python 包，或通过 **ESP-IDF：配置 ESP-IDF 扩展** 命令重新设置。 + +> **注意：** 在 Windows 中通过 Git 克隆 ESP-IDF 时，如果出现 "unable to create symlink" 错误，可启用`开发者模式`进行克隆，从而解决该问题。 + +如果有无法解决的错误，请在 [GitHub 仓库问题区](http://github.com/espressif/vscode-esp-idf-extension/issues) 搜索相似问题，也可点击[此处](https://github.com/espressif/vscode-esp-idf-extension/issues/new/choose)提交新问题。 + +# 行为准则 + +该项目及其所有参与者都受到[行为准则](./docs/CODE_OF_CONDUCT.md)的约束。参与本项目时，应遵守此准则。若发现任何不规范行为，请报告至 [vscode@espressif.com](mailto:vscode@espressif.com)。 + +# 许可证 + +此扩展基于 Apache License 2.0 授权许可。有关附加版权声明和条款，请参见[许可证](./LICENSE)。