Zhejiang University RoboMaster Vision

构建电控工作环境

在 Ubuntu 上使用 VS Code、STM32CubeIDE for Visual Studio Code 与 CMake/Ninja 构建、烧录 STM32 工程。

电控组约 8 分钟
#电控#STM32#VS Code#CMake#Ninja#Ubuntu

本文的工作环境是 Ubuntu + VS Code + STM32CubeIDE for Visual Studio Code + STM32CubeCLT + CMake/Ninja + J-Link。默认你已经完成 VS Code、Git、STM32CubeMX、STM32CubeCLT 与 SEGGER J-Link 软件的安装，并拿到了一个由队内维护的 STM32 工程。

工程的 .ioc、CMakeLists.txt、CMakePresets.json、.vscode/ 与 README 都属于项目配置的一部分。已有工程应优先沿用这些文件和负责人的约定，不要为了套用其他教程而重新生成 CubeMX 工程或替换工具链。

1. 先看参考视频

在开始配置前，先观看参考视频，了解一次完整的配置、构建与烧录操作：

视频中的安装位置、工程名和芯片型号可以不同，但操作顺序是相同的：打开工程 → 配置工具链 → Configure → Build → 连接 J-Link → Flash / Debug。下面的文字用于补充视频中容易遗漏的细节，并给出队内推荐做法。

2. 为电控创建独立的 VS Code Profile

视觉开发与嵌入式开发需要的扩展、终端环境和设置不同。建议为电控单独建立一个 VS Code Profile，避免 CMake、调试和 STM32 相关设置影响视觉工作区。

  1. 在 VS Code 左下角点击齿轮，选择 Profiles → Create Profile；也可以在命令面板运行 Profiles: Create Profile。
  2. 选择创建空 Profile，名称填写 STM32 或 电控开发。
  3. 创建完成后，确认左下角当前 Profile 已切换为这个新 Profile。
  4. 后续所有 STM32 扩展都安装在该 Profile 中；视觉开发时切回原来的 Profile。

Profile 会分别保存已安装扩展和多数用户设置，但同一个项目下的 .vscode/ 配置仍由项目共享。不要把只适合个人电脑的绝对路径直接提交进仓库；个人路径应放在本地用户设置，或使用环境变量表示。

3. 安装并检查扩展

在刚创建的 STM32 Profile 中打开 Extensions，搜索并安装以下扩展：

扩展用途
STM32CubeIDE for Visual Studio CodeST 的 STM32 集成扩展；用于配置、构建、烧录和调试入口
C/C++（Microsoft）代码补全、跳转与诊断
CMake Tools（Microsoft）查看和操作 CMake 配置；部分项目仍会用到

扩展安装后，重新加载 VS Code 窗口一次。打开工程根目录，而不是只打开 main.c。如果扩展提示选择工程、配置或 build preset，优先选择 README、CMakePresets.json 或负责人指定的选项。

4. 首选：让 Agent 协助完成本机配置

不同同学的 CubeCLT 安装版本和目录可能不同。相比手工复制路径，推荐先在已打开的工程根目录中让 Agent 检查本机并生成个人配置。

将下面的提示词原样发送给你使用的编程 Agent；其中方括号的内容按实际情况填写：

我在 Ubuntu 上打开了一个 STM32 CMake 工程。请帮我完成 VS Code 的本机开发环境配置。

要求：
1. 先只读检查当前仓库的 README、CMakeLists.txt、CMakePresets.json、.vscode/ 和现有脚本，不能覆盖或删除已有配置；
2. 在本机查找 STM32CubeCLT 与 SEGGER J-Link，并确认 arm-none-eabi-gcc、cmake、ninja、JLinkExe、JLinkGDBServerCL（如已安装）的实际路径和版本；
3. 工程使用 CMake + Ninja。优先沿用项目的 preset、toolchain file 和构建目录；不要随意新增第二套编译器配置；
4. 只为当前用户创建必要的 VS Code 配置。若必须修改 .vscode 文件，请先说明将修改什么；个人绝对路径不要写入将提交到仓库的文件；
5. 配置完成后执行一次 CMake Configure 和 Build，并报告生成的 .elf/.bin/.hex 路径；
6. 不要烧录、不删除 build 目录、不安装系统软件。把需要我手动确认的步骤单独列出。

我的 STM32CubeCLT 可能安装在：[填写安装目录；不知道则填“请搜索常见目录”]
当前工程使用的板卡与 target：[填写；不知道则说明“以仓库配置为准”]

执行 Agent 建议前，先阅读它将要改动的文件和命令。Agent 的职责是定位本机工具、复用项目配置和减少手填错误；它不能替代对板卡、供电和烧录目标的确认。

5. 备用：手工让 VS Code 找到工具链

如果不使用 Agent，先在终端定位 CubeCLT。常见安装位置类似 ~/ST/STM32CubeCLT_<版本号>，但以你的实际安装目录为准：

