Skip to content

Latest commit

 

History

History
613 lines (537 loc) · 34.5 KB

README_CN.md

File metadata and controls

613 lines (537 loc) · 34.5 KB
Raw
espressif logo

适用于 VS Code 的 ESP-IDF 扩展

英文

乐鑫文档 故障排除 版本 发布 论坛

基于乐鑫芯片，可通过乐鑫物联网开发框架 (ESP-IDF) 来开发、构建、烧录、监控、调试项目，详情请参见文档中心。

最新的 master 安装包适用于 Visual Studio Code。请下载此 VSIX 文件，按 F1 或点击 VS Code 菜单栏中的查看 -> 命令面板，输入从 VSIX 安装，选择下载好的 .vsix 文件来安装此扩展。

此扩展的操作指南可参考乐鑫文档。

使用指南

安装

  1. 下载并安装 Visual Studio Code。

  2. 在操作系统中安装 ESP-IDF 所需的软件包：

  • 适用于 MacOS 和 Linux 的软件包。
  • Windows 系统无需额外安装软件包。

  1. 打开 VS Code，点击左侧活动栏中的扩展图标，或使用查看：显示扩展命令（快捷键：⇧⌘X 或 Ctrl+Shift+X）。

  2. 搜索 ESP-IDF 扩展。

  3. 安装上述扩展。安装成功后，Espressif 图标 会出现在 VS Code 左侧活动栏中。点击该图标，可以看到该扩展提供的基本命令列表。

命令列表

  1. 从命令列表中选择 配置 ESP-IDF 扩展 或按 F1 输入 Configure ESP-IDF Extension，然后选择 ESP-IDF：配置 ESP-IDF 扩展 选项。

    注意： 对于 ESP-IDF 5.0 之前的版本，配置路径中不可出现空格。

选择 ESP-IDF

  1. 选择 Express 后可自行切换下载服务器：
  • Espressif：该服务器链接在中国的下载速度更快。
  • Github：使用 Github 发布链接。

  1. 选择要下载的 ESP-IDF 版本，或选择 Find ESP-IDF in your system 选项查找系统中已有的 ESP-IDF 目录。

  2. 选择 ESP-IDF 工具的存放位置（即 IDF_TOOLS_PATH），默认情况下在 MacOS/Linux 系统中是 $HOME\.espressif，Windows 系统中是 %USERPROFILE%\.espressif。

  3. 如果使用 MacOS/Linux 操作系统，请选择系统 Python 可执行文件来在 ESP-IDF 工具内创建 ESP-IDF 虚拟环境，并安装 ESP-IDF Python 包。

    注意： Windows 用户不需要选择 Python 可执行文件，因为此设置过程会自动安装所需文件。

  4. 确保 IDF_TOOLS_PATH 中不包含空格，避免构建过程中出现问题，且 IDF_TOOLS_PATH 与 IDF_PATH 不能相同。

  5. 此时应出现安装界面，显示设置进度状态，包括 ESP-IDF 下载进度、ESP-IDF 工具的下载和安装进度，以及 Python 虚拟环境的创建过程。

  6. 如果一切正常，将收到所有设置已配置完成的消息，此时可开始使用扩展。

如有问题，请参阅故障排除部分。

在 VS Code 中使用 ESP-IDF 扩展

ESP-IDF 扩展在 VS Code 底部蓝色窗口的状态栏中提供了一系列命令图标，将鼠标悬停在图标上时，会看到可执行的命令。

状态栏

