环境配置
从零到能烧录。

给谁看：会一点 C，没用过 CMake / 交叉编译 / 嵌入式工具链的同学。 前提：Windows 10/11（最好有管理员权限）+ 一块主控板 + 一个调试器。 要多久：走通第 1~4 章（配置 → 编译 → 烧录）约 2~3 小时（下载占大半）。 把第 5、6 章（Ozone / VS Code 调试）也做完，一共约 4~5 小时。

怎么读：第 0 → 1 → 2 → 3 → 4 章，按顺序，别跳。 任何一步报错都不要跳过，去 第 7 章 按报错现象查表。

一个约定：命令里的路径分两种 —— 仓库根目录（能看到 project.py 的那一层，你自己解压出来的位置） 和 <你的工具目录>（工具的安装位置，第 1 章装完就在那儿；本文示例写成 C:\Tools\）。 ⚠️ 只有 Ninja 必须放在 C:\Tools\ninja\（见 §0.3）—— 其余工具换到别的盘、别的目录都行， 但换了目录之后，命令里的路径要跟着换成你自己的实际路径，也别改成相对路径。 本文用 RowletBot 当示例目录名，换成你自己的。

目录

第 0 章 开始之前

📖 本章导读

• 做什么：搞清楚这套环境是什么、要装哪十件工具、装完长什么样
• 需要：15 分钟，不用动手，读完就行
• 读完的标志：能说出「clang 编译、gcc 链接」，并知道自己该把仓库放在哪

0.1 一句话说清：这套环境是什么

你写的代码在你的电脑上被翻译成 ARM 机器码，打包成一个 .bin 文件，通过调试器烧进单片机，然后板子跑起来。

   ┌──────────────────────────┐   ①编译             ┌─────────────┐
   │ VS Code 写代码            │  ──────────────►   │  ┌─────────────┐  │
   │ clang 翻译成 ARM 码       │   生成 xrobot.bin   │  │ 只能跑 ARM   │  │
   └──────────────────────────┘                     │  │ 机器码       │  │
              ▲                    ②烧录             │  └─────────────┘  │
              │                ──────────────►      │         ▲         │
              │                通过调试器            └─────────┼─────────┘
              └─────────────────────── ③看现象（轮子转 / 灯闪）┘

三个新词：

0.2 十个工具，每个是干什么的

🔑 必须记住的反直觉点：clang 编译，gcc 链接

嵌入式教程通常说「就用 arm-none-eabi-gcc 编」，本框架不是这样：

• clang / clang++ 负责编译（加 --target=arm-none-eabi 变成交叉编译器）；
• arm-none-eabi-gcc 只负责链接 —— 因为工程用了 nano + nosys specs， 而 LLVM 的 lld 不支持 GCC 的 specs 文件；
• arm-none-eabi-size / objcopy / objdump / ar 负责后处理和归档。

结论：两套工具链都得装，缺一个都编不出来。

0.3 装完长什么样：目录布局（照抄即可）

⚠️ 只有 Ninja 必须放在 C:\Tools\ninja\（测试证明：它放别处会出问题）； 其余工具全部可以换盘 / 换目录。

下面这棵树是教程用的示例布局（照抄最省事）：

C:\Tools\
  ├─ ninja\                  ← Ninja ⚠️ 唯一"必须在这儿"的（ninja\ninja.exe）
  ├─ openocd\                ← OpenOCD（可以换盘，见 §1.9）
  └─ arm-gnu-toolchain\      ← ARM 工具链（可以换盘，见 §1.8）

用官方安装包安装的（下表是安装器的默认位置 —— 你可以改成别的盘/别的目录，改了记得自己记住）：

⚠️ 为什么 ARM 工具链建议别用安装器默认路径：ARM 安装器的默认路径是 C:\Program Files (x86)\Arm GNU Toolchain arm-none-eabi\13.3 rel1\ —— 里面有空格。 本工程的 toolchain.cmake 要把 sysroot 路径拼成编译参数传给 clang， 带空格的路径在这种场景下是经典的踩坑点；装到一个不含空格/括号的目录最省事 （教程示例：C:\Tools\arm-gnu-toolchain —— 换成 D:\Tools\arm-gnu-toolchain 一样可以）。

0.4 两条铁律（违反任何一条都会浪费你一整天）

0.5 开工前的准备清单

硬件

软件 / 账号

💡 学习阶段不需要 Git，也不需要 GitHub 权限 —— 框架用压缩包下发（见 §2.1）。 什么时候才需要 Git，见 §2.4。

第 1 章 装工具（逐步详细）

📖 本章导读

• 做什么：把九件工具装上（Ozone 在第 5 章单独装），并让 PATH 生效（本章最长，占了全程一多半时间）
• 需要：管理员权限、约 1.5 GB 下载量、2~3 小时（下载占大半）
• 做完的标志：新开一个终端，§1.11 那 7 条版本命令全都有输出

⚠️ 本章最容易崩心态的地方是"装完了但敲不出来" —— 那 99% 是 PATH 没生效， 不是你没装好。别急着重装，先看 §1.10 和坑 2。

1.0 装之前先读这 5 条

装之前花 2 分钟扫一遍，能省下几个小时。

第 1 条 · 什么算好路径

✅ C:\Tools\...                      ✅ %USERPROFILE%\Desktop\RowletBot
❌ C:\工具\...                       ❌ D:\我的 文件\...

第 2 条 · 四个不能装最新的工具（本教程最重要的版本约束）

第 3 条 · 为什么"重开终端"这么重要

终端只在启动的那一刻读一次 PATH，加完 PATH 不重开等于没加。 VS Code 的终端是 VS Code 的子进程 —— 所以VS Code 要整个关掉重开（见坑 2）。

🖥 "终端"是什么、在哪儿打开？（零基础看这里 —— 全教程只讲这一遍）

终端 = 敲命令的那个黑窗口（本文里 cmd 和 PowerShell 都算终端）。打开方法：

1. 同时按住键盘左下角的 Windows 键和 R 键（即 Win + R）， 屏幕左下角会弹出一个小窗口，标题是「运行」；
2. 在里面的输入框键入 cmd（三个字母），按回车；
3. 弹出的黑底白字窗口就是本文说的"终端"。窗口里会显示一行以 C:\Users\你的用户名> 开头的提示符，后面闪烁的方块就是光标 —— 命令就敲在这里。

以后每次改完 PATH，都要先把旧窗口关掉、再按上面三步重新开一个新的 —— 在旧窗口里敲什么都没用（原因就是上面那句话）。

💡 习惯 PowerShell 的话：第 2 步输入 powershell 再回车，效果一样。 ⚠️ 但本文标着 bat 的命令请用 cmd 跑 —— 有两条 cmd 写法在 PowerShell 里不成立： where 要写成 where.exe（PowerShell 里 where 是 Where-Object 的别名，敲 where git 什么都不显示）、 A & B 要拆成一行一条（& 在 PowerShell 里不是命令分隔符）。 标着 powershell 的代码块，当然要用 PowerShell 跑。

第 4 条 · 杀毒白名单怎么加

🔍 两条都找不到？用搜索：打开「设置」，在窗口顶部的搜索框里输入 病毒和威胁防护（或 Windows 安全中心），点搜出来的第一条，一样能进去。

进去之后：「病毒和威胁防护」设置里点 「管理设置」 → 往下滚，找到「排除项」（不在最底部 —— 它下面还有「通知」等几段）→ 「添加或删除排除项」 → 「添加排除项」→「文件夹」，把下面两个加进去：

⚠️ 点「添加或删除排除项」时会弹一个 UAC 管理员确认框，点「是」； 如果你的账号不是管理员，跳过这一条就行（只是编译慢，不影响正确性）。

⚠️ 注意：这两个文件夹现在都还不存在 —— 这一条要分两次做，别在这里卡住。

文件夹	现在怎么办
C:\Tools	现在就手工建一个空的：打开「此电脑」→ 进 C:\ → 在空白处右键 → 新建 → 文件夹 → 命名为 Tools（不能有空格），建完回到上面把它加进白名单。§1.6 装 Ninja 时就是往这个空文件夹里放东西，不影响。
你的仓库文件夹	先不加，等第 2 章解压完再回来补 —— 它要到 §2.2 解压压缩包时才出现。拿到 RowletBot 文件夹后，照上面同样的步骤再「添加排除项 → 文件夹」一次即可。

💡 不想现在建 C:\Tools 也行：整条先跳过，等 §1.6 建好 C:\Tools、第 2 章解压出仓库之后，再回来一次性加这两个文件夹。 但别拖到编译突然变慢才想起来 —— 那时你会以为是环境装坏了。

（C:\Tools 要你自己建（就是上面表里那次），教程不会替你建；仓库目录要到 第 2 章 才有。）

不加排除项编译要 5 分钟级，加了之后 20 秒级。 偶尔还会文件被锁住 → ninja: error: ... Permission denied。

第 5 条 · 想把工具装到别的盘（比如 C 盘小、只有 D/E 盘）

完全可以 —— 把十件工具全部装到 E 盘（E:\Tools\、E:\RowletBot）， 编译正常通过（mc02 上的目标 29.45 秒，与默认盘符无差别）。 只要满足"路径无中文无空格"（第 1 条）就行。

⚠️ 除了 Ninja，其余工具都可以换盘 —— Ninja 必须留在 C:\Tools\ninja\（测试证明它只有放这儿才稳）。

换盘后要一起改下面这几处，漏一处就会报「找不到命令」或「找不到工具链」：

💡 最省事的办法：换盘之后不用自己找，直接 双击 5-check.bat —— 它会告诉你每个工具实际在哪（位置： 那一行）、 环境变量可不可用（只有 3 件还额外核对版本，见 §1.11）。 位置： 那行有你的实际路径、判定是 [OK]，就说明你换对了。

📌 另外：仓库本身也可以放别的盘（放到 E:\RowletBot 完全正常）—— 工程里没有任何写死的盘符，见 §0.3。

1.1 第 1 步：7-Zip（解压工具）

下载：https://www.7-zip.org/ → 下 64-bit Windows x64 的 .exe 安装包 （文件名形如 7z*-x64.exe）。

安装：双击 → 确认 Destination folder 是 C:\Program Files\7-Zip\ → 点 Install → 装完点 Close。 （7-Zip 24 之后是单页安装器，没有 Next / Finish，这是正常的。）