find "$HOME" -maxdepth 4 -type f -name arm-none-eabi-gcc 2>/dev/null
find "$HOME" -maxdepth 4 -type f -name cmake 2>/dev/null
find "$HOME" -maxdepth 4 -type f -name ninja 2>/dev/null

找到后，确认工具可运行：

/实际路径/arm-none-eabi-gcc --version
/实际路径/cmake --version
/实际路径/ninja --version

若队内没有提供 CMakePresets.json 或工具链文件，可在 VS Code 的用户设置中配置 CMake 路径和 Ninja 生成器。下面仅作结构示例，请替换为实际路径：

{
  "cmake.generator": "Ninja",
  "cmake.cmakePath": "/home/<用户名>/ST/STM32CubeCLT_<版本号>/CMake/bin/cmake"
}

更常见的做法是把工具目录加入 ~/.bashrc 的 PATH，然后重新打开终端和 VS Code：

export PATH="$HOME/ST/STM32CubeCLT_<版本号>/GNU-tools-for-STM32/bin:$PATH"
export PATH="$HOME/ST/STM32CubeCLT_<版本号>/CMake/bin:$PATH"
export PATH="$HOME/ST/STM32CubeCLT_<版本号>/Ninja/bin:$PATH"

路径中的 <版本号> 必须替换为实际目录名。不要把这类个人路径写入仓库的 CMakeLists.txt 或提交到共享的 .vscode/settings.json。

6. 在 VS Code 中配置、构建与烧录

6.1 Configure 与 Build

  1. 以 STM32 Profile 打开工程根目录。
  2. 在 STM32CubeIDE for Visual Studio Code 的项目视图中选择项目配置；若项目有 Debug、Release 或 CMake preset，按 README 选择。
  3. 首次使用时执行 Configure，等待 CMake 完成生成。
  4. 执行 Build，在输出中确认使用的是预期的 arm-none-eabi-gcc，并等待构建成功。
  5. 在构建目录中确认 .elf、.bin 或 .hex 的实际路径。调试通常使用 .elf，烧录镜像格式以项目任务为准。

也可用终端验证，但只在项目没有规定其他命令时使用：

cmake -S . -B build -G Ninja
cmake --build build

如果工程使用 CMakePresets.json、自定义工具链文件或脚本，不要把这两条示例命令和项目约定混用。

6.2 连接板卡

构建通过后，再连接 J-Link 与目标板。先确认：

  • J-Link、目标板和工程 target 是同一套硬件；
  • 调试接口类型与板卡配置一致（通常为 SWD），并确认 SWDIO、SWCLK、GND 与供电连接正确；
  • 电机或其他执行器处于架空、限功率或未使能的安全状态；
  • 当前没有其他程序占用 J-Link。

在终端检查 USB 设备和内核日志有助于判断下载器是否被 Ubuntu 识别：

lsusb
dmesg | tail -n 30

6.3 Flash 与 Debug

  1. 在 STM32CubeIDE for Visual Studio Code 中选择项目提供的 J-Link 调试/烧录配置，再进入 Flash / Run 或 Debug；不同版本的按钮名称和位置可能略有不同。
  2. 确认弹出的目标板、烧录接口和镜像文件与当前项目一致，再开始烧录。
  3. 等待写入和校验完成；出现连接错误时先停止，不要连续反复烧录。
  4. 烧录完成后，打开项目约定的串口监视方式，确认启动日志、固件版本和自检信息。
  5. 只有在日志和状态均正常后，才在安全条件下验证一个小幅、可预测的动作。

如果项目没有提供 J-Link 的 VS Code 配置，不要自行猜测 J-Link 设备型号、接口、速度、烧录地址或 OpenOCD target 文件。应使用负责人提供的 task、脚本或调试配置。

7. 常见问题

现象优先检查
arm-none-eabi-gcc: command not foundCubeCLT 安装位置、PATH、重开的终端与 VS Code
CMake 选择了系统 GCC项目的 preset/toolchain file；不要在多处重复指定编译器
CMake 找不到 Ninjaninja --version、CubeCLT 路径与 cmake.generator
VS Code 无法跳转或补全重新 Configure，检查 compile_commands.json 与 C/C++ 扩展
J-Link 未识别USB 连接、板卡供电、SWD 接线、SEGGER 软件与 Linux udev 权限，以及是否被其他程序占用
烧录成功但程序无输出实际烧录 target、串口设备与波特率、TX/RX/GND、日志是否启用

完成本篇后，你应能在独立的 STM32 Profile 中打开既有工程，让 Agent 或手工配置本机工具链，在 VS Code 中完成 Configure、Build、Flash，并通过日志验证固件已启动。修改板级外设、电机使能、CAN 或通信协议前，仍应先与电控负责人确认。

返回入组培训
|
添加批注