以下步骤展示了这些图标的常见用例：

  1. 按 F1 并输入 ESP-IDF：展示示例项目，可以基于 ESP-IDF 示例创建新项目。在命令面板中选择 ESP-IDF，搜索想使用的示例并创建新项目。

  2. 创建好新项目并在 VS Code 中打开后，点击状态栏图标 串口 设置设备的串口。也可以按 F1 输入 ESP-IDF：选择要使用的端口，选择设备连接的串口。

  3. 点击状态栏图标 IDF 目标 选择使用的芯片设备（如 esp32、esp32s2 等），或按 F1 输入 ESP-IDF：设置乐鑫设备目标 命令。

  4. 接下来，通过点击状态栏图标 sdkconfig 编辑器 或按 F1 输入 ESP-IDF：SDK 配置编辑器 命令（快捷键：CTRL E G），修改 ESP-IDF 项目设置。完成所有更改后，点击 Save 并关闭此窗口。可以在菜单栏中的查看 -> 输出中选择下拉列表里的 ESP-IDF 来查看输出信息。

  5. （可选）ESP-IDF：运行 idf.py reconfigure 任务 命令生成 compile_commands.json 文件，以便启用语言支持。也可以按照 C/C++ 配置 文档中的说明来配置 .vscode/c_cpp_properties.json。

  6. 请自行对代码进行必要修改。完成项目后，点击状态栏图标 构建 或按 F1 输入 ESP-IDF：构建项目 来构建项目。

  7. 点击状态栏图标 烧录 或按 F1 输入 ESP-IDF：烧录项目，依据使用的接口类型，在命令面板中选择 UART、DFU 或 JTAG，将应用程序烧录到设备上。

  8. 点击状态栏图标 烧录方式 或按 F1 输入 ESP-IDF：选择烧录方式，从 UART、DFU 或 JTAG 中选择想要更改的烧录方式。也可以直接使用命令 ESP-IDF：通过 UART 接口烧录项目、通过 JTAG 接口烧录项目 或 ESP-IDF：通过 DFU 接口烧录项目。

  9. 点击状态栏图标 监视器 或按 F1 输入 ESP-IDF：监视设备 启动监视器，在 VS Code 终端中记录设备活动。

  10. 根据 ESP-IDF 文档中的要求来配置驱动程序，详情请参考配置 JTAG 接口。

  11. 在调试设备之前，先按 F1 输入 ESP-IDF：选择 OpenOCD 开发板配置，选择设备的 OpenOCD 开发板配置文件。点击状态栏图标 openocd 或按 F1 输入 ESP-IDF：OpenOCD 管理器 命令来测试连接。可以在菜单栏中的查看 -> 输出里选择下拉列表中的 ESP-IDF 来查看输出信息。

    注意： 可以使用 ESP-IDF：OpenOCD 管理器 命令或者点击 VS Code 状态栏中的 OpenOCD Server (Running | Stopped) 按钮来启动或停止 OpenOCD。

  12. 确保项目已经构建并烧录，OpenOCD 连接正常，调试器能正常工作。按 F5 启动调试会话。调试会话的输出可在菜单栏中选择查看 -> 调试控制台进行查看。

如有问题，请参阅故障排除部分。

拓展阅读

所有的教程、命令和功能都收录在适用于 VS Code 的 ESP-IDF 扩展文档中心。

可用命令列表

按 F1 或点击菜单栏中的查看 -> 命令面板，输入 ESP-IDF 即可查看 ESP-IDF 扩展所支持的所有命令。

