系列文章目录

---

前言

---

一、视频教程快速入门

        通过我们简单易学的视频教程，快速掌握新版本的使用方法：

二、功能描述

2.1 创建/导入项目

        STM32 VS Code 扩展提供两种不同的项目创建选项：

• STM32CubeMX 项目： 这是一个依靠 CMake 作为构建系统的 STM32CubeMX 管理项目。
• 空项目： 这是一个裸机项目设置，只包含启动 STM32 设备所需的最低限度的代码和脚本集。

        将项目导入 VS Code 时，扩展程序将自动生成 .vscode 文件夹，其中包含编辑/编译/调试所需的元数据（假设项目中尚未存在）。

        有关项目创建的全面指导，请观看我们的教程视频，标题为 "如何使用 STM32 VS Code 扩展创建项目"，该视频为新用户和有经验的用户提供了分步指导。

2.1.1 创建 STM32CubeMX 项目

        如果安装了 STM32CubeMX，"启动 STM32CubeMX "按钮将打开 STM32CubeMX。它允许用户为所选设备创建、配置和生成初始化 C 代码。

        要创建以 VS Code 为目标的项目，用户必须在 STM32CubeMX 的项目管理器面板中选择 CMake 的工具链。
        有关 STM32CubeMX 的更多信息，请参阅 UM1718。

        当选择 CMake 作为工具链时，STM32CubeMX CMake 生成器会生成以下文件：

• cmake\ 文件夹： 此文件夹包含 CMake 相关文件：
  • stm32cubemx" 文件夹： 该文件夹包含 CMakeLists.txt。STM32CubeMX 管理此文件
  • Gcc-arm-none-eabi.cmake： 仅由 STM32CubeMX 生成一次，用户拥有并管理此文件
• CMakeLists.txt： 仅由 STM32CubeMX 生成一次，用户拥有并管理此 CMake 文件
• CMakePresets.json： 仅由 STM32CubeMX 生成一次，用户拥有并管理此文件
• STM32xxxxxxx_FLASH.ld： 链接器脚本。STM32CubeMX 和用户共享所有权

        STM32CubeMX 创建的项目目前不包含 .vscode 文件夹。当使用 "导入 CMake 项目 "按钮在 VS Code 中导入项目时，VS Code 扩展会自动创建该元数据文件夹。

2.1.2 创建一个空项目

        该按钮可生成一个模板项目，其中包含构建项目、初始化 MCU 和分支到 main() 所需的最少一组源文件和元数据文件。这种项目类型的目标用户是需要最大灵活性、最少依赖性和完全所有权的最终用户。用户完全可以添加 HAL/LL 驱动程序，或从头开始编写自己的代码和驱动程序。

        点击后，系统会提示用户输入项目名称。

        命名项目后，文件浏览器将打开，允许用户浏览和选择项目目录。

        下一步是选择目标，目标可以是设备或电路板。

        随后，系统会显示项目摘要，用户可以在单击 "创建项目 "或 "操作 "完成项目创建过程之前查看详情。

        成功创建后，VS Code 会向用户提供三种打开新项目的选项：

• 将项目添加到当前打开的文件夹中
• 在新的 VS Code 会话中打开包含项目的文件夹 <-- 推荐选项！
• 在现有工作区中添加项目链接

小贴士 在 VS Code C/C++ 世界中，通常的做法是每个项目只有一个 VS Code 实例。这是与 STM32CubeIDE 的主要区别，后者通常在一个工作区中打开多个项目。每个 VS Code 实例只有一个项目，可确保编辑器索引、构建和调试的上下文以最佳方式运行。因此，我们推荐第二种方案。

        STM32 VS 代码扩展生成的项目结构如下：

• .vscode\ 文件夹： 包含元数据的文件夹：
  • c_cpp_properties.json 文件夹： 该文件可确保 C/C++ 编辑器索引正常工作
  • extensions.json： 该文件提供额外的扩展建议
  • launch.json： 此文件自动生成调试配置
  • tasks.json： 此文件是执行某些任务（如加载 flash）的模板