为什么用它：

• ✅ 格式全：.zip / .7z / .rar / .tar.gz / .tar.xz / .iso 都能开；
• ✅ 快（多线程），解大包比别的工具快得多；
• ✅ 「解压到当前位置」直接铺在当前文件夹，不多套一层同名目录；
• ✅ 免费、开源、无广告、无捆绑。

1.2 第 2 步：VS Code

下载：https://code.visualstudio.com/download

版本不用挑 —— 官网默认给的就是最新稳定版，装最新即可。

安装：

1. 双击 → 接受许可协议 → 一路 Next；

   

   ⚠️ 如果你当前是管理员账户，用户版安装器会弹一个提示：

   复制

   This User Installer is not meant to be run as an Administrator.
   If you would like to install VS Code for all users in this system,
   download the System Installer instead.
   

   点「确定」继续就行 —— 不影响安装，也不影响 PATH 注册。 不用跑去下系统版重装（本文推荐用户版，见下面那个说明框）。

   中间还有「选择目标位置」和「选择开始菜单文件夹」两页 —— 都保持默认，直接 Next：

   

   

2. ⚠️ 关键一步：务必勾上「添加到 PATH」（Add to PATH，默认就是勾上的，别取消） —— 它和第 3 步那几项都在同一页「选择附加任务」里。

3. 把「其他」里的项全部勾上（一个都别漏）；最上面的 「创建桌面快捷方式」勾不勾都行（它只是往桌面放一个图标）—— 英文界面这一页从上到下依次是：

   • 「附加快捷方式」：Create a desktop icon（创建桌面快捷方式）—— 可勾可不勾
   • 「其他」（这一组全部勾上）：
     • Add "Open with Code" action to Windows Explorer file context menu（文件右键菜单）
     • Add "Open with Code" action to Windows Explorer directory context menu（目录右键菜单 —— 和上一条是两个独立的勾）
     • Register Code as an editor for supported file types（关联文件类型）
     • Add to PATH ← 这个本来就必须勾着，别取消（见第 2 步）

   ⚠️ 别去死记"勾前三项" —— 不同小版本这一页的项数和顺序会略有差别。 判断标准只有一条：添加到 PATH 必须勾着、「其他」里的项全部勾上 （只有「创建桌面快捷方式」可勾可不勾）。

   

4. 点「安装」后先是安装进度：

   

   最后是完成页 —— 点「完成(F)」：

   

装插件（6 个）：

1. 打开 VS Code，按 Ctrl + Shift + X —— 左侧会弹出「扩展」面板（图标是四个方块）；

2. 在左侧扩展面板的搜索框里逐个搜下面的名字，找到后点结果行右边的「安装」：

   

3. 装完关掉 VS Code 再打开 —— 重新打开看到的就是欢迎页：

   

怎么确认装齐了：扩展面板左侧有个 「已安装 / INSTALLED」 分组。

⚠️ 点开你会看到 11 个，不是 6 个 —— 这是正常的，别以为多出来的是垃圾：

来源	个数
上面让你装的	6 个
cortex-debug 自动带上的 mcu-debug.* 依赖	+4 个
cpptools 自动带上的 ms-vscode.cpp-devtools	+1 个
合计	11 个

对照检查：只要上面表里那 6 个都在，就装齐了。少哪个再搜一遍装哪个。

code --install-extension ms-vscode.cpptools
code --install-extension ms-vscode.cmake-tools
code --install-extension marus25.cortex-debug
code --install-extension dan-c-underwood.arm
code --install-extension llvm-vs-code-extensions.vscode-clangd
code --install-extension ms-ceintl.vscode-language-pack-zh-hans

1.3 第 3 步：Python 3.12

下载：https://www.python.org/downloads/windows/ → 找 Python 3.12.x 那一栏， 下 Windows installer (64-bit)（文件名形如 python-3.12.x-amd64.exe）。 补丁号不用挑 —— 3.12 里最新的那个就行（本文只约束到 3.12 这个主次版本）。

⚠️ 不要装 3.13+：个别第三方库还没跟上。 ⚠️ 也别下错包：要 Windows installer (64-bit) —— 不要 embeddable package（缺 pip / tkinter）， 也不要 ARM64 版（除非你确定是 ARM 电脑）。

安装：

1. 双击安装包 —— 会先出现一个首屏，先别急着点 Install Now；

2. 第一个界面底部，务必勾上 Add python.exe to PATH ← 不勾后面全是坑：

   

   ⚠️ 首屏底部有两个复选框，另一个是 Use admin privileges when installing py.exe —— 不用勾：它决定安装器要不要用管理员权限把 py.exe（Python 启动器）装给所有用户 （"Customize installation" 页里这一项的原话就是 for all users (requires admin privileges)）。 本文全程只用 python 命令、用不到 py；不勾，整个安装过程连管理员权限都不需要。

3. 点 Install Now（默认装到 %LOCALAPPDATA%\Programs\Python\Python312\；想装到别处就点下面的 Customize installation，装完记住路径）， 接下来是几分钟的安装进度：

   

4. 装完点 Disable path length limit（如果有这个按钮，点它）：

   

   

验证（先重开终端 —— 刚勾的 Add python.exe to PATH 只对新开的终端生效）：

python --version

期望：Python 3.12.x（补丁号不用对 —— 3.12 里哪个补丁都行）

python -c "import tkinter; print(tkinter.TkVersion)"

期望：8.6 ← 这是图形配置界面能不能开的关键。报 ModuleNotFoundError 说明装的时候没勾 tcl/tk and IDLE，重装一次。

where python

期望：第一行是你装的那个 python.exe（默认 %LOCALAPPDATA%\Programs\Python\Python312\python.exe；不能是 …\WindowsApps\…）

C:\Users\<你的用户名>\AppData\Local\Programs\Python\Python312\

1.4 第 4 步：Git（学习阶段可选）

💡 学习阶段用压缩包下发框架，所以不装 Git 也能一路走完（编译、烧录、调试全都行）。 着急开工的话，这一步可以直接跳到 §1.5。

什么时候才真正需要 Git，见 §2.4。这里给出安装方法，想装就照做。

下载：https://git-scm.com/download/win → 选 「64-bit Git for Windows Setup」 （认这个名字就行 —— 版本号不用挑，页面给的就是最新稳定版）

安装：一路 Next，但有 3 个地方要改。

第 1 页 · GPL 许可协议 —— 看完直接点「Next」，这页不用改：

⚠️ 安装向导一共 16 页，要改的那 3 处分别在 第 5、6、7 页。改完这 3 处还没结束 —— 后面还有约 8 页（SSH 可执行文件、HTTPS 后端、换行符、终端模拟器、 git pull 行为、凭据助手、额外选项、实验特性）。

那 8 页全部保持默认，一路 Next 到 Install 就行。 别以为"改完 3 处就可以关窗口了"——那时候还没点 Install。

第 5 页 · 选择默认编辑器 —— 展开下拉框，选 Use Visual Studio Code as Git's default editor：

第 6 页 · 初始分支名 —— 点 Override（下方方框会自动出现 main，不用手输）：

第 7 页 · PATH 环境 —— 保持默认的推荐项就行：

安装中 —— 后面约 8 页全部保持默认，一路 Next 到 Install：

完成页 —— 看到这个就点 Finish：

验证（先重开终端 —— 装 Git 之前就开着的终端不认识 git）：

git --version

期望：git version 2.x（补丁号不用对 —— 装了 2.48、2.50 都是对的）

where git

期望：打印出你装的那个 …\Git\cmd\git.exe（默认 C:\Program Files\Git\cmd\git.exe）—— ⚠️ where 只列路径，不打印版本号。

1.5 第 5 步：CMake

下载：https://cmake.org/download/ → 在 Windows 那一栏找 Windows x64 Installer（.msi，安装版）—— 认这个类型，不用记版本号。 （嫌官网慢也可以走 GitHub Releases，内容一样：https://github.com/Kitware/CMake/releases —— 认文件名以 -windows-x86_64.msi 结尾，别下 .zip 绿色包，也别下 i386 / arm64。）

安装：

1. 双击 .msi → 欢迎页点 Next：

   

2. 接受许可协议 → Next：

   

3. ⚠️ 确认「Add CMake to the PATH environment variable」是勾着的 —— 它默认就是勾上的，不用改；Add CMake shortcut to the Desktop 默认未勾，要不要都行：

   

   

4. 安装路径：默认 C:\Program Files\CMake\，也可以装到别处（记住路径）→ Next → 出现 Ready to install CMake 页再点一次 Install：

   

   安装中：

   

   完成页：

   

装完应该是：

<你的 CMake 安装目录>\bin\cmake.exe        ← 必须有这个
<你的 CMake 安装目录>\share\...

验证（先重开终端）：

cmake --version

期望：cmake version 3.x（认大版本就行）

📌 本文实测的是 CMake 3.31.x；如果官网给的是 4.x，也可以用 —— §1.11 的自检不核对 cmake 版本（只验"环境变量可用"），所以不会再报 [~]。 万一 cmake 配置这一步真的报错，就换回 3.31.x 重装。

where cmake

期望：第一行是你装的那个 …\CMake\bin\cmake.exe（默认 C:\Program Files\CMake\bin\cmake.exe）

⚠️ 如果 where cmake 没输出，说明装的时候没勾「Add CMake to the system PATH」。 跑一遍 §1.10 的脚本就能补上（那段脚本里带了这一条作为兜底）。

1.6 第 6 步：Ninja

下载：https://github.com/ninja-build/ninja/releases → ninja-win.zip

不要下 ninja-win-arm64.zip，除非你是 ARM 电脑。

openocd -f interface/cmsis-dap.cfg -c "cmsis-dap vid_pid 0x04d8 0x00df" -c "init; shutdown"

安装（解压式）：解压得到单独一个 ninja.exe，建目录 C:\Tools\ninja\ 放进去。

第 1 步 · 新建目标目录 —— 在 C:\Tools\ 下新建文件夹 ninja（还没有 C:\Tools\ 就先建它）。

第 2 步 · 用 7-Zip 解压 —— 在下载目录里右键 ninja-win.zip → 7-Zip →「解压到 "ninja-win"」， 再把解出来的 ninja.exe 放进 C:\Tools\ninja\。