类别 命令 描述 快捷键（Mac） 快捷键（Windows/Linux）
设置 添加 Docker 容器配置 将 .devcontainer 文件添加到当前打开的项目目录中，从而能借助 Dev Containers 扩展 在 Docker 容器中使用 ESP-IDF 项目。
添加 VS Code 配置文件夹 将 .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 G Ctrl E G
构建项目 使用 CMake 和 Ninja-build 来构建项目，具体说明请参见 ESP-IDF 构建系统直接使用 CMake。若想修改构建任务的行为，可以在配置 Cmake 时使用 idf.cmakeCompilerArgs 命令，或在配置 Ninja 时使用 idf.ninjaArgs 命令。例如，可以使用 [-j N] 来设置并行作业数，其中 N 是并行作业的数量。 ⌘ I B Ctrl E B
二进制文件大小分析 启动 UI 以显示 ESP-IDF 项目的二进制文件大小信息。 ⌘ I S Ctrl E S
选择要使用的端口 选择用于 ESP-IDF 任务（如烧录或监视设备）的串口。 ⌘ I P Ctrl E P
烧录项目 将当前项目生成的二进制文件烧录至目标设备。此命令将根据 idf.flashType 使用 UART、DFU 或 JTAG 接口。 ⌘ I F Ctrl E F
监视设备 此命令将执行 idf.py monitor，与乐鑫设备进行串行通信。 详情请参见 IDF 监视器。 ⌘ I M Ctrl E M
打开 ESP-IDF 终端 启动一个配置了 ESP-IDF 扩展设置的终端窗口，效果类似于 ESP-IDF CLI 的 export.sh 脚本。 ⌘ I T Ctrl E T
选择 OpenOCD 开发板配置 选择与使用的乐鑫设备目标相匹配的 OpenOCD 配置文件。例如，可以选择 DevKitC 或 ESP-Wrover-Kit。使用 JTAG 接口进行烧录或对设备进行调试时，此步骤必不可缺。
构建、烧录项目并监视设备 此命令可用于构建项目、将二进制程序写入设备，并启动监视终端，效果类似于 idf.py build flash monitor。 ⌘ I D Ctrl E D
创建项目 展示示例项目 启动 UI 以显示所选框架的示例，可从中创建新项目。此命令将显示扩展中已配置的框架，如果想查看 ESP-Rainmaker 示例，需要先运行 安装 ESP-Rainmaker 命令（或设置相应的 idf.espRainmakerPath），然后执行此命令以查看示例。
基于模板创建新项目 使用扩展中的项目模板来创建一个新的 ESP-IDF 项目。 ⌘ I C Ctrl E C
创建新 ESP-IDF 组件 在当前目录下，基于 ESP-IDF 组件模板创建新组件。
导入 ESP-IDF 项目 导入现有的 ESP-IDF 项目，在新位置添加 .vscode 和 .devcontainer 文件，同时可以重命名项目。
新建项目 启动 UI，通过 ESP-IDF 项目创建向导，使用 ESP-IDF 中的示例模板和扩展中配置的其他框架。 ⌘ I N Ctrl E N
烧录 选择烧录方式 选择用于 烧录项目 命令的烧录方法，可选择 DFU、JTAG 或 UART 接口。
烧录项目 将当前项目生成的二进制文件烧录至目标设备。此命令将根据 idf.flashType 使用 UART、DFU 或 JTAG 接口。 ⌘ I F Ctrl 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 R Ctrl 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-IDF 资源管理器的 EFUSEEXPLORER 中清除 eFuse 摘要集。
QEMU 启动 QEMU 服务器 如 QEMU 文档中所述，此命令将使用项目的 Dockerfile 和二进制文件执行 ESP32 QEMU。
启动 QEMU 调试回话 如 QEMU 文档中所述，此命令将使用项目的 Dockerfile 和二进制文件启动 ESP32 QEMU 的调试会话。
监视 QEMU 设备 如 QEMU 文档中所述，此命令将启动终端，通过使用项目的 Dockerfile 和二进制文件来监视 ESP32 QEMU。
监视 监视设备 该命令将执行 idf.py monitor，启动计算机与乐鑫设备之间的串行通信。 详情请参阅 IDF 监视器。 ⌘ I M Ctrl E M
启动 IDF 监视器以支持 Core Dump 模式/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 G Ctrl 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 R Ctrl 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 文档中进行搜索，搜索结果将显示在 VS Code ESP-IDF 资源管理器选项卡中。 ⌘ I Q Ctrl E Q
搜索错误提示 输入文本，在 ESP-IDF 提示库中搜索匹配的错误。
 清理 清除 ESP-IDF 搜索结果 清除资源管理器文档搜索结果选项卡中的所有搜索结果。
清除已保存的 ESP-IDF 设置 清除扩展中保留的现有 ESP-IDF 设置。

针对 tasks.json 和 launch.json 的命令

扩展中实现了一些实用工具命令，可以在 tasks.json 和 launch.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 工具链的绝对路径。

在调试文档中查看示例。

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 服务器将输出调试日志。

注意： 将 <project-directory>/.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

  1. 在 VS Code 菜单栏中选择帮助 > 切换开发人员工具，Console 选项卡中会显示与扩展相关的错误信息，可自行复制。

  2. VS Code 支持不同级别的设置，如：全局（用户设置）、工作区 和 工作区文件夹，请确保项目配置正确。运行 ESP-IDF：诊断命令得到的结果可能来自于用户设置，而非工作区文件夹。

  3. 查看 OpenOCD 故障排除 FAQ，可帮助进行应用追踪及调试，并解决 OpenOCD 输出中显示的其他相关问题。

  4. 有时 VS Code 中配置的默认 shell（Powershell、zsh、sh 等）可能会影响扩展的行为。请确保环境中未设置 MSYS/MinGW，且变量与终端行为不冲突。ESP-IDF：诊断命令会显示运行构建、烧录和监视任务时扩展检测到的 shell。详情请参考此处。

如果出现 Python 包错误，请尝试使用 ESP-IDF：安装 ESP-IDF Python 包 命令重新安装所需的 Python 包，或通过 ESP-IDF：配置 ESP-IDF 扩展 命令重新设置。

注意： 在 Windows 中通过 Git 克隆 ESP-IDF 时，如果出现 "unable to create symlink" 错误，可启用开发者模式进行克隆，从而解决该问题。

如果有无法解决的错误，请在 GitHub 仓库问题区 搜索相似问题，也可点击此处提交新问题。

行为准则

该项目及其所有参与者都受到行为准则的约束。参与本项目时，应遵守此准则。若发现任何不规范行为，请报告至 vscode@espressif.com。

许可证

此扩展基于 Apache License 2.0 授权许可。有关附加版权声明和条款，请参见许可证。