• cmake\ 文件夹： 此文件夹包含 CMake 相关文件：
  • vscode_generated.cmake： 这是一个转换器生成的文件。只有 STM32 VS Code 扩展程序管理此文件
  • Gcc-arm-none-eabi.cmake： 仅由 STM32 VS Code 扩展生成一次，用户拥有并管理此文件
• Inc\ 文件夹： 此文件夹为空。用户可自行添加头文件
• Src\ 文件夹： 该文件夹包含 main.c、**syscall.c 和 sysmem 文件。用户可以在此文件夹中添加自己的源文件
• Startup\ 文件夹： 此文件夹包含启动文件 startup_stm32xxxxxxxx.s
• CMakeLists.txt 文件夹： 仅由 STM32 VS Code 扩展生成一次，用户拥有并管理此 CMake 文件
• CMakePresets.json： 仅由 STM32 VS Code 扩展生成一次，用户拥有并管理此文件
• STM32xxxxxxx_FLASH.ld： 链接器脚本。由 STM32 VS 代码扩展和用户共享所有权

2.1.3 导入 CMake 项目

        该功能允许用户将 CMake 项目（空项目或 STM32CubeMX 生成的项目）导入 VS Code。
        导入程序会检查项目是否已包含编辑/编译/调试所需的 json 文件。如果这些文件尚不存在，扩展程序将生成它们。

注意：
在 VS Code 中通过文件 -> 打开文件夹打开项目，而不是使用 STM32 VS Code 扩展的导入 CMake 项目，不会自动生成 json 文件。

        随后，用户会看到一个项目摘要，允许他们在单击 "导入项目 "或 "操作 "完成流程之前查看详细信息。

        成功导入后，VS Code 会为用户提供三种打开项目的选项：

• 将项目添加到当前打开的文件夹中
• 在新的 VS Code 会话中打开包含项目的文件夹
• 在现有工作区中添加项目链接

        启动 STMCUFinder
        如果安装了 ST-MCU-FINDER，该按钮将打开 ST-MCU-FINDER，允许用户浏览各种 STM32 和 STM8 微控制器、微处理器、开发板和示例。有关 ST-MCU-FINDER-PC 的更多信息，请参阅 DB3190。

2.2 启动 STMCUFinder

        如果安装了 ST-MCU-FINDER，该按钮将打开 ST-MCU-FINDER，允许用户浏览各种 STM32 和 STM8 微控制器、微处理器、开发板和示例。有关 ST-MCU-FINDER-PC 的更多信息，请参阅 DB3190。

2.3 升级 STLINK 固件

        该功能允许用户通过 USB 端口升级设备或电路板的固件。

        提示：在首次调试启动之前，许多电路板都需要更新 ST-LINK 固件！

三、构建项目

3.1 选择构建目标

        要选择构建目标，首先要

• 通过设置或使用键盘快捷键 Ctrl + Shift + P 访问 VS 代码命令调板
• 搜索 CMake 预设并选择 "选择配置预设
• 选择构建目标，完成整个过程。

3.2 添加构建目标

        要添加构建目标，首先要

• 通过设置或使用键盘快捷键 Ctrl + Shift + P 访问 VS 代码命令调板
• 搜索 CMake 预置并选择添加配置预置
• 选择其中一个选项，然后按照其余步骤选择所需的构建目标

3.3 开始构建

        要构建项目，请单击 "构建 "选项，如下图所示。输出控制台将显示构建结果。

四、调试项目

        要快速了解项目调试，请观看我们的教程视频，标题为 "如何使用 STM32 VS Code Extension 进行调试"，其中提供了针对新用户的分步说明。

4.1 启动调试

        launch.json 文件包含有关调试配置的信息。该扩展创建了两种默认调试配置：