💡 想一步到位：右键 → 7-Zip →「解压文件...」，在弹出的对话框里把目标填成 C:\Tools\ninja， 解压和落位一次完成。（认准对话框里的目标路径填对就行。）

⚠️ 7-Zip 那三个菜单项别点错（26.03 中文界面里的实际名字）： 要指定目标目录 → 点「解压文件...」（会弹出一个带目标框的对话框）； 「解压到当前位置」是直接解到当前文件夹（不问你）； 「解压到 "xxx\"」是解到它自己建的同名文件夹。 名字很像 —— 认准带省略号的「解压文件...」。

⚠️ 对话框里如果有一个「解压到 "xxx"」的子文件夹勾（默认是勾着的），把它取消掉 —— 否则会多套一层目录。 拿不准就看解压结果：project.py（或 ninja.exe）直接躺在目标文件夹第一层就对了。

⚠️ 解压首选 7-Zip：右键 ninja-win.zip →「7-Zip」→「解压文件...」， 目标填 C:\Tools\ninja，一步到位（走法和 §2.2 解包代码包一致）。 万一右键没有「7-Zip」子菜单 —— 那是装完还没生效，注销重登一次再看。

第 3 步 · 目标路径 —— 在 7-Zip「解压文件...」对话框的目标框里填 C:\Tools\ninja。

第 4 步 · 确认结果 —— 目录里就一个 ninja.exe，没有多余层级：

C:\Tools\ninja\ninja.exe            ← 必须有这个

验证（先重开终端）：

"C:\Tools\ninja\ninja.exe" --version

期望：能打印出版本号（形如 1.12.1，小版本不用对）

💡 这里为什么用全路径：Ninja 是绿色包，PATH 要到 §1.10 才加 —— 现在还没有。 §1.10 配完 PATH 之后，直接敲 ninja --version 就行（那条同时也是 PATH 检查）。

1.7 第 7 步：LLVM / Clang

下载：https://github.com/llvm/llvm-project/releases 找 LLVM-18.1.8-win64.exe（安装版） 大小：374,335,885 字节（约 357 MB）

安装：

1. 双击 → 欢迎页点 Next（中文向导）：

   

2. 许可页选「我接受(I)」→ Next：

   

3. ⚠️ 改选「Add LLVM to the system PATH for all users」 —— 默认是 Do not add LLVM to the system PATH，不勾后面敲 clang 没反应：

   

4. 安装路径：默认是 C:\Program Files\LLVM\，你也可以装到别的盘（比如 D:\Tools\LLVM\）。 ⚠️ 不管装哪儿，把路径记下来 —— 虽然第 3 步勾了「Add LLVM to the system PATH for all users」， 但万一以后 PATH 里找不到 clang，你得能想起来它装在哪（手动补 PATH 时就要填这个路径）。 路径不能有中文和空格（§1.0 第 1 条）。→ Next：

   

5. 这一页点右下角的「安装(I)」—— 点完才开始真正解压：

   

6. 然后就是漫长的解压（安装包约 2.6 GB，要等几分钟）：

   

7. 看到完成页就点「完成(F)」：

   

装完应该是（<你的 LLVM 安装目录> = 你第 4 步选的那个；默认 C:\Program Files\LLVM\）：

<你的 LLVM 安装目录>\bin\clang.exe        ← 必须有
<你的 LLVM 安装目录>\bin\clang++.exe      ← 必须有
<你的 LLVM 安装目录>\bin\clangd.exe       ← VS Code 跳转要用
<你的 LLVM 安装目录>\lib\clang\18\include\...   ← C++ 标准头文件

验证（先重开终端）：

clang --version

期望（第一行）：clang version 18.1.x —— 红线是 18.1.x（别装 19+），补丁号不用对

where clang

期望：第一行指向你装的那个 …\LLVM\bin\clang.exe（没改路径的话就是 C:\Program Files\LLVM\bin\clang.exe）

✅ 关键验证：clang 要能当 ARM 交叉编译器用

clang --target=arm-none-eabi -c -x c nul -o nul.o

• 没有输出（静默成功）= ✅ 能用；
• 报 error: unknown target triple 'arm-none-eabi' = ❌ 下错包了，重下。

⚠️ 别用 clang++ --target=arm-none-eabi 单独编 C++ 来验证环境 —— 那会报 fatal error: 'cstddef' file not found，是正常的：clang 不知道 ARM 的 libstdc++ 头文件在哪。工程 toolchain.cmake 会用显式 -isystem 喂给它。

真正算数的验证是 §3.4 的工程编译。

1.8 第 8 步：ARM GNU Toolchain

下载：https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads 在 "Windows (x86_64) hosted" 那一栏找：

arm-gnu-toolchain-13.3.rel1-mingw-w64-i686-arm-none-eabi.exe

大小：207,426,408 字节（约 198 MB）

⚠️ 别下错：

• ...-x86_64-arm-none-eabi.tar.xz 是 Linux 版；
• ...-darwin-... 是 macOS 版；
• 带 -aarch64 的是给 ARM 电脑的 Windows。

（另有同版本 .zip 包，297,871,203 字节，解压式，适合脚本化；两者内容一致。）

安装：

1. 双击 .exe —— 先在语言下拉框里选 中文(简体)，点「确定」：

   

   然后是欢迎页：

   

2. 许可页选「我接受(I)」→ Next：

   

3. 安装路径：点一下文本框 → Ctrl+A 全选 → 键入你的安装目录。 默认那串带空格和括号，建议换个干净的（教程示例：C:\Tools\arm-gnu-toolchain）。→ Next：

   

4. 点「安装(I)」：

   

5. 完成页 —— 点「完成(F)」之前，把 Add path to environment variable 勾上（它默认没勾）：

   

   勾了 PATH 就自动配好你这个安装目录下的 bin，§1.10 不用再加这一条。

装完应该是（<你的 ARM 工具链目录> = 你第 3 步键入的那个路径，教程示例是 C:\Tools\arm-gnu-toolchain）：

<你的 ARM 工具链目录>\bin\arm-none-eabi-gcc.exe    ← 必须有
<你的 ARM 工具链目录>\bin\arm-none-eabi-g++.exe
<你的 ARM 工具链目录>\bin\arm-none-eabi-objcopy.exe
<你的 ARM 工具链目录>\arm-none-eabi\include\...              ← newlib 头文件
<你的 ARM 工具链目录>\arm-none-eabi\include\c++\13.3.1\...   ← libstdc++ 头文件

实际落点长这样 —— bin / include / lib / share 和 arm-none-eabi 直接同级：

📌 目录里多一层（如 <你的目录>\arm-gnu-toolchain-13.3.rel1\bin\）也不影响使用 —— 只要 bin 在 PATH 里就行。底下那两条验证命令跑通，就说明装对了。

验证（先重开终端）：

arm-none-eabi-gcc --version

期望（第一行）：

arm-none-eabi-gcc (Arm GNU Toolchain 13.3.Rel1 (Build arm-13.24)) 13.3.1 20240614

💡 这条命令其实一次验证两件事：① 工具链装好了；② 完成页那个 PATH 勾生效了。 报「不是内部或外部命令」= PATH 没配上（先 where arm-none-eabi-gcc 看有没有输出， 没有就回第 5 步确认那个勾）。 📌 不需要写全路径 —— 勾了 Add path to environment variable 之后 PATH 里就有它了； 写全路径反而绕过了 PATH 检查（就算 PATH 没配好也"跑得通"）。

再验证 C++ 标准头文件在不在（这一步很多人会漏）：

Get-ChildItem '<你的 ARM 工具链目录>' -Recurse -Filter cstddef |
  Select-Object -ExpandProperty FullName

期望：打印出 ...\arm-none-eabi\include\c++\13.3.1\cstddef（6,656 字节）。 （<你的 ARM 工具链目录> 就是你第 3 步键入的那个；忘了的话 where arm-none-eabi-gcc 会告诉你它在哪 —— 去掉末尾的 \bin\arm-none-eabi-gcc.exe 就是安装目录。）

⚠️ 注意路径：网上很多教程让你 dir ...\arm-none-eabi\include\cstddef， 但 13.3.rel1 里没有这个路径 —— 它把 C++ 头文件放在 include\c++\<版本>\ 下面。 上面这条 Get-ChildItem -Recurse 才是对的；照抄错的路径会让你误以为装坏了。

1.9 第 9 步：OpenOCD ⚠️ 版本选错会烧不进去

Error: CMSIS-DAP command mismatch. Expected 0x6 received 0x5
Error: Failed to read memory at 0x080024e8

下载 OpenOCD.zip（sysprogs 构建的 0.11.0，22,315,834 字节）—— 快递柜取件页：

1. 打开 http://139.196.220.183:8080/#/?code=YG347
2. 页面上确认取件码是 YG347（链接里已经带上了，一般不用手输）
3. 点页面上的 「下载」 按钮

⏳ 取件页是长期有效的；万一打不开或提示鉴权失败， 重新打开取件页、重新输一次取件码再点下载即可。

拿到包后核对这两条

项	值
bin\openocd.exe	4,245,518 字节
版本自证	openocd --version 第一行必须含 sysprogs/openocd

⚠️ 不要用压缩包大小判断 —— 换个打包方式（多套一层目录、压缩级别不同） 大小就差几百 KB。

安装（解压式）：

1. 新建目录 —— 教程示例 C:\Tools\openocd\，你可以换到别的盘/目录；

2. 用 7-Zip 解压 OpenOCD.zip —— 右键 OpenOCD.zip → 7-Zip →「解压文件...」， 目标直接填你新建的那个目录（下文中统一写成 <你的 OpenOCD 目录>，教程示例 C:\Tools\openocd\。 这个包的顶层就是 bin\ / share\ / drivers\，解出来正好对上）：

   ⚠️ 对话框里如果有一个「解压到 "xxx"」的子文件夹勾（默认是勾着的），把它取消掉 —— 否则会多套一层目录。

拿不准就看解压结果：project.py（或 ninja.exe）直接躺在目标文件夹第一层就对了。

3. 装完应该是（<你的 OpenOCD 目录> = 你新建的那个；注意 bin 和 share 是同级的）：

   

   

<你的 OpenOCD 目录>\bin\openocd.exe                                    ← 必须有
<你的 OpenOCD 目录>\share\openocd\scripts\interface\cmsis-dap.cfg      ← 必须有
<你的 OpenOCD 目录>\share\openocd\scripts\target\stm32h7x.cfg          ← 必须有（mc02）
<你的 OpenOCD 目录>\share\openocd\scripts\target\stm32f4x.cfg          ← 必须有（rm-c）