• （Build & Debug Microcontroller - ST-Link）构建和调试微控制器 - ST-Link： 该选项允许你构建代码，将其加载到微控制器上，并启动调试。
• （Attach to a running target）附加到运行目标： 使用该选项，可以将调试器连接到正在运行的目标，而无需下载新固件。

        用户可通过编辑 launch.json 文件修改和创建自己的配置。有关创建新启动配置的更多详情，请参阅相关章节。

注意
我们建议在启动调试程序之前更新 STLINK 固件，以防止出现潜在问题。更多信息，请参阅 "无法启动调试 "一节。

        要启动调试，请选择启动配置并单击 "启动 "按钮。在此阶段，用户可以观察局部变量和全局变量、在观察堆栈中加入表达式、设置断点以及查看外设寄存器。

4.2创建新的启动配置

        要创建新的启动配置，请按照以下步骤操作：

• 打开运行和调试
• 访问 launch.json 文件
• 点击添加配置
• 选择所需的启动类型
• 调整设置以匹配您的配置
• 保存 launch.json 文件，添加新的启动配置

五、故障排除

5.1 构建相关问题

5.2 CMake 版本问题

        如果您有多个使用 CMake 的软件或工具，VS Code 可能会引用扩展所需的不正确版本。如果出现这种情况，您可能会遇到编译错误，提示信息为：需要 CMake 3.22 或更高版本。您正在运行 x.y.z 版本。

        要解决这个问题

• 关闭 VS 代码
• 访问启动系统上的环境变量设置，确认 STM32CubeCLT_PATH 设置正确
• 重新启动 VS 代码并继续项目构建过程

5.3 清理构建配置

        在使用旧版本的 STM32CubeMX、STM32CubeCLT 或扩展本身编译项目的情况下，重建项目有时可能会失败。为防止或解决此问题，可通过设置或使用键盘快捷键 Ctrl + Shift + P 打开 VS Code 命令调板，然后搜索 CMake：删除缓存并重新配置。

5.4 无法启动调试

        如果调试器无法连接到电路板，请首先查看调试控制台，检查根本原因。如果看到 "初始化 STLINK 设备时出错。原因： 需要升级 STLINK 固件，只需点击升级 STLINK 固件功能即可解决此问题。

5.5 调试相关问题

        当涉及到大型复杂项目时，用户在尝试在自己的 PCB 上调试 STM32CubeMX 生成的应用程序时可能会遇到一些问题。

        我们的建议是创建一个新的空项目，其中只包含启动 MCU 所需的最小源文件集。如果该项目能在设备上编译、闪烁和调试，那么剩余的问题可能来自 STM32CubeMX 生成的代码、用户代码或选项字节不匹配。

六、将基于 STM32 的项目迁移到 VS Code v2.0.0

        将项目从一种工具迁移到另一种工具并不是一项复杂的任务，但确实需要遵循特定的步骤顺序。
        迁移所需的步骤数量因项目的原始起点和所依赖的工具而异。一般来说，迁移过程可分为三类。请确定最适合您项目的类别，以确保迁移成功。

• 类别 1：项目使用 STM32CubeIDE/MX 创建，并由 1.0.0 版本的 STM32 VS Code 扩展管理
• 类别 2：该项目使用 STM32CubeIDE/MX 创建，但未迁移至 STM32 VS Code 扩展的 1.0.0 版本
• 类别 3：该项目不是使用 STM32CubeIDE/MX 生成的。在这种情况下，有两种可能的解决方案：
  • 如果项目使用 CMake，您可以通过单击 Import CMake project（导入 CMake 项目）按钮将其导入。
  • 如果项目不使用 CMake：
    • 单击 "创建空项目 "按钮创建一个空项目
    • 将所有文件和构建设置转移到基于 CMake 的空项目中

        要将基于类别 1 或类别 2 的项目迁移到新的 VS Code 解决方案，请按照以下步骤操作。

1. 前提条件

   确保已安装 STM32CubeMX v6.11.0、STM32CubeIDE v1.15.0 和 STM32CubeCLT v1.15.0 或更新版本。

2. 进行备份

   在更新任何工具或嵌入式软件时，建议创建还原点或备份副本，以防升级或迁移结果不理想。我们的建议是，要么在版本库中提交/标记，要么创建整个项目的备份。

3. 更新 STM32CubeMX 和 STM32Cube 固件

   迁移可能需要升级到新版本的 STM32CubeMX，这可能会引入新的 HAL 驱动程序或代码生成中的细微变化。
   在继续将项目迁移到本地 CMake 项目之前，请确保更新后 STM32CubeIDE 中的构建和调试结果符合预期。为此

   3.1 使用 STM32CubeIDE v1.15.0 或更新版本打开项目
   3.2. 打开 STM32CubeMX ioc 文件，如果有新的 STM32Cube 固件包，则将项目迁移到该固件包上。 
   3.3. 重新生成代码  
   3.4. 使用 STM32CubeIDE 构建和调试项目  

   

   如果这些步骤已顺利完成，请关闭 STM32CubeIDE，因为迁移过程的剩余部分将在文件系统上进行。

4. 删除旧文件
   由于新的 STM32CubeMX 和 VS Code 解决方案所引入的概念变化，用户有必要手动删除某些与项目相关的元数据。
   STM32CubeMX 会在后续步骤中再次生成相应的元数据，并通过 VS Code 扩展的更新版本进一步增强。代码本身保持不变。

   在继续删除元数据文件之前，我们建议创建项目的备份还原点。

   a. 如果您的项目仅通过 STM32CubeIDE 访问过，尚未使用 STM32 VS Code for 扩展打开，请删除以下文件：

   a.1. .settings/ : folder containing some metadata
   a.2. .cproject : file containing build configuraitons for STM32CubeIDE
   a.3. .project : file containing project natures and paths to c/h folders and/or files

   b. 如果您的项目以前使用过 STM32CubeIDE 和 STM32 VS Code 扩展 1.0.0，除前面提到的文件外，请删除以下文件：

   b.1. .vscode folder
   b.2. build folder
   b.3. cmake folder
   b.4. CMakeLists.txt
   b.5. CMakePresets.json
   b.6. nvcpkg_configuration.json

   删除指定文件后，我们将开始重新创建基于 CMake 的新构建结构。只有 STM32CubeMX 可以管理这个新结构。

5. 使用 STM32CubeMX 生成 CMake 项目
   要继续迁移过程，请按照以下步骤操作：

   5.1. 启动 STM32CubeMX 6.11.0 或更新版本（单机模式，不在 STM32CubeIDE 内）  
   5.2. 加载要迁移的项目  
   5.3. 访问项目管理器面板  
   5.4. 将 "工具链/集成开发环境 "从 "STM32CubeIDE "切换到 "CMake"。 
   5.5. 点击 "GENERATE CODE（生成代码）"按钮 

   

   当选择 CMake 作为工具链时，STM32CubeMX CMake 生成器会生成以下文件：

   cmake\ 文件夹： 此文件夹包含 CMake 相关文件：
       stm32cubemx" 文件夹： 此文件夹包含 CMakeLists.txt。只有 STM32CubeMX 管理此文件
       Gcc-arm-none-eabi.cmake： 由 STM32CubeMX 生成后，用户可以编辑该文件
   CMakeLists.txt： 由 STM32CubeMX 生成后，用户拥有并管理此文件
   CMakePresets.json： 由 STM32CubeMX 生成后，用户拥有并管理此文件
   STM32xxxxxxx_FLASH.ld： 由 STM32CubeMX 生成的链接器脚本，表明 CMake 被选为工具链

   
   现在您可以通过命令行编译您的项目，方法是依次输入以下命令：

   PROJ_FOLDER$> cmake -B build -G Ninja
   PROJ_FOLDER$> cmake --build build -j

   