Can't find interface/cmsis-dap.cfg

openocd -c "echo FOUND=[find interface/cmsis-dap.cfg]" -c shutdown

验证（先重开终端）：

"<你的 OpenOCD 目录>\bin\openocd.exe" --version

💡 这里为什么用全路径：OpenOCD 是绿色包，PATH 要到 §1.10 才加 —— 现在还没有，所以必须写全路径。 §1.10 配完 PATH 之后，直接敲 openocd --version 就行（那条同时也是 PATH 检查）。 期望：

Open On-Chip Debugger 0.11.0 (2021-11-18) [https://github.com/sysprogs/openocd]
Licensed under GNU GPL v2
libusb1 09e75e98b4d9ea7909e8837b7a3f00dda4589dc3
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html

1.10 把所有目录加进 PATH

PATH 是什么：Windows 的「去哪儿找程序」清单。 不把工具目录加进去，你敲 ninja 它会说 「不是内部或外部命令」 —— 这是新生最常撞的一堵墙（原因和解法见 坑 2）。

VS Code 不用手动加 —— 安装版会自动把自己的 bin 写进 PATH（见 §1.2）。

入口有两个，走哪个都行 —— 除了下面第 1 步的 sysdm.cpl， 也可以从「设置 → 系统 → 关于 → 高级系统设置」进：

操作步骤：

1. 按 Win + R，输入 sysdm.cpl，回车 —— 打开「系统属性」；

2. 切到 「高级」 选项卡 → 点右下角 「环境变量(N)…」：

   

3. 在上半部分（写着「<你的用户名> 的用户变量」）里， 单击选中 Path → 点 「编辑(E)…」：

   

   

4. 先看列表里有没有；缺了才点「新建(N)」补上 —— 本文要你手动加的只有两条： Ninja：C:\Tools\ninja、OpenOCD：<你的 OpenOCD 目录>\bin（教程示例 C:\Tools\openocd\bin）， 输完回车确认；两条都加完就够了。 ⚠️ 列表里已经有同名/同目录的那条，就别再加（重复条目只会让后面排查更乱）； 其余 7 个工具不用你加（安装器 / 安装时勾的选项已经加好了，见下面的表）。

   ① 先看当前列表（安装器已经自动加了几条；要加的那条不在里面，才点「新建(N)」）：

   

   ② 出现一条空白行，光标在里面：

   

   ③ 把路径输进去（例：C:\Tools\ninja），回车确认：

   

💡 9 个工具的 PATH：先查有没有，缺了才补

⚠️ 大部分安装器会自动加好，你不用管。真正要你手动加的只有 2 个： Ninja（§1.6）+ OpenOCD（§1.9） —— 都是绿色包，没有安装程序。 其余 7 个：先看环境变量 Path 列表里有没有对应目录 —— 有就别动，也别重复加。

工具	对应目录（先查有没有）	需要手动加吗
7-Zip	（不需要）	❌ 靠右键菜单集成，不依赖 PATH
VS Code	（自动）	❌ 安装器自动加
Python	<你的 Python 安装目录> 和 …\Scripts（默认 %LOCALAPPDATA%\Programs\Python\Python312）	❌ 安装时勾了「Add python.exe to PATH」就自动加（§1.3 第 2 步）
Git	<你的 Git 安装目录>\cmd（默认 C:\Program Files\Git\cmd）	❌ 安装器自动加
CMake	<你的 CMake 安装目录>\bin（默认 C:\Program Files\CMake\bin）	❌ 安装时勾了「Add CMake to the PATH」就自动加（§1.5）
Ninja	C:\Tools\ninja	✅ 必须手动加 —— 绿色包，没有安装程序
LLVM	<你的 LLVM 安装目录>\bin（默认 C:\Program Files\LLVM\bin）	❌ 选了 for all users 就自动进系统 PATH —— 用户 Path 列表里没有它是正常的
ARM 工具链	<你的 ARM 工具链目录>\bin（教程示例 C:\Tools\arm-gnu-toolchain\bin）	❌ 完成页勾了「Add path to environment variable」就自动进用户 Path（§1.8）
OpenOCD	<你的 OpenOCD 目录>\bin（教程示例 C:\Tools\openocd\bin）	✅ 必须手动加 —— 绿色包，没有安装程序

真正要你动手的只有 2 条：Ninja（§1.6）+ OpenOCD（§1.9） —— 都是绿色包，没有安装程序， PATH 只能自己加（加法见上面第 4 步）。其余 7 个都自动加好了（Python / CMake / VS Code 看安装时的勾选， Git 安装器自动加，LLVM 写进系统 PATH、ARM 写进用户 Path）。

「扫一眼有没有」具体怎么看 —— 在环境变量窗口里对着列表看有没有上面那一列的目录； 或者在终端里直接问：

复制

where.exe git & where.exe cmake & where.exe clang & where.exe python & where.exe arm-none-eabi-gcc & where.exe openocd

有输出的就是已经在 PATH 里了 —— 不用管；哪一条报「找不到文件」就补哪一条。 ⚠️ 这一行是 cmd 的写法：PowerShell 里 where 是 Where-Object 的别名（敲了什么都不显示）， 要用 where.exe（上面就是），或者把 & 拆成一行一条。

⚠️ 补的时候只加缺的那条，别照抄一堆 —— 加重复条目会让 Path 里出现两条一模一样的 ARM 条目，后面排查时很难看出哪条是哪来的。

📌 这张表就是 §0.2 说的那 10 件工具（Git 在里面；7-Zip 也在，只是它不靠 PATH）。 Ozone / J-Link 不在表里 —— 它是图形界面工具， 安装器自己搞定调用方式，不需要加 PATH（见第 5 章）。

5. 一路点 「确定」 关掉所有窗口 —— 三层都要点（编辑框 → 环境变量 → 系统属性）， 少点一层就不保存。加完之后列表里能看到新加的路径：

   

6. 把已经打开的终端和 VS Code 全部关掉重开 —— 这一步不能省，PATH 只在程序启动那一刻读一次（见坑 2）。

怎么确认加对了：重新打开一个终端，敲：

ninja --version

有版本号输出就对了。 还是「不是内部或外部命令」→ 回第 6 步， 确认 VS Code 已经从任务管理器里彻底退出了。

# 先探测每个工具装在哪，再把"实际存在"的目录加进 PATH（只写用户变量，不需要管理员）
$ErrorActionPreference = 'SilentlyContinue'

# 显示名 / 命令名 / 可执行文件名 / 候选目录（按顺序找）
$tools = @(
  @{ N='Git';     C='git';               E='git.exe';               D=@("$env:ProgramFiles\Git\cmd", "${env:ProgramFiles(x86)}\Git\cmd") },
  @{ N='CMake';   C='cmake';             E='cmake.exe';             D=@("$env:ProgramFiles\CMake\bin") },
  @{ N='LLVM';    C='clang';             E='clang.exe';             D=@("$env:ProgramFiles\LLVM\bin") },
  @{ N='Python';  C='python';            E='python.exe';            D=@("$env:LOCALAPPDATA\Programs\Python\Python312") },
  @{ N='VS Code'; C='code';              E='code.cmd';              D=@("$env:LOCALAPPDATA\Programs\Microsoft VS Code\bin") },
  @{ N='Ninja';   C='ninja';             E='ninja.exe';             D=@('C:\Tools\ninja') },
  @{ N='OpenOCD'; C='openocd';           E='openocd.exe';           D=@('C:\Tools\openocd\bin') },
  @{ N='ARM';     C='arm-none-eabi-gcc'; E='arm-none-eabi-gcc.exe'; D=@('C:\Tools\arm-gnu-toolchain\bin') }
)

# 读注册表里的现有 PATH（用户 + 系统）—— 即使当前终端是旧的，也能正确判断"有没有"
function Get-PathList($scope) {
  if ($scope -eq 'User') { $v = (Get-ItemProperty 'HKCU:\Environment' -Name Path).Path }
  else { $v = (Get-ItemProperty 'HKLM:\SYSTEM\CurrentControlSet\Control\Session Manager\Environment' -Name Path).Path }
  if (-not $v) { return @() }
  return @($v -split ';' | Where-Object { $_.Trim() -ne '' } | ForEach-Object { $_.Trim().TrimEnd('\') })
}
$userList = Get-PathList 'User'
$all = $userList + (Get-PathList 'Machine')
$add = New-Object System.Collections.ArrayList

foreach ($t in $tools) {
  $found = $null
  foreach ($d in $t.D) { if (Test-Path (Join-Path $d $t.E)) { $found = $d.TrimEnd('\'); break } }
  if (-not $found) {
    if (Get-Command $t.C -ErrorAction SilentlyContinue) { "[{0,-7}] 已在 PATH（装在别处），无需处理" -f $t.N }
    else { "[{0,-7}] 没找到，请手动确认装在哪" -f $t.N }
    continue
  }
  if ($all -contains $found) { "[{0,-7}] 已在 PATH：{1}" -f $t.N, $found; continue }
  [void]$add.Add($found)
  "[{0,-7}] 已添加：{1}" -f $t.N, $found
  if ($t.N -eq 'Python') {                                  # Python 还要 Scripts
    $sc = Join-Path $found 'Scripts'
    if ((Test-Path $sc) -and ($all -notcontains $sc)) { [void]$add.Add($sc); "[Python ] 已添加：$sc" }
  }
}

if ($add.Count -eq 0) { "PATH 无需改动（探测到的目录都已经在 PATH 里）。" }
else {
  $merged = @($userList)
  foreach ($d in $add) { if ($merged -notcontains $d) { $merged += $d } }
  [Environment]::SetEnvironmentVariable('Path', ($merged -join ';'), 'User')
  "已写入用户变量 Path：新增 $($add.Count) 条。"
}

# 顺手把 OpenOCD 的脚本目录显式告诉它（§1.9 提过的兜底）
$ocd = @($add) + @($userList) | Where-Object { $_ -like '*openocd*' } | Select-Object -First 1
if ($ocd) {
  $root = if ($ocd -like '*\bin') { Split-Path $ocd -Parent } else { $ocd }
  [Environment]::SetEnvironmentVariable('OPENOCD_SCRIPTS', (Join-Path $root 'share\openocd\scripts'), 'User')
}

"请【完全关闭】终端 / VS Code 再重新打开，PATH 才会生效。"

💡 Python 如果装在别处（比如自己改过路径）：不用手改脚本 —— 它的候选目录里已经带了 %LOCALAPPDATA%\Programs\Python\Python312；实在探测不到会明确报「没找到，请手动确认装在哪」。

1.11 全环境自检（装完必做）

🖱 最省事的做法：双击一个脚本，它替你全查完

下载 RowletBot-环境验证.zip（1,939 字节）—— 快递柜取件页：

1. 打开 http://139.196.220.183:8080/#/?code=9LESD
2. 页面上确认取件码是 9LESD（链接里已经带上了，一般不用手输）
3. 点页面上的 「下载」 按钮

⏳ 取件页是长期有效的；万一打不开或提示鉴权失败， 重新打开取件页、重新输一次取件码再点下载即可。 （拿到 zip 后用 7-Zip 解压，得到 1 个 .bat。）

双击 5-check.bat（放哪都行，它不依赖仓库）。 约 20 秒后你会看到逐项判定 —— 10 件工具里，自检脚本只查 8 件 （不含 7-Zip 和 Ozone：一个只管解压、一个是调试工具，都不影响编译和烧录）。 这 8 件里只有 3 件有硬版本要求（openocd / arm-none-eabi-gcc / clang）—— 脚本对它们核对版本；其余 5 件只验"命令能不能跑、环境变量可不可用"，不看版本：

复制

  git                [OK] 环境变量可用
  python             [?] 取不到版本          ← 指向了微软商店的占位程序（见坑 3）
  ninja              [OK] 环境变量可用  [已确认在 PATH]
  openocd            [~] 版本不对，期望含 0.11.0  [已确认在 PATH]
  ...
  [有 3 项没通过] 往上翻看是哪几个…

判定符号：[OK] 通过 · [~] 版本不对 · [?] 取不到版本 · [X] 没装或不在 PATH。

📌 ninja / openocd 行尾多的 [已确认在 PATH]：脚本对这两件额外验了一步 —— 拿 where 找到的绝对路径再跑一次 --version，跑得通才算 PATH 真的可用 （上面 位置： 那行打印的就是它实际用的那个文件）。

📌 出现 [?] 时别急着重装：先用下面第 1/2 组的命令手工复核一遍 —— 手工能出结果，就说明环境没问题，是脚本没抓到（例如 OpenOCD 把版本打到 stderr，不是没装）； 手工也出不来，才回对应小节重装或修 PATH。

📌 [~] 版本不对 怎么读：现在只有那 3 件（openocd / arm-none-eabi-gcc / clang）可能报它 —— 它们正是 §1.0 第 2 条里既靠 PATH、又有硬版本红线的那三个。 看到 [~] = 真装错版本了，按 §1.0 第 2 条回对应小节换版本 （脚本提示的「版本红线见教程 1.0 第 2 条」说的就是这件事）。 其余工具（git / python / cmake / ninja / code）根本不会再报 [~] —— 它们只报 [OK] 环境变量可用 / [?] / [X]，所以不用再纠结"我装的版本是不是和教程写的不一样"。

📌 Ozone 的版本为什么不在这儿查：它不靠 PATH（本来就不在这 8 件里），脚本抓不到它 —— Ozone 3.24（32 位）+ J-Link 7.22b 这条红线只能手动核对，见 §5.1。

📌 [X] 没装 / 不在 PATH 里的 git 也可以忽略： Git 是可选件（§1.4 / §2.4 —— 压缩包路线不需要它），没装时就是这一项报 [X]， 最后那句「[有 N 项没通过]」里把 git 减掉再看。

它还会把结果写成 env-check-report.txt —— 在群里问问题时把这个文件的内容贴上去，别人一眼就能看出你哪儿不对， 不用来回问三遍。

全部通过的输出长这样 —— 10 件工具里它只查 8 件（不含 7-Zip 和 Ozone）， 这 8 件逐项 [OK]：openocd / arm-none-eabi-gcc / clang 这三件是 [OK] 版本正确， 其余 5 件是 [OK] 环境变量可用，后面各自跟一行 位置：（ninja / openocd 还多一个 [已确认在 PATH]）：

下面是它查的内容 —— 想手动核对时展开：

git --version
python --version
cmake --version
ninja --version
clang --version
arm-none-eabi-gcc --version
openocd --version

where git
where python
where cmake
where ninja
where clang
where clangd
where arm-none-eabi-gcc
where openocd
where code

C:\Program Files\Git\cmd\git.exe
%LOCALAPPDATA%\Programs\Python\Python312\python.exe       ← 不能是 ...\WindowsApps\python.exe
C:\Program Files\CMake\bin\cmake.exe
C:\Tools\ninja\ninja.exe
C:\Program Files\LLVM\bin\clang.exe
C:\Program Files\LLVM\bin\clangd.exe
C:\Tools\arm-gnu-toolchain\bin\arm-none-eabi-gcc.exe
C:\Tools\openocd\bin\openocd.exe
...\Microsoft VS Code\bin\code.cmd

python -c "import tkinter; print(tkinter.TkVersion)"

clang --target=arm-none-eabi -c -x c nul -o nul.o

openocd -c "echo OK=[find target/stm32h7x.cfg]" -c shutdown

第 2 章 拿代码（学习阶段用压缩包）

📖 本章导读

• 做什么：把学长给的压缩包解开，放到一个不会出问题的路径
• 需要：框架压缩包、约 5 GB 空闲磁盘
• 做完的标志：解压出来的 project.py / src\ / hw\ / build_script.bat 都在（§2.5）

💡 学习阶段不用 GitHub、不用 git clone —— 压缩包解压就能用，子模块已经打包在内。

2.1 学习阶段的框架来源：压缩包

战队对学习阶段的新生不下发 git 权限，统一用压缩包发放框架。

也就是说：你不需要 GitHub 账号，也不需要 git clone。 学长会给你一个打包好的压缩包，解压就能编译。

这样做有几个好处：

常见的包名（具体以学长给你的为准）：

RowletBot-<日期>.tar.gz
RowletBot-<日期>.zip

📌 什么时候才需要 Git？ 见 §2.4 —— 学习阶段不用， 等你要参与开发、提交代码的时候再配。

2.2 解包（照做）

第一步：先决定放哪

• ✅ 好：%USERPROFILE%\Desktop\RowletBot、D:\RowletBot
• ❌ 坏：C:\Users\张三\桌面\我的代码\RowletBot（中文）、 C:\Program Files\RowletBot（空格 + 权限问题）

⚠️ 铁律 1：路径里不能有中文和空格，否则后面 CMake / Ninja 会报一堆看不懂的错。

第二步：用 7-Zip 解包

先新建一个文件夹放代码 —— 在桌面空白处 右键 → 新建 → 文件夹， 名字改成 RowletBot。

然后解压（全部走 7-Zip，右键就行）：

⚠️ 对话框里如果有一个「解压到 "xxx"」的子文件夹勾（默认是勾着的），把它取消掉 —— 否则会多套一层目录。 拿不准就看解压结果：project.py（或 ninja.exe）直接躺在目标文件夹第一层就对了。

⚠️ 解压完一定要看一眼文件夹里面。 有些包解开后会多套一层同名目录，变成 RowletBot\RowletBot\project.py。 判断标准：project.py 必须直接躺在 RowletBot 文件夹的第一层。 如果多了一层，进去把里层的东西全选剪切，粘贴到外层。

cd /d "%USERPROFILE%\Desktop"
mkdir RowletBot
tar -xzf .\RowletBot-<日期>.tar.gz -C .\RowletBot

第三步：确认解压对了（在资源管理器里看）

打开 RowletBot 文件夹，应该直接看到：

💡 看不到 .vscode 文件夹？ 那是正常的 —— 以 . 开头的文件夹默认隐藏。 在资源管理器里点 「查看」→ 勾上「隐藏的项目」 就能看到。

dir project.py
dir src\robot
dir hw\bsp
dir lib
dir utils

2.3 压缩包里已经包含子模块，不用跑 git submodule

lib\ 和 hw\mcu\st\ 下面有些目录不属于本仓库，而是从别的 GitHub 仓库「挂」进来的， 这种机制叫 git submodule（子模块）。用 git clone 拉的话它们是空的，必须再跑一次 git submodule update --init。

✅ 但你用的是压缩包 —— 打包的时候已经把这 5 个目录的真实文件都放进去了， 所以这一步完全不用做。

2.4 关于 Git（学习阶段用不到，但不是没用）

学习阶段你完全可以不装 Git —— 压缩包解压就能编译、能烧录、能改代码。

那什么时候需要它？

git --version
where git

git init
git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"
git config --global core.autocrlf false
git add -A
git commit -m "导入框架压缩包"

ssh-keygen -t ed25519 -C "你的邮箱@example.com"

type %USERPROFILE%\.ssh\id_ed25519.pub

ssh -T [email protected]

Hi <你的用户名>! You've successfully authenticated, but GitHub does not provide shell access.

cd /d "%USERPROFILE%\Desktop"

REM 方式 A（SSH key）—— 地址以 [email protected]: 开头
git clone -b dev [email protected]:Birdiebot2025/RowletBot.git RowletBot

REM 方式 B（PAT）—— 地址是 https:// ，会弹凭据窗口
git clone -b dev https://github.com/Birdiebot2025/RowletBot.git RowletBot

cd RowletBot
git submodule update --init      REM ⚠️ 走 git 路线才需要这一步

第 3 章 编第一个固件：改一行 → 看变化

📖 本章导读

• 做什么：编出第一个固件，看到 [N/N] + 内存占用表、没有红色 failed:（§3.4）
• 需要：第 1、2 章都走完了
• 做完的标志：dir build\xrobot.bin 有文件

📌 本章只要三步：§3.2 用 python ./project.py config 选目标 → §3.4 在 VS Code 里跑 build 任务 → §3.5 看产物。

🎯 这一章的目标

让板子上的 LED 闪起来，然后改一个数字让它闪得不一样， 重新烧进去，亲眼看到它变了。

本文用的目标：rm-c + ex1_led（§3.2 里选它）—— 只闪灯、不驱动任何电机，所以直接烧就行，不用架车、也不用拔电机线。 （只有换成会驱动电机的目标，比如 26-Omni_Infantry，才需要先把车架起来。）

3.1 先认识一个词：目标（target）

一个目标 = 一块板子 + 一个 robot 程序。

• rm-c 是板子；ex1_led 是跑在它上面的 robot 程序（本文全程用它当例子）。
• 同一个 robot 名字在不同板子上可能是两份不同的配置。
• 所以编译前必须先确定「这块板子 + 这个 robot」 —— 在 §3.2 的配置窗口里选一次（Save），之后的重编就按这个组合走（换目标 = 回配置窗口改 + Save，见 §3.4）。

3.2 打开配置窗口，选板子和 robot

这是全程唯一的"配置"动作 —— 选完之后，编译和烧录都跟着这个选择走。

1. 在 VS Code 集成终端里跑（确认目录是仓库根，提示符末尾是 \RowletBot>）：

   复制

   python ./project.py config
   

   → 弹出 Main menu 配置窗口。

2. 展开「开发板 (board-…)」 → 点 board-rm-c 那行最左边的小圆圈（见图 3-1）。

3. 展开「机器人 (robot-…)」 → 点 robot-ex1_led 那行最左边的小圆圈（见图 3-1）

   ⚠️ 点名字只会把那一行变蓝（高亮），不算选中 —— 必须点最左边那个小圆圈。 不确定有没有点上：看窗口底部的 Choice symbols: 几行，带 (selected) 的才生效。

4. 点 Save → 关掉窗口（本工具没有 Exit 按钮，点右上角 X 或 Alt + F4）。 config_cmake() 要等窗口关掉之后才跑，build\build.ninja 这时才生成 —— 黑窗口刷完出现 Build files have been written to 就说明配置好了。

📌 树上只有「开发板」和「机器人」必须各选一个（决定编"哪块板子的哪个 robot"）； 系统 / 组件 / 设备 / 模块 是更细的开关，目标配置里已经配好了，本文流程不用动。

⚠️ 第一次必须走这一步：它顺带把 CMake 配置好，跳过它直接编译会报 ninja: error: loading 'build.ninja'（见坑 20）。

💡 本文全程用 rm-c + ex1_led —— ex1_led 只闪灯、不驱动电机，直接烧就行、 不用架车也不用拔电机线；换成会驱动电机的目标（如 26-Omni_Infantry）才要架车或拔电机线再烧。 ⚠️ 但窗口里有什么才是准的（见坑 21）—— 别背本文的例子。

3.3 打开文件、找到要改的那一行

用 VS Code 打开整个仓库文件夹（File → Open Folder，不是打开单个文件）， 然后打开 src\robot\ex1_led\robot.cpp —— 这是这个 robot 的主程序。

要找的是「改一个数字就能看出差别」的地方，最常见的是这两类：

• 延时：形如 System::Delay(500)、Thread::Sleep(1000) 里的毫秒数；
• 速度 / 系数：形如 SetSpeed(...)、* 0.5、PID 的那一组参数。

用 Ctrl + F 搜 Delay 或 Speed，挑一处改一个数字（比如把 500 改成 1000）， 按 Ctrl + S 保存。

💡 改完看不出差别？ 换一处再试 —— 不同目标里「看得出差别」的参数不一样。 只要能编过、能烧进去，这一章的目的（走通流程）就已经达到了。

3.4 编译（第一次）

编译 = 先在 §3.2 的配置窗口里定好目标，再跑 VS Code 的 build 任务 —— 在 VS Code 里打开仓库，跑任务 build（定义在 .vscode\tasks.json）：

• Ctrl + Shift + P → 输入 Run Task → 选 build ← 最稳，一定可用；
• 菜单 终端 → 运行任务… → 选 build（图 3-2、图 3-3）；
• Ctrl + Shift + B —— ⚠️ 本仓库没设成"默认生成任务"，按下去可能先弹任务列表，选 build 即可。

成功的样子：最后一行是 [N/N]（objcopy 那两步：xrobot.bin / .hex），紧跟着一张内存占用表 （Memory region / Used Size / Region Size / %age Used —— 图 3-4），全程没有红色的 failed:。

失败：结尾是红色的 failed: ninja exited with 1. → 别慌，去第 7 章按报错关键字查。

⚠️ 顺序：先 §3.2 配置窗口，再跑 build。反过来会报 ninja: error: loading 'build.ninja': The system cannot find the file specified.（见坑 20）。

💡 换板子 / 换 robot：回 §3.2 改一次 + Save，再跑 build —— 编出来的就是新目标。 只想重编一次（改完代码）：双击 build_script.bat —— 快、沿用上次目标，但只 ninja、不配置也不归档。 ⚠️ 别用 build_script.bat <板> <目标> 这种写法：本文这版脚本忽略参数（坑 20）。

📌 想编 Release 版（一般用不到，上板一律用默认 Debug）：python project.py build-release rm-c ex1_led。

3.5 产物在哪：build\ 里的那五个文件

编译成功后，产物都在 build\ 里（正常流程）：

第 4 章 烧录

📖 本章导读

• 做什么：把固件烧进板子，并确认它真的在跑
• 需要：调试器 + 4 根烧录线 + 给板子供电
• 做完的标志：看到 wrote N bytes ... + shutdown command invoked（§4.5）

⚠️ 本章有一条"能救你的车"的规矩：烧错目标不会报错，只会安静地烧进去。 所以顺序是 接线 → 确认调试器 → 烧录 → 看现象，一步都别省。

📌 本文只保留 §1.11 的环境自检脚本（5-check.bat），不再附带探测 / 备份的助手脚本 —— 需要探测芯片或备份板子里的固件时用命令行，两条命令都在第 7 章： 探测见坑 23，备份 / 还原见坑 26。

⚠️ 烧错目标不会报错

build\xrobot.bin 是共享路径、0x08000000 对所有 STM32 都成立 —— 所以烧错目标只会安静地写进一份错误的固件。 把驱动电机的固件烧到真车上可能直接飞车，所以下面几步一步都别省。

4.1 你手上可能是哪一种下载器

4.2 接线（4 根线，一根都不能错）

接反/接错通常表现为「设备管理器里能看到调试器，但 openocd 探测不到芯片」。

⚠️ 烧录之前：先让轮子悬空

本文用的 ex1_led 只闪灯（不驱动电机）—— 不会动。换成会驱动电机的目标时，烧进去之后程序一跑，轮子就可能转。 第一次烧录前做一件事（二选一）：

• 把车架起来，让四个轮子离地空转；
• 或者拔掉电机线（只烧程序、不接电机）。

这样即使程序写错、上电就全速转，车也不会冲出去撞坏东西。

4.3 确认电脑认出了调试器

把调试器插进 USB 口，等 2~3 秒。

设备管理器里看：应该出现 3 个相关设备，分在 3 个节点下 —— 所以这三个节点都要展开：「端口 (COM 和 LPT)」、「通用串行总线控制器」、「人机接口设备」 （有的系统把最后一个显示成「人体学输入设备」，是同一个节点）。

🔎 第三个（「人机接口设备」里的那个）是关键 —— 少了它，openocd 必然连不上。 有黄色感叹号：右键 → 卸载设备 → 拔插一次，让 Windows 重装驱动。 认不出是哪个设备时，点开设备 →「详细信息」→「硬件 ID」，看有没有 VID_04D8&PID_00DF。

烧录前必须关掉所有可能占用调试器的程序：VS Code 的调试会话、其它 openocd 窗口、Keil / IAR。

4.4 烧录（VS Code 运行任务 download_dap）

这是唯一会写板子的一步。

在 VS Code 里运行任务 download_dap（入口和 §3.4 跑 build 任务完全一样）：

• 菜单 终端 → 运行任务… → 选 download_dap。

它干的事就一行 —— 先编译，再用 openocd 烧：

build_script.bat && openocd -f toolchain/openocd_dap.cfg -c init -c halt -c "reset halt; wait_halt;flash write_image erase build/xrobot.bin 0x08000000" -c reset -c shutdown

拆开看：

⚠️ 它没有确认环节 —— 任务一跑就开始烧，不会问你 y。 所以烧之前先探一下板子：按坑 23 那条命令确认探到的芯片（Device: 那行）就是你手上这块板。

📌 toolchain\openocd_dap.cfg 是"最后一次配置的那块板"的共享副本（§3.2 配置时拷过来的）—— 单块板子开发时它就是对的（你刚在 §3.2 配过）；换过板子、又不确定它指向哪颗芯片时， 先 type toolchain\openocd_dap.cfg 看最后一行 target，或按坑 23 先探一次。

⚠️ 唯一要留意的：build_script.bat 那一步失败时脚本不一定停（老版返回码恒 0，见坑 20） —— 编译输出里有红色 failed: 就别往下烧。

烧录成功的输出（openocd 写完 + 脚本结尾）：

wrote 338016 bytes from file build/xrobot.bin in 7.540754s (43.775 KiB/s)
shutdown command invoked

  烧录完成，板子已复位。

4.5 烧录成功的样子 & 板子上的现象

成功输出（关键几行）：

wrote 338016 bytes from file build/xrobot.bin in 7.540754s (43.775 KiB/s)
shutdown command invoked

退出码 0。

板子上的现象：

⚠️ 会驱动发射机构、拨弹轮的 robot（名字带 Hero / Infantry / shoot 的）， 测试前务必确认机构周围无人、无弹。

最后一步，也是最重要的一步：

改一行代码 → build_script.bat → 重新烧录 → 现象变了 🎉

第 5 章 Ozone + J-Link

做完第 1~4 章再回来装这一章 —— 调试、断点、看变量、变量曲线都靠它。 （基础编译 / 烧录环境不依赖它，所以它排在第 4 章「烧录」之后。）

5.1 ⚠️ 版本是唯一的重点：Ozone 3.24（32 位）+ J-Link 7.22b

🚫 不要装最新版 Ozone。 新版 Ozone（V3.40 以后）走的是「OpenOCD GDB server 中转」的路子， 和这里「Ozone 直连探针」完全不是一种用法：配置界面、连接方式、能用的功能都不一样， 换成新版反而更麻烦（新版走 GDB server 中转，曲线功能也用不了）。

装 3.24 32 位就对了。

5.2 下载：「Ozone + J-Link 必装包」

下载 RowletBot-Ozone+JLink-必装包.zip —— 87,190,628 字节（83.2 MB） —— 快递柜取件页：

1. 打开 http://139.196.220.183:8080/#/?code=0MAW5
2. 页面上确认取件码是 0MAW5（链接里已经带上了，一般不用手输）
3. 点页面上的 「下载」 按钮

⏳ 取件页是长期有效的；万一打不开或提示鉴权失败， 重新打开取件页、重新输一次取件码再点下载即可。 这一步要用的东西全在这一个包里。

包里 4 个文件（字节数可用来核对下载是否完整）：

💡 这一步只用这一个包就够了 —— 包里那份 JLinkARM.dll 是改过的，官网下不到。

5.3 安装顺序：先装 Ozone，再装 J-Link

① 安装 Ozone

1. 双击 Ozone_Windows_V324_x86.exe —— 欢迎页点 Next：

   

2. 许可页点 I Agree：

   

3. ⚠️ 这一步注意选择 install a new instance（安装一个新的实例）； 组件 / 目标目录 / 用户范围都保持默认即可：

4. 后续一路确认，看到完成页就结束：

   

② 安装 J-Link

1. 双击 JLink_Windows_V722b.exe；
2. ⚠️ Update DLL in other applications 默认是勾着的，要手动取消勾选 —— 否则 J-Link 会把 Ozone 里那套老的驱动和启动项替换掉；
3. choose destination 和 Ozone 一样，选 install a new instance；
4. 如果已经装过相同版本的 J-Link，先卸载；版本相同不用管，直接新装一个。

默认安装位置（32 位程序，在 Program Files (x86) 下）：

C:\Program Files (x86)\SEGGER\Ozone V3.24\Ozone.exe
C:\Program Files (x86)\SEGGER\JLink_V722b\

⚠️ 目录名里带版本号（因为上面选的是 install a new instance）—— 以你机器上实际的名字为准。

③ 必做：替换 JLinkARM.dll

✅ 把包里的 JLinkARM.dll 覆盖到两个安装目录

包里那份是改过的，用来绕过 SEGGER 对克隆调试器的检测 —— 不覆盖的话，J-Link OB / 克隆版 J-Link / 部分 DAP-Link 会反复弹 clone version 之类的提示，甚至连不上。

怎么找这两个目录：打开 C:\Program Files (x86)\SEGGER\ —— 里面就是两个文件夹， 一个是 J-Link、一个是 Ozone。⚠️ 目录名带版本号（因为选的是 install a new instance）：

复制

C:\Program Files (x86)\SEGGER\JLink_V722b\      ← J-Link 安装目录
C:\Program Files (x86)\SEGGER\Ozone V3.24\      ← Ozone 安装目录

以你机器上实际的名字为准（版本号不同，名字就不同）。 每个文件夹里都有一个 JLinkARM.dll（约 18 MB）—— 两个都要覆盖。

怎么做：把包里那个 JLinkARM.dll 复制一份 → 分别进上面两个目录 → 粘贴 → 提示「替换目标中的文件？」时，点 「替换目标中的文件」。 ⚠️ 往 C:\Program Files 下复制会弹权限提示（「你需要提供管理员权限才能复制到此文件夹」）—— 点 「继续」 即可。 （想稳妥点：覆盖前把原文件改名成 JLinkARM.dll.bak 备份，要还原时改回来。）

⚠️ 以后如果又装了别的版本的 J-Link，千万不要勾 Update DLL in other applications —— 那会把这份 DLL 覆盖回去，等于白替换（要重新覆盖一次）。

验证：双击 Ozone 图标，能看到 SEGGER 的启动界面（New Project Wizard）就对了。

第一次启动会先弹一个 J-Link 使用条款，点 Accept 才能进去：

进去之后就是 Ozone 主界面（New Project 向导）：

也可以看一眼版本号（应该显示 3.24 / FileVersion 3.2.4.0）：

(Get-Item 'C:\Program Files (x86)\SEGGER\Ozone V3.24\Ozone.exe').VersionInfo.FileVersion

5.4 ⚠️ 两个已知的启动失败

📌 注意位数：如果你装的是新版 64 位 Ozone，缺运行库时要装的是 vc_redist.x64.exe。3.24 是 32 位，装 x86 那个。

第 6 章 VS Code 配置

📖 本章导读

• 做什么：让 VS Code 能跳转定义、能在线调试
• 需要：§1.2 已装好 VS Code 和那 6 个插件；已成功编译过一次
• 做完的标志：在 .cpp 里按 F12 能跳到定义

💡 clangd 和 cpptools 会抢跳转 —— 本章 §6.1 说了怎么二选一。

6.1 插件

§1.2 已经装过。检查：

code --list-extensions

应该包含：ms-vscode.cpptools、ms-vscode.cmake-tools、 marus25.cortex-debug、dan-c-underwood.arm、 llvm-vs-code-extensions.vscode-clangd、ms-ceintl.vscode-language-pack-zh-hans。

💡 clangd 和 cpptools 会打架：两个都想做代码跳转。 建议只留一个：要么禁用 ms-vscode.cpptools 的 IntelliSense，要么禁用 clangd。 本框架工程自带 .clangd 配置，推荐用 clangd。

6.2 用 File → Open Folder 打开仓库

不是打开单个文件 —— 否则 .clangd、.vscode 里的配置都不生效，跳转全废。

6.3 代码跳转（F12）

前提：build\compile_commands.json 存在（第一次完整编译之后就有了）。

dir build\compile_commands.json
where clangd

两个都有输出，然后在 .cpp 里按 F12 应该能跳到定义。 如果不跳：Ctrl+Shift+P → clangd: Restart language server。

6.4 在线调试（cortex-debug）

.vscode\launch.json 是完整编译时从 hw\bsp\<板>\debug\launch.json 拷过来的（每次编译都会刷新，所以不要直接改 build\ 或 .vscode\ 里的那份， 要改就改 hw\bsp\<板>\debug\launch.json）。

⚠️ 先改 .vscode\settings.json 里的三条路径

为什么：仓库模板里这三条指向的是队友电脑上的目录（D:\softwarerm\...）—— 你机器上根本没有这个目录，一按 F5 就报「找不到 openocd / gdb」。

改哪儿：用 VS Code 打开仓库根目录下的 .vscode\settings.json，找到这三行（原文就是这样）：

    "cortex-debug.openocdPath": "D:\\softwarerm\\OpenOCD\\bin\\openocd.exe",
    "cortex-debug.armToolchainPath": "D:\\softwarerm\\gcc-arm-none-eabi-10.3-2021.10-win32\\Arm-GNU-Toolchian\\bin",
    "cortex-debug.JLinkGDBServerPath": "D:\\softwarerm\\SEGGER\\JLinkGDBServerCL.exe",

改成什么（用你自己机器上的真实路径）：

⚠️ JSON 里反斜杠要写两个：C:\Tools\openocd\bin\openocd.exe 在 json 里必须写成 "C:\\Tools\\openocd\\bin\\openocd.exe"。

💡 文件上面还有一组被 /* */ 注释掉的（用的是 C:\Program Files\...）—— 那是队友的参考示例， 别删；你可以照它的格式改下面那三行。 📌 那组注释里的 Arm-GNU-Toolchian 是原文的拼写（少了个 i）—— 照抄时别被它带偏：路径要以你自己机器上实际的目录名为准。

📌 改完按 Ctrl + S 存盘即可，不用重开 VS Code。

⚠️ servertype 要和你的调试器对上：模板里可能写的是 "servertype": "jlink"。

你的调试器	servertype	configFiles
J-Link	jlink	留空即可
DAP-Link / ATK 无线调试器	openocd	hw\bsp\<板>\debug\openocd_dap.cfg

对不上的表现：按 F5 后一直连不上，或者 GDB server 根本起不来。

⚠️ 调试器同一时刻只能被一个程序占用。 用 Ozone 调试时，先关掉 VS Code 的调试会话；反过来也一样。

调试流程：

1. 先确认没有别的程序占用调试器（关掉其它 openocd / 上位机）；
2. VS Code 里按 F5；
3. cortex-debug 会自己起 openocd、烧录、停在 main。

6.5 看外设寄存器（SVD）

hw\bsp\<板>\debug\launch.json 里的 svdFile 指向 lib\cmsis_svd\data\STMicro\...。 这个目录编译时零引用，但别删 —— 看外设寄存器就靠它，删了调试时就没有寄存器视图。

6.6 VS Code 常用快捷键

更多快捷键按 Ctrl+K 再按 Ctrl+S 查看，并且可以改成你最习惯的方式。 补全和 snippet 都用 Tab 接受提议，↑/↓ 切换。

第 7 章 故障字典

📖 本章导读

• 做什么：查错。这章不是用来顺序读的
• 需要：一条具体的报错信息（越完整越好）
• 用法：按报错现象在本章搜关键字。

💡 查错三步：① 看清报错最后 20 行 → ② 在本章搜关键字 → ③ 还是不行就贴出来问， 附上 §1.11 的版本号。

用法：出问题先来这里按现象查。

🔑 先做一次分类：是环境问题，还是代码问题？

这一步能帮你跳过 80% 的无用重装。 对不上号再往下按现象查。

你看到的现象	判断	去哪儿
有的目标编得过、有的编不过	✅ 代码问题	工具链是好的 → 那是下发包自身的代码缺陷，别动环境
所有目标都卡在同一个工具上（都找不到 clang / ninja…）	🔴 环境问题	§1.11 自检 → PATH → 盘符
报 cstddef 找不到	🔴 环境问题	where arm-none-eabi-gcc 空不空 → §1.7
openocd --version 正常、探测也正常，但读内存失步	🔴 版本问题	用了 xPack 0.12.0 → 回 §1.9
打完 banner 无限静默卡住	🔴 硬件问题	探针好的，芯片没响应 → 查接线/供电/有没有接板子（坑 23）
命令打印一段用法后静默退出	🔴 参数/版本问题	见 §1.9 末尾
报 ERROR:No target select.	⚠️ 名字写错了	大小写不对 → §3.2

💡 一句话记住：「有的过有的不过 → 工具链是好的」。

7.1 环境类

🔴 坑 1：路径含中文 / 空格 → CMake / Ninja 各种奇怪报错

🔴 坑 2：ninja / cmake / clang 报 「不是内部或外部命令」 → PATH 没生效

'ninja' 不是内部或外部命令，也不是可运行的程序或批处理文件。

🔴 坑 3：python 命令不存在 / 敲 python 弹出微软商店

Remove-Item "$env:LOCALAPPDATA\Microsoft\WindowsApps\python.exe"  -Force
Remove-Item "$env:LOCALAPPDATA\Microsoft\WindowsApps\python3.exe" -Force

🔴 坑 4：杀毒软件拦截 → 编译变慢 / 文件被锁

🔴 坑 5：core.autocrlf 导致 CRLF → 旧版 project.py 会 IndexError 崩溃

🔴 坑 6：Windows 更新中途重启 → 编译到一半断电

🔴 坑 7：code --version 不打印版本、反而弹出一个 VS Code 窗口然后卡住

🔴 坑 8：dir ...\arm-none-eabi\include\cstddef 报「找不到文件」

Get-ChildItem '<你的 ARM 工具链目录>' -Recurse -Filter cstddef |
  Select-Object -ExpandProperty FullName

🔴 坑 9：单独敲 clang++ --target=arm-none-eabi 编 C++ 报 'cstddef' file not found

7.2 构建类

🔴 坑 10：project.py config 保存后报 cstddef 找不到 → 其实是坑 2 的变体

CMake Error at hw/bsp/mc02/toolchain.cmake:128 (message):
  Could not find the arm-none-eabi toolchain C++ headers (cstddef).

    arm-none-eabi-gcc :
    sysroot           :
    searched          : <sysroot>/include/c++/*/cstddef and /usr/include/newlib/c++/*/cstddef
...
CMake Error: CMake was unable to find a build program corresponding to "Ninja".
  CMAKE_MAKE_PROGRAM is not set.
-- Configuring incomplete, errors occurred!

if(WIN32)
  execute_process(
    COMMAND where arm-none-eabi-gcc      # ← 完全依赖 PATH
    OUTPUT_VARIABLE GCC_ARM_NONE_EABI_GCC
    ...)
  ...
  get_filename_component(GCC_ARM_NONE_EABI_BIN "${GCC_ARM_NONE_EABI_GCC}" DIRECTORY)
  get_filename_component(GCC_ARM_NONE_EABI_PREFIX "${GCC_ARM_NONE_EABI_BIN}" DIRECTORY)
  if(EXISTS "${GCC_ARM_NONE_EABI_PREFIX}/${CLANG_TARGET}")
    set(GCC_ARM_NONE_EABI_ROOT "${GCC_ARM_NONE_EABI_PREFIX}/${CLANG_TARGET}")
  endif()
endif()

where.exe arm-none-eabi-gcc
where.exe ninja

🔴 坑 11：Configuration file not found / ERROR:No target select.

🔴 坑 12：Cannot find source file: .../system_stm32h7xx.c → 没跑子模块初始化

git submodule update --init

🔴 坑 13：'robot.hpp' file not found → 配置指向的 robot 不存在

🔴 坑 14：'dev_cap.hpp' file not found → 某些分支没有 src/device/cap/

🔴 坑 15：HAL_IWDG_DeInit 未定义 → STM32 的 IWDG HAL 根本没有这个函数

🔴 坑 16：module.hpp: No such file or directory → 同名头 / 选错模块

🔴 坑 17：编译"到一半失败"但没提示 → 一定要看汇总

1 target(s) failed to build:
  - .../hw/bsp/XXX [yyy] (cmake configure failed)

🔴 坑 18：build all all 报 Webots 的 cmake configure failed

lld-link: error: could not open 'kernel32.lib': no such file or directory

🔴 坑 19：编完 A 目标，再编 B 目标，firmware\ 里 A 不见了

🔴 坑 20：没配置过就编译 —— 两种报错，都不是环境坏了

@echo off
if not exist build mkdir build
cd build
ninja -j%NUMBER_OF_PROCESSORS%
cd ..

dir build\build.ninja       REM 有输出就说明配置过了
ninja -C build               REM 应该能正常跑

🔴 坑 21：目标名（robot / module）随分支和压缩包变化，不能背文档

Configuration file not found
ERROR:No target select.
fatal error: 'dev_blink_led.hpp' file not found

26-Omni_Infantry   demo_serial_leg_chassis   Drone      gather_table
Mecanum_Hero       Mecanum_Infantry          Meca_TrackHero
Music              New_26_Hero               Omni_Infantry   Radar
rudder_chassis     rudder_gimbal             Shoot_Hero      WLT_TestChassis

7.3 烧录类

🔴 坑 22：Error: couldn't open analysis\before-flash.bin → 反斜杠被 Tcl 吃掉

🔴 坑 23：烧完没反应 → 先确认烧的是哪个固件，再确认板子型号

openocd -f hw/bsp/rm-c/debug/openocd_dap.cfg -c init -c halt -c "flash probe 0" -c "flash banks" -c shutdown

🔴 坑 24：Error: CMSIS-DAP command mismatch. Expected 0x6 received 0x5

🔴 坑 25：Can't find interface/cmsis-dap.cfg

openocd -c "echo [find interface/cmsis-dap.cfg]" -c shutdown

🔴 坑 26：没备份就烧了

openocd -f hw/bsp/rm-c/debug/openocd_dap.cfg -c init -c halt -c "dump_image analysis/rm-c-backup.bin 0x08000000 0x100000" -c shutdown

openocd -f hw/bsp/mc02/debug/openocd_dap.cfg -c init -c halt -c "flash write_image erase analysis/mc02-backup-20261002-024759.bin 0x08000000" -c reset -c shutdown

🔴 坑 27：蜂鸣器响完就不叫了 / 车控不了 → Error_Handler 的报警

🔴 坑 28：板子反复重启 → 看门狗复位 或 Error_Handler 循环

7.4 调试类

🔴 坑 29：p g_assert_file / p g_err_file / p g_overflow_task_name

🔴 坑 30：System::AssertInfo() —— 没调试器时在还能跑的线程里打印

7.5 报错怎么读（零基础版）

1. 先看最后 20 行 —— 真正的错误几乎总在最后；
2. 找 error: / Error: 关键字，忽略 warning；
3. 看第一个错，后面的经常是它的连锁反应；
4. 把报错原文整段贴出来问，别只说"编译不过"；
5. 对照坑 22 的特征：路径里出现少字母或多出怪空格（如 analysisefore-flash.bin） = -c "..." 里用了反斜杠。

7.6 脚本 / 自动化类

这一节是给「用脚本或远程方式配环境」的人看的。手动双击安装的同学可以跳过。

🔴 坑 31：PowerShell 脚本里的中文变成乱码

🔴 坑 32：脚本装 ARM 工具链时永久卡住

🔴 坑 33：脚本里装软件静默装错目录（参数被空格拆断 / 用错参数名）

# ❌ 错：'/DIR=D:\Program Files\Git' 被拆成 '/DIR=D:\Program' + 'Files\Git'
Start-Process $exe -ArgumentList '/DIR=D:\Program Files\Git' -Wait

# ✅ 对：用数组，一个参数一个元素；加 -NoNewWindow 让退出码能正常回传
Start-Process $exe -ArgumentList @('/DIR=D:\Program Files\Git') -Wait -NoNewWindow -PassThru

Get-CimInstance Win32_Process -Filter "Name='cmd.exe'" |
  Where-Object { $_.CommandLine -like '*gccvar*' } |
  ForEach-Object { Stop-Process -Id $_.ProcessId -Force }

附录 A 目录结构

RowletBot\
  project.py                 ← 总指挥（日常只用 config / clean，见 §3.2）
  build_script.bat           ← 快速重编
  download_dap.bat           ← 仓库自带的一键烧录（⚠️ 分支差异大，别直接双击，见 §4.4）
  config\                    ← .config / config.cmake（构建时生成）
  build\                     ← 编译产物（xrobot.bin/elf/hex/map、compile_commands.json）
  firmware\                  ← 归档产物（⚠️ 正常流程不产生）
  analysis\                  ← 固件备份放这里（别提交 git）
  src\                       ← robot / module / component / device / system
  hw\bsp\<板子>\             ← config\ / debug\(openocd_dap.cfg, launch.json) / drivers\ / ld\
  lib\                       ← 第三方库（含 5 个 vendored 子模块）
  user\                      ← 你自己的代码
  toolchain\                 ← 构建产物缓存（openocd_dap.cfg 的拷贝在这里，⚠️ 别用它烧录）
  tools\ozone\               ← Ozone 调试脚本与工程（⚠️ 脚本里写死了作者机器的路径，是另一条 Ozone ≥3.40 路线，见 §0.3）

附录 B 本文实测环境（版本参照）

📌 本文主用例已改为 rm-c + ex1_led（§3.2）。

这份下发包里几个关键文件的实测大小（无 md5/包体字节数 —— 未测，不列）：

文件	实测大小
build_script.bat	133 字节
download_dap.bat	174 字节
.vscode\settings.json	4,205 字节
ninja.exe	569,856 字节
openocd.exe	4,245,518 字节

📌 本表是"我们测过哪一版"的存档，不是让你照着下这个版本 —— 补丁号更新很正常（如 Git 2.48、Python 3.12.9），大版本一致就行。 📌 唯一要留神的是 CMake：官网现在给的是 4.x，而本文只实测过 3.31.x —— §1.11 的自检不核对 cmake 版本（只验"环境变量可用"），装了 4.x 它照样显示 [OK] 环境变量可用；但万一 cmake 配置这一步报错，就换回 3.31.x（见 §1.5）。 安装位置按 §0.3 的约定：CMake / LLVM / Ozone 用官方安装包的默认位置，Ninja / OpenOCD / ARM 工具链在 C:\Tools\。

卡住的时候，先把自己的 --version 输出和这张表对一遍 —— 十有八九能直接看出是哪个工具不对。 只有 §1.0 第 2 条那 4 个红线工具（OpenOCD / Ozone / ARM / LLVM）必须严格对上，其余差个补丁号无所谓。

附录 C 术语表（零基础速查）

读文档时遇到不认识的词，来这里查。按"你在哪儿看到它"分组。 本文档里没解释、你又看不懂的词 → 直接在群里问，问的时候把看到它的那句话一起贴出来。

C.1 硬件与目标

C.2 编译与工具链

C.3 工程与代码

C.4 调试与烧录

C.5 系统与操作