6. 设置新的 VS Code 环境
   对于 VS Code 的新用户来说，使用 VS Code 中的配置文件概念将 STM32 环境沙盒到自己的配置文件中可能会很有帮助。点击此处了解更多信息。

   要将项目导入 VS Code，请按照以下步骤操作：

   6.1. 打开 VS Code 并安装新扩展 2.0.0 版，该版本可与新的 STM32CubeMX 6.11.0 或更高版本以及 STM32CubeCLT 1.15.0 或更高版本一起使用。
   6.2. 使用 "Import local project（导入本地项目）"按钮/命令，指向 STM32CubeMX 生成的项目文件夹。

   

   导入项目后，VS Code 扩展会自动生成以下文件：

   .vscode 文件夹： 包含元数据的文件夹：
   c_cpp_properties.json： 该文件可确保 C/C++ 编辑器索引正常工作
   extensions.json： 该文件提供额外的扩展建议
   launch.json： 此文件自动生成调试配置
   tasks.json： 此文件是执行某些任务（如加载 flash）的模板

   注意：

   首次在 VS Code 中打开项目时，可能会遇到一些提示，例如

   选择 CMake 预设： 选择调试预设
   安装 Better C++ Syntax： 高亮显示 C 和 C++ 语法的高效扩展程序
   配置 CMake 选项可见性： 使用设置中的 cmake.options 属性自定义视图

7. 在新生成的 CMakeList.txt 文件中添加您的私有文件夹源路径
   如果您的项目包含私有文件夹，在 CMakeList.txt 文件中包含其路径至关重要。

8. 如果需要，更新 CMake 文件以使用项目中已有的链接器脚本：
   这可以在 \cmake\gcc-arm-none-eabi.cmake 文件中修改。示例

   set(CMAKE_C_LINK_FLAGS "${CMAKE_C_LINK_FLAGS} -T \"${CMAKE_SOURCE_DIR}/STM32F407VGTx_FLASH.ld\"")

9. 构建和调试项目
   更多详情，请参阅 "构建项目 "和 "调试项目 "部分。

   对于高级调试功能，我们建议同时使用 STM32CubeIDE 作为调试器工具。更多详情，请参阅 "使用 STM32CubeIDE 进行高级调试"。

10. 恭喜您！您现在已经设置好了。您可以随时在 STM32CubeMX 中更新配置。生成的 CMake 文件和源代码可在 VS Code 中正常运行。

七、提示和技巧

7.1 防止弹出窗口

        当您打开资源中提到的一些外部网站时，VS Code 可能会提示您，因为它不会自动信任这些网站。
        要避免这种提示，请打开 "配置受信任的域 "并信任所需的域。

7.2 使用 STM32CubeIDE 进行高级调试

        如果您需要 VS Code 中不具备的高级调试功能，您可以将 STM32CubeIDE 用作 VS Code 的辅助调试工具。
        为此，您需要将项目创建的 elf 文件从 VS Code 导入 STM32CubeIDE。这样，您就可以使用 STM32CubeIDE 的所有基本和高级调试功能。尽管没有导入 C/C++ 代码，源代码查找仍可正常运行。通过这种方法，您可以结合两种工具的优势，使用 VS Code 进行编辑、编译和调试，同时使用 STM32CubeIDE 的高级调试功能。

        要开始使用，请打开 STM32CubeIDE 并选择文件 > 导入 > C/C++ > STM32 Cortex®-M 可执行文件。

        然后，浏览并选择 elf 文件，并指定目标设备。

        如有必要，请编辑启动配置并点击调试。

        就是这样！现在，您可以使用 STM32CubeIDE 的高级调试功能了。

7.3 保留已安装的多个 STM32 VS Code 扩展程序版本：

        要在安装最新版本的同时保留以前版本的 STM32 VS 代码扩展，需要按照以下步骤创建新的配置文件：

• 导航至 VS Code 配置文件并创建新配置文件
• 为配置文件指定一个名称，然后选择 "创建 "完成该过程

• 创建配置文件后，继续安装最新版本的 STM32 VS Code 扩展程序
• 现在，您有两个配置文件：一个包含 v1.0.0，另一个包含 v2.0.0

         对于 VS Code 的新用户，请在此处阅读有关配置文件的更多信息。