dsh-stm32 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -16
- package/README_EN.md +84 -17
- package/client/client.js +682 -0
- package/docs/development-notes.md +920 -2
- package/docs/logic-audit.md +607 -0
- package/lib/client.js +682 -0
- package/lib/commands/register.js +165 -12
- package/lib/data/cmsis-sources.js +147 -0
- package/lib/data/firmware-packages.js +352 -0
- package/lib/data/install-guides.js +190 -0
- package/lib/data/search-roots.js +135 -15
- package/lib/data/toolchain-config.js +310 -0
- package/lib/engine/build.js +6 -0
- package/lib/engine/cache.js +280 -0
- package/lib/engine/code-patch.js +18 -6
- package/lib/engine/debug-session.js +163 -4
- package/lib/engine/debug.js +9 -9
- package/lib/engine/fetch.js +143 -0
- package/lib/engine/firmware-install.js +668 -0
- package/lib/engine/flash.js +51 -10
- package/lib/engine/fs-longpath.js +107 -0
- package/lib/engine/generate-cache.js +118 -0
- package/lib/engine/generate-script.js +30 -8
- package/lib/engine/generate.js +285 -14
- package/lib/engine/ioc-plan.js +19 -6
- package/lib/engine/msys2-install.js +1599 -0
- package/lib/engine/probe.js +57 -6
- package/lib/engine/register-template.js +378 -0
- package/lib/engine/regs.js +18 -4
- package/lib/engine/route-plan.js +553 -0
- package/lib/engine/scaffold.js +225 -70
- package/lib/engine/subprocess-runner.js +2 -0
- package/lib/engine/tar.js +250 -0
- package/lib/engine/text-file.js +150 -0
- package/lib/engine/thirdparty.js +243 -0
- package/lib/engine/tool-env.js +51 -0
- package/lib/engine/toolchain-gate.js +386 -0
- package/lib/engine/vscode-config.js +99 -0
- package/lib/engine/web-api.js +375 -0
- package/lib/engine/web-routes.js +100 -0
- package/lib/engine/xcube-catalog.js +102 -0
- package/lib/engine/xcube.js +254 -0
- package/lib/index.js +42 -2
- package/lib/skill/stm32-workflow.js +1 -1
- package/lib/tools/build.js +43 -3
- package/lib/tools/cache.js +219 -0
- package/lib/tools/code-patch.js +29 -2
- package/lib/tools/debug-session.js +56 -14
- package/lib/tools/debug.js +36 -2
- package/lib/tools/doctor.js +5 -1
- package/lib/tools/env-install.js +472 -0
- package/lib/tools/env-probe.js +6 -2
- package/lib/tools/firmware-install.js +255 -0
- package/lib/tools/flash.js +38 -2
- package/lib/tools/generate.js +96 -10
- package/lib/tools/ioc-apply.js +27 -11
- package/lib/tools/ioc-inspect.js +4 -2
- package/lib/tools/ioc-plan.js +14 -7
- package/lib/tools/project-create.js +204 -21
- package/lib/tools/project-dir.js +95 -0
- package/lib/tools/regs.js +82 -7
- package/lib/tools/route-plan.js +467 -0
- package/package.json +7 -2
- package/templates/register/CMakeLists.txt +39 -0
- package/templates/register/Core/Src/main.c +63 -0
- package/templates/scaffold/vscode/launch.json +8 -6
- package/templates/scaffold/vscode/settings.json +5 -11
package/README.md
CHANGED
|
@@ -10,9 +10,9 @@
|
|
|
10
10
|
[](LICENSE)
|
|
11
11
|
[](#已知限制)
|
|
12
12
|
[](#已知限制)
|
|
13
|
-
[](https://github.com/JingYu-er/dsh-stm32/releases)
|
|
14
14
|
|
|
15
|
-
这是一个 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **插件**:注册
|
|
15
|
+
这是一个 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **插件**:注册 19 个工具、6 条斜杠命令和 1 个随插件下发的 SKILL,让模型能直接探测工具链、建cubemx cmake工程、改 `.ioc`、跑 CubeMX、编译、烧录和调试,烧完再把寄存器里的状态读回来确认——实现更彻底的面向DSH硬件编程。
|
|
16
16
|
|
|
17
17
|
## 为什么需要它
|
|
18
18
|
|
|
@@ -56,7 +56,7 @@ dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main
|
|
|
56
56
|
|
|
57
57
|
`dsh plugin` 做的事就是在 profile 目录里跑 `pnpm add`。装完它会把 `dsh-stm32` 写进该 profile 的 `dsh.profile.bundles`,重启 dsh 即生效(把 `desktop` 换成 `web` 就装到 web profile)。
|
|
58
58
|
|
|
59
|
-
装完确认:`dsh plugin --profile desktop why dsh-stm32` 应显示 `0.1.
|
|
59
|
+
装完确认:`dsh plugin --profile desktop why dsh-stm32` 应显示 `0.1.1`;重启后 `/stm32-doctor` 有输出。
|
|
60
60
|
|
|
61
61
|
|
|
62
62
|
**卸载**:`dsh plugin --profile desktop remove dsh-stm32`,重启 dsh。
|
|
@@ -68,7 +68,7 @@ git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
|
68
68
|
cd dsh-stm32
|
|
69
69
|
npm install --no-audit --no-fund # 只装 typescript
|
|
70
70
|
npm run build # tsc -> lib/(提交前必须跑)
|
|
71
|
-
npm test # 可选:
|
|
71
|
+
npm test # 可选:309 个离线用例,不需要板子
|
|
72
72
|
```
|
|
73
73
|
|
|
74
74
|
挂进 dsh 的 profile——**改代码时必须用 `link:`,不要用 `file:`**:
|
|
@@ -91,7 +91,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
91
91
|
| --- | --- | --- | --- |
|
|
92
92
|
| 1 | 体检:工具链、被占用的探针、端口、`.elf`、`.ioc` 告警 | `stm32_doctor` | ~2 s |
|
|
93
93
|
| 2 | 空目录建 CMake 工程骨架(14 个模板文件 + 629 个固件文件 + 配好 SWD 的 `.ioc`) | `stm32_project_create` | ~2 s |
|
|
94
|
-
| 3 | 按 `.ioc` 无头跑 CubeMX,产物落到 `Core/` | `stm32_generate` |
|
|
94
|
+
| 3 | 按 `.ioc` 无头跑 CubeMX,产物落到 `Core/` | `stm32_generate` | 首次 130–175 s;之后再跑,`.ioc` 与产物都没变会**直接跳过**(<1 s) |
|
|
95
95
|
| 4 | 编译(首次自动 `cmake --preset`) | `stm32_build` | 配置 ~5 s + 编译 3 s |
|
|
96
96
|
| 5 | **只烧录**:program + verify + reset | `stm32_flash` | 2.1–2.6 s |
|
|
97
97
|
| 6 | 读回 `GPIOC_ODR`,确认状态确实在翻 | `stm32_regs_read` | 0.4–1.3 s |
|
|
@@ -100,6 +100,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
100
100
|
|
|
101
101
|
```text
|
|
102
102
|
/stm32-doctor # 开工前体检
|
|
103
|
+
/stm32-env # 只看四项能力缺什么(缺件也能看)
|
|
103
104
|
/stm32-build # 编译,打印内存占用与错误
|
|
104
105
|
/stm32-flash # 只烧录,不进调试会话
|
|
105
106
|
/stm32-debug # 烧录 + 停在 main
|
|
@@ -127,7 +128,10 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
127
128
|
| 能力 | 提供方式 |
|
|
128
129
|
| --- | --- |
|
|
129
130
|
| 环境体检 | `stm32_env_probe`(只读)、`stm32_doctor`(工具链 + 探针占用 + 端口 + 工程告警) |
|
|
130
|
-
|
|
|
131
|
+
| 开工前门禁 | 每个会动工具链的工具先过 `ensureToolchain`:缺件就拦住并写清装什么、缺了会怎样;`envCheck: "block"`(默认)/ `"warn"` / `"off"` 由调用方决定 |
|
|
132
|
+
| 装工具链 | `stm32_env_install`:先只出计划(下载什么、多大、要改哪条 PATH),你点头才真装 MSYS2 + 5 个 pacman 包 + 用户级 PATH,装完自己写进配置文件 |
|
|
133
|
+
| 选技术路线 | `stm32_route_plan`:先按**这个工程**的需求,把每个外设的 HAL 版与寄存器版代价摆出来(效率 / 可读性 / 排错),再告诉你缺的是「能代装的」还是「只能人装的」(CubeMX 是 GUI 向导 + 要 ST 账号、固件包只由 CubeMX 包管理器维护) |
|
|
134
|
+
| 从零建工程 | `stm32_project_create`:`route: "hal"` 用模板快照 + 固件包 Drivers(与 CubeMX GUI 新建的工程逐字节一致);`route: "register"` 建不用 CubeMX 的寄存器版工程,CMSIS 模板首次从网上下到缓存、之后复用 |
|
|
131
135
|
| `.ioc` 事务 | `stm32_ioc_inspect`(只读解析)→ `stm32_ioc_plan`(算 diff,不写盘)→ `stm32_ioc_apply`(SHA 校验 + 备份 + 回滚) |
|
|
132
136
|
| 只改 USER CODE | `stm32_code_patch`:只写 `/* USER CODE BEGIN X */` 与 `END X` 之间,块外逐字节不动 |
|
|
133
137
|
| 生成代码 | `stm32_generate`:无头 CubeMX + 按 ST 结构落位 + USER CODE 按标签搬回 |
|
|
@@ -144,8 +148,12 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
144
148
|
| 工具 | 作用 |
|
|
145
149
|
| --- | --- |
|
|
146
150
|
| `stm32_env_probe` | 探测 gcc / gdb / openocd / cmake / ninja / CubeMX / JRE 的路径与版本;缺什么会写清影响(编译不了 / 烧不了 / 调不了 / 建不了工程)、推荐装法(含可粘贴的 pacman / winget 命令)、装完自检命令,并给 `capabilities`(四项能力是否可用)与 `recommendations`(安装顺序 + 要不要我帮你装)。只读、可重复调 |
|
|
151
|
+
| `stm32_env_install` | 缺工具链时的一条龙:`dryRun`(默认)只给计划——官方 MSYS2 安装包多大、要装哪 5 个包、PATH 会加哪一条;`dryRun: false` + `confirm: true` 才真干活(下载 → 装 MSYS2 → `pacman -S` → 写 **用户级** PATH → 自检 → 写 `~/.dsh-stm32/config.json`)。已装 msys64 时只补包。不做卸载 |
|
|
152
|
+
| `stm32_route_plan` | 动手前先把路线问清楚:`requirement` 必填(如「按键控制 LED,串口每秒打印一次状态」),返回 `verdict`(`register-ok` / `both-viable` / `hal-only` / `unclear`)、逐外设的 `halEffort`/`regEffort` 与 `advice`、两种写法的差别、落地的下一步、工具链缺件(每条标 `installability`:`auto` 可代装 / `manual` 只能人装)与手动安装指引全文。不做通用对照表——结论只对当前需求成立 |
|
|
147
153
|
| `stm32_doctor` | 一次回答三件事:工具链齐不齐、探针被谁占(`openocd.exe` / gdb 进程 / 3333 端口)、这个工程能不能烧 |
|
|
148
|
-
| `stm32_project_create` | 空目录 → 完整 CMake
|
|
154
|
+
| `stm32_project_create` | 空目录 → 完整 CMake 工程。`route: "hal"`(默认)走 CubeMX 那套(含 `.vscode` 里"① 只烧录 / ② 烧录并调试"两份配置);`route: "register"` 建**不用 CubeMX、不用 HAL** 的寄存器版工程(`mcu` 指定型号,CMSIS 头与启动文件从缓存取)。目标目录非空默认拒绝,`overwrite: true` 才覆盖 |
|
|
155
|
+
| `stm32_cache` | 看 / 验 / 拉 / 清下载缓存:`action: "list"`(默认)列条目、`"verify"` 逐文件校验、`"fetch"` 按 `mcu` 拉一次模板(已缓存则直接复用,不联网)、`"purge"` 删条目(不给 `id` 就清空)。缓存里放的是"不属于插件、但建工程要用"的 CMSIS 设备头 + 启动文件 + 内核头,第一次用时才下载,之后一直复用 |
|
|
156
|
+
| `stm32_firmware_install` | 缺固件包时的一条龙:`dryRun`(默认)只出计划——装到哪、下哪两个源码仓、几条自检判据;`dryRun: false` + `confirm: true` 才真下(GitHub 上 HAL 驱动与 CMSIS 设备支持两个源码包 + 内核头,合计约 2 MB),组装成与官方同构的 `STM32Cube_FW_<族>_V<版本>` 包(自写 `package.xml`)并过五条自检。已有官方包时什么都不做;默认装到 `<CubeMX 根>/dsh-firmware`(不是 `Repository`——塞自造版本号会被 CubeMX 静默忽略),生成时由 `stm32_generate` 用 `setCustomFWPath` 指过去 |
|
|
149
157
|
|
|
150
158
|
### .ioc:只读与事务
|
|
151
159
|
|
|
@@ -160,7 +168,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
160
168
|
| 工具 | 作用 |
|
|
161
169
|
| --- | --- |
|
|
162
170
|
| `stm32_code_patch` | 只在 `USER CODE` 块内 replace/append;块外字节(含 CRLF)原样保留;写前备份、临时文件 + rename 原子替换。标签写错会把该文件所有可用标签列给你 |
|
|
163
|
-
| `stm32_generate` | 无头跑 `java -jar STM32CubeMX.exe -q`,成功后落位到 `Core/Src`、`Core/Inc`,旧文件的 USER CODE 按标签搬进新内容。默认后台 job |
|
|
171
|
+
| `stm32_generate` | 无头跑 `java -jar STM32CubeMX.exe -q`,成功后落位到 `Core/Src`、`Core/Inc`,旧文件的 USER CODE 按标签搬进新内容。默认后台 job。**`.ioc`、CubeMX 版本、产物 hash 都没变时直接复用上次结果**(`skipped: true`,约 1 s;传 `skipIfUnchanged: false` 或删 `.dsh-stm32/generate-cache.json` 可强制重跑)。工程没用 X-CUBE 扩展包时(`Mcu.ThirdPartyNb=0`)会自动把 `~/.stm32cubemx/thirdparties/pdsc` 临时停放、跑完还原,省约 25 s;要保留索引传 `thirdpartyPacks: "keep"`。**要不要索引不靠关键词猜**:`.ioc` 里的 `Mcu.ThirdParty0=STMicroelectronics.X-CUBE-ALGOBUILD.1.4.0` 会跟内置的 X-CUBE 包目录(67 个包,`scripts/gen-xcube-catalog.mjs` 生成)对名字,本机缺这个包会提前在 notes 里警告 |
|
|
164
172
|
| `stm32_build` | `cmake --build`,构建目录从 `CMakePresets.json` 与 `build/*/CMakeCache.txt` 推断;首次构建自动 configure;会拦住"CMakeCache 目录不一致但 ninja 退出码 0"的假成功 |
|
|
165
173
|
|
|
166
174
|
### 烧录与调试
|
|
@@ -181,6 +189,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
181
189
|
| 命令 | 做什么 | 会不会动板子 |
|
|
182
190
|
| --- | --- | --- |
|
|
183
191
|
| `/stm32-doctor` | 体检:工具链、被占用的调试进程、端口、`.elf`、`.ioc` 告警 | 否 |
|
|
192
|
+
| `/stm32-env` | 看四项能力(编译 / 烧录 / 调试 / 生成代码)各缺什么、装什么、装完怎么自检;缺件也照常出卡片 | 否 |
|
|
184
193
|
| `/stm32-build [dir] [--clean]` | 编译,打印内存占用 / `.elf` / 错误 | 否 |
|
|
185
194
|
| `/stm32-flash [dir]` | **烧录**:program + verify + reset,不建调试会话、不下断点 | 是 |
|
|
186
195
|
| `/stm32-debug [dir]` | **烧录 + 调试**:烧完停到 `main`,会话保留(空闲 3 分钟 / 上限 10 分钟,本轮结束也会自动关) | 是 |
|
|
@@ -198,13 +207,68 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
198
207
|
|
|
199
208
|
## 配置
|
|
200
209
|
|
|
210
|
+
### 用户配置文件(`~/.dsh-stm32/config.json`)
|
|
211
|
+
|
|
212
|
+
工具装在哪,插件自己记。`stm32_env_install` 装完会写这个文件,之后所有工具读它——**不用重启 DSH、也不用设环境变量**。手写也行:
|
|
213
|
+
|
|
214
|
+
```json
|
|
215
|
+
{
|
|
216
|
+
"version": 1,
|
|
217
|
+
"msys64": "E:/msys64",
|
|
218
|
+
"binDirs": [],
|
|
219
|
+
"packages": ["mingw-w64-ucrt-x86_64-arm-none-eabi-gcc", "mingw-w64-ucrt-x86_64-cmake"],
|
|
220
|
+
"cubeMxRoot": "",
|
|
221
|
+
"updatedAt": "2026-02-01T00:00:00.000Z"
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
`binDirs` 留空时由 `msys64` 推出 `<msys64>/ucrt64/bin`——安装器写的就是这个形状。文件坏了(JSON 不合法)不会让工具报错,只是当它不存在。
|
|
226
|
+
|
|
227
|
+
**优先级**:工具参数(`binDirs` / `cubeMxRoots`)> 环境变量 > 这个配置文件 > 内置默认值;自动发现只追加在"没点名参数"的那一档尾部。
|
|
228
|
+
|
|
229
|
+
**内置默认值里没有任何"某台机器专属"的路径**:只有 `C:/msys64/...` 与 `C:/Program Files/...` 这种 Windows 默认安装位置,装在别处靠自动发现兜底。配置或环境变量里点名的目录如果在本机不存在(典型情况:配置是从别的机器拷过来的,带着 `D:/app/msys64` 这种路径),门禁与 `stm32_env_probe` 会明确写一句「配置文件里的 X 在本机不存在……这一条搜不到工具」,而**不会**悄悄改你的配置;安装器也不会拿这种路径当安装目标(盘符都没有时只提示、并要求你给 `targetDir`)。
|
|
230
|
+
|
|
231
|
+
### 设置面板(GUI)
|
|
232
|
+
|
|
233
|
+
上面那个配置文件也能不碰命令行改:DSH 的 **设置 → STM32 工具链**(插件自带的浏览器端面板,与宿主同源,零额外依赖)。三张卡:
|
|
234
|
+
|
|
235
|
+
- **装在哪**:读当前配置,改 `msys64` / `cubeMxRoot` / 额外 `binDirs` 后保存——写的就是上面那个文件,下一条工具调用就读得到,不用重开 DSH;
|
|
236
|
+
- **缺什么**:跑一次探测(会执行各工具的版本命令,不装任何东西),逐项显示找到的路径与版本、缺件的 `hint`,以及编译 / 烧录 / 调试 / 生成四项能力徽章;
|
|
237
|
+
- **装工具链**:先出计划(步骤、下载体积、PATH 与配置会怎么改),**再点一次确认**才真装;装的过程实时显示步骤与日志尾巴,实际执行与 `stm32_env_install` 是同一个安装器。工具链已经完整时,计划只回一句话「工具链完整,不需要装任何东西」,不列那七行「已跳过」。
|
|
238
|
+
|
|
239
|
+
接口是插件注册在宿主上的六条 `/dsh-stm32/api/*`(读配置、存配置、探测、安装计划、开始安装、安装进度);面板产物是 `lib/client.js`,源码在 `client/client.js`,由 `npm run build` 原样复制——手写纯 JS、只 `require("react")`,不引入打包器或运行时依赖。宿主没有 `webServer` 服务时(纯 CLI 组合)这层注册自动跳过,工具与斜杠命令不受影响。
|
|
240
|
+
|
|
241
|
+
### 下载缓存(寄存器版模板)
|
|
242
|
+
|
|
243
|
+
寄存器版工程要的 CMSIS 设备头、启动文件、内核头**不预置进插件**(要覆盖任意 STM32,每颗都打一份会让包大到不可用),而是第一次用时从网上下载,落到一个可检索的缓存目录,之后一直复用:
|
|
244
|
+
|
|
245
|
+
- 位置:`DSH_STM32_CACHE`(支持 `~`)> `%LOCALAPPDATA%\dsh-stm32\cache`;
|
|
246
|
+
- 索引:缓存根下 `index.json` 记录每条源 URL、字节数、许可(`THIRD_PARTY_NOTICES.md` 随条目一起写);
|
|
247
|
+
- 下载源:按 `fastly.jsdelivr` → `cdn.jsdelivr` → `raw.githubusercontent` → `ghproxy` 的顺序回退,HTTP 错误 / 内容像网页 / 字节数明显不对都算该源失败;
|
|
248
|
+
- 半截缓存会被整条删掉(比没有缓存更糟);条目文件缺失或大小对不上时下次自动重下;
|
|
249
|
+
- 看得见、清得掉:`stm32_cache` 的 `list` / `verify` / `fetch` / `purge`。
|
|
250
|
+
|
|
251
|
+
### 固件包下载(HAL 路线)
|
|
252
|
+
|
|
253
|
+
CubeMX 装好也不一定有**这一颗芯片**的固件包(安装包里不带,得在包管理器里另装)。插件能代下的那一代,`stm32_firmware_install` 会从 GitHub 拉两个源码包组装出来:
|
|
254
|
+
|
|
255
|
+
- 下什么:`stm32f1xx-hal-driver`(HAL 驱动,BSD-3-Clause)+ `cmsis-device-f1`(设备头与启动文件,Apache-2.0)+ 5 个 CMSIS 内核头,合计约 2 MB、几秒钟;
|
|
256
|
+
- 为什么不能直接解压 `STM32CubeF1` 的源码包:它的 HAL 与 CMSIS 设备目录是 **git 子模块**,tarball 里是空目录——解压出来编译必挂(缺 startup、缺 HAL 源文件);
|
|
257
|
+
- 装到哪:默认 `<CubeMX 根>/dsh-firmware/<包名>`(与 `Repository` 并列、插件自建,不动官方包);这个根写不进去才退回用户缓存目录。**别往 `Repository` 里塞自造版本号**——实测 CubeMX 认不出那个版本名,不报错地退回它自己认识的包(生成「成功」,HAL 却是旧版);
|
|
258
|
+
- 生成时怎么用上它:`stm32_generate` 按 `.ioc` 的 `ProjectManager.FirmwarePackage` 找包(`Repository` 与 `<CubeMX 根>/dsh-firmware` 都找),并在 CubeMX 脚本里发 `project setCustomFWPath <包目录>`——这是唯一被实测有效的机制,不往 `.ioc` 里写绝对路径;
|
|
259
|
+
- 组装包与官方包同构:自写 6 行 `package.xml`(版本串 `FW.<族>.<x.y.z>`)与 `THIRD_PARTY_NOTICES.md`,**不含任何哈希/清单**——CubeMX 也不校验来源(已实测:用 `setCustomFWPath` 指过去生成,拷出的 HAL 源文件逐字节来自我们目录);
|
|
260
|
+
- 但「生成成功」不能当验收:`.ioc` 点名了不存在的包时 CubeMX 不报错、退出码 0、只是不拷 HAL。所以装完必须过五条判据(内核头 / HAL Inc / HAL Src / 设备头 / `startup_*.s`),插件装完自己就验一遍。
|
|
261
|
+
|
|
201
262
|
### 环境变量(可选)
|
|
202
263
|
|
|
203
264
|
| 变量 | 作用 | 默认 |
|
|
204
265
|
| --- | --- | --- |
|
|
205
|
-
| `STM32_BIN_DIRS` | 工具链目录候选,`;` 分隔,**整份替换**内置列表(之后的自动发现仍追加在尾部) | `
|
|
206
|
-
| `STM32_CUBEMX_ROOT` | STM32CubeMX 安装根目录,**整份替换**内置列表 | `
|
|
266
|
+
| `STM32_BIN_DIRS` | 工具链目录候选,`;` 分隔,**整份替换**内置列表(之后的自动发现仍追加在尾部) | `C:/msys64/ucrt64/bin`、`C:/msys64/mingw64/bin` |
|
|
267
|
+
| `STM32_CUBEMX_ROOT` | STM32CubeMX 安装根目录,**整份替换**内置列表 | `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` |
|
|
207
268
|
| `STM32_NO_DISCOVER` | 设为 `1` / `true` 关掉下面的自动发现(CI、只想用内置列表时) | 不设 = 开着 |
|
|
269
|
+
| `DSH_STM32_CONFIG` | 换一个配置文件路径(多份工具链 / 多工程隔离) | `%USERPROFILE%\.dsh-stm32\config.json` |
|
|
270
|
+
| `DSH_STM32_NO_CONFIG` | 设为 `1` / `true` 完全不读配置文件(只想走环境变量时) | 不设 = 读 |
|
|
271
|
+
| `DSH_STM32_CACHE` | 下载缓存根目录(寄存器版模板等),支持 `~` | `%LOCALAPPDATA%\dsh-stm32\cache` |
|
|
208
272
|
| `DSH_STM32_E2E_PROJECT` | 真机 e2e 用的工程(含 `openocd.cfg` 与 `build/Debug/*.elf`) | 无 |
|
|
209
273
|
| `DSH_STM32_E2E_ROOT` | e2e 临时副本目录 | 系统临时目录 |
|
|
210
274
|
|
|
@@ -258,22 +322,27 @@ source [find target/stm32f1x.cfg]
|
|
|
258
322
|
| 现象 | 原因与处理 |
|
|
259
323
|
| --- | --- |
|
|
260
324
|
| 烧完连不上、SWD 失联 | 固件里生成了 `__HAL_AFIO_REMAP_SWJ_DISABLE()`。按住 BOOT0 上电进系统 bootloader 重烧,然后把 SYS 设回 Serial Wire——`stm32_flash` 现在会先拦这种情况 |
|
|
261
|
-
| `Error: No device found` / `transfer count mismatch` | 探针被别的进程占着。先 `/stm32-stop`,再用 `stm32_doctor` 看 openocd / gdb 进程与 3333
|
|
325
|
+
| `Error: No device found` / `transfer count mismatch` | 探针被别的进程占着。先 `/stm32-stop`,再用 `stm32_doctor` 看 openocd / gdb 进程与 3333 端口。调试会话开着时读寄存器不会再有这个问题:`stm32_regs_read` 复用会话的 openocd,不另起第二个 |
|
|
326
|
+
| 调试会话开着时读寄存器,`report.command` 是一条 `gdb-multiarch … target extended-remote 127.0.0.1:3333` | 这是「复用会话」的正常形态:`stm32_debug_session` 活着时,`stm32_regs_read` 用会话自己的 gdb 连接执行 `print/x $pc` 与 `print/x *(unsigned int *)0x…`,读完 `monitor resume` 再 detach,notes 第一条写「复用调试会话(端口 N)的 openocd,没有另起一个」;只有没有会话时才另起 openocd。旧版在这里会报 `CMSIS-DAP transfer count mismatch: expected N, got M` |
|
|
262
327
|
| 编译"成功"但跑的是旧固件 | 复制或改名过带 `build/` 的工程:CMakeCache 里的目录对不上,ninja 仍退出 0。`stm32_build` 会判失败;按提示 clean 或删 `build/Debug` |
|
|
328
|
+
| 工具直接回「缺 arm-none-eabi-gcc…,这次没有开始编译」 | 这是开工前门禁(`envCheck` 默认 `block`)拦下来的,不是 bug:它比跑到一半才发现省时间。回一句「装」,模型调 `stm32_env_install` 出计划;确认后装好并写配置文件,**下一条命令就能用,不必重启**。想先看全貌就 `/stm32-env`;只想先跑起来就传 `envCheck: "warn"`(照做但写警告)或 `"off"`(不查) |
|
|
263
329
|
| `stm32_doctor` 说找不到 gcc / openocd | 先看 doctor 的 notes / 报错里的「查过 …」列表与自动发现结果;装上后还找不到就设 `STM32_BIN_DIRS` 或给工具传 `binDirs`。**不知道装什么就先跑 `stm32_env_probe`**:每条缺失项都带 `impact`(缺了影响哪些功能)、`install`(推荐装法,第一条最省事)、`verify`(装完自检),顶层 `recommendations` 给出安装顺序,还会问要不要帮你装 |
|
|
264
|
-
| `stm32_generate` 很慢或像卡住 |
|
|
330
|
+
| `stm32_generate` 很慢或像卡住 | 首次(冷启动、无缓存)3.5–4 分钟属正常,之后 .ioc 与产物没变会直接跳过(<1 s)。默认后台 job,用 `job_output` 看进度,或传 `foreground: true` 同步等。想确认是不是漏命中缓存,看返回里的 `skipped` 与 notes 给的 reason |
|
|
331
|
+
| 生成没变化却每次都跑满 3 分钟 | 缓存键里含 CubeMX 的 size+mtime 与产物 hash:换过 CubeMX、改过生成区文件、或改过落位布局都会失效。看 notes 里的 reason,或删 `.dsh-stm32/generate-cache.json` 从干净状态重来 |
|
|
332
|
+
| 生成变快了,但 CubeMX GUI 里看不到扩展包了 | `thirdpartyPacks: "auto"` 会在不需要扩展包时把 `thirdparties/pdsc` 停放成 `pdsc.dsh-parked`,生成结束自动还原。若正在 CubeMX GUI 里手工选包,传 `thirdpartyPacks: "keep"` |
|
|
333
|
+
| notes 说「本机第三方包索引里没有这个包」 | 工程要用的 X-CUBE 包本机没装(判定靠 `.ioc` 里的 `Mcu.ThirdParty<k>` 与内置包目录对名字)。在 CubeMX 的 Manage embedded software packages 里装上它再生成。这条在**生成失败的报告里也会出现**(超时/报错时照样带 notes,先看 notes 再猜原因)。内置目录是快照,装了新包后重跑 `node scripts/gen-xcube-catalog.mjs` 更新(旧的目录只是不认识新包,不会误判成「不需要」) |
|
|
265
334
|
| `stm32_code_patch` 说块不存在 | `main.c` 里是短标签(`PV`=私有变量、`PFP`=函数原型、`2`=while 前初始化、`3`=循环体);报错会列出该文件全部可用标签,照抄即可 |
|
|
266
335
|
|
|
267
336
|
## 开发与测试
|
|
268
337
|
|
|
269
338
|
```powershell
|
|
270
339
|
npm run build # tsc -> lib/(lib/ 入库,改完 src 必须重建后一起提交)
|
|
271
|
-
npm test #
|
|
340
|
+
npm test # 24 个离线套件、309 个用例;不需要板子、CubeMX、工具链
|
|
272
341
|
```
|
|
273
342
|
|
|
274
343
|
CI(`.github/workflows/ci.yml`)在每次 push / PR 上跑 `npm ci → build → 检查提交的 lib/ 是否与 src/ 同步 → npm test`(windows-latest)。
|
|
275
344
|
|
|
276
|
-
GitHub runner 上没有 msys64 / CubeMX,所以有两条依赖真固件包的脚手架用例会 skip:CI 上是 **
|
|
345
|
+
GitHub runner 上没有 msys64 / CubeMX,所以有两条依赖真固件包的脚手架用例会 skip:CI 上是 **307 pass + 2 skipped**,开发机上是 309 全跑。离线套件只读仓库自带的 [`test/fixtures/`](test/fixtures/README.md);会话类用例用 `fakeBinDirs()` 在临时目录造空文件占位的 openocd / gdb,不依赖本机装了什么。
|
|
277
346
|
|
|
278
347
|
真机 e2e 会写板子,需要你指一个能构建的工程:
|
|
279
348
|
|
|
@@ -289,9 +358,9 @@ node test\e2e-flash.mjs
|
|
|
289
358
|
```text
|
|
290
359
|
src/
|
|
291
360
|
index.ts 插件入口(name / inject / apply)
|
|
292
|
-
tools/
|
|
361
|
+
tools/ 19 个工具的 L3 层(参数 schema + 输出契约 + 渲染)
|
|
293
362
|
engine/ 纯逻辑与工作流(generate / build / flash / debug / ioc / scaffold …)
|
|
294
|
-
commands/register.ts
|
|
363
|
+
commands/register.ts 6 条斜杠命令
|
|
295
364
|
skill/stm32-workflow.ts 随插件下发的 SKILL
|
|
296
365
|
data/ 路径与芯片数据(路径是数据不是逻辑)
|
|
297
366
|
templates/scaffold/ 建工程用的模板快照(CMake / .ld / .vscode / .ioc)
|
package/README_EN.md
CHANGED
|
@@ -8,9 +8,9 @@
|
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
[](#known-limitations)
|
|
10
10
|
[](#known-limitations)
|
|
11
|
-
[](https://github.com/JingYu-er/dsh-stm32/releases)
|
|
12
12
|
|
|
13
|
-
A [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **plugin** (host-side, no UI): it registers
|
|
13
|
+
A [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **plugin** (host-side, no UI): it registers 19 tools, 6 slash commands and 1 SKILL shipped with the plugin, so the model can probe the toolchain, scaffold a CubeMX CMake project, edit the `.ioc`, run CubeMX, build, flash and debug on its own, then read the state back out of the registers — hardware programming that actually stays inside DSH.
|
|
14
14
|
|
|
15
15
|
## Why you need it
|
|
16
16
|
|
|
@@ -45,7 +45,7 @@ That is what "hardware programming inside DSH" means here: **the model does not
|
|
|
45
45
|
| STM32CubeMX (with its bundled JRE) | `stm32_generate`, `stm32_project_create` | Generation tools unavailable, everything else still works |
|
|
46
46
|
| STM32Cube firmware package F1 (installed with CubeMX) | Drivers copied when scaffolding | "Firmware package not found" |
|
|
47
47
|
|
|
48
|
-
Paths are searched as MSYS2 (`
|
|
48
|
+
Paths are searched as MSYS2 (`C:/msys64/ucrt64/bin`, `C:/msys64/mingw64/bin`) → ST official packages, with CubeMX at `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` by default; installs elsewhere are found by auto-discovery, and environment variables override everything (see [Configuration](#configuration)).
|
|
49
49
|
|
|
50
50
|
### Install (recommended: one command)
|
|
51
51
|
|
|
@@ -55,7 +55,7 @@ dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main
|
|
|
55
55
|
|
|
56
56
|
All `dsh plugin` does is run `pnpm add` inside the profile directory. On success it also appends `dsh-stm32` to that profile's `dsh.profile.bundles`, so a restart of dsh is all that is left (use `web` instead of `desktop` to target the web profile).
|
|
57
57
|
|
|
58
|
-
Verify with `dsh plugin --profile desktop why dsh-stm32` (should print `0.1.
|
|
58
|
+
Verify with `dsh plugin --profile desktop why dsh-stm32` (should print `0.1.1`); after a restart `/stm32-doctor` should respond.
|
|
59
59
|
|
|
60
60
|
|
|
61
61
|
**Uninstall**: `dsh plugin --profile desktop remove dsh-stm32`, then restart dsh.
|
|
@@ -67,7 +67,7 @@ git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
|
67
67
|
cd dsh-stm32
|
|
68
68
|
npm install --no-audit --no-fund # typescript only
|
|
69
69
|
npm run build # tsc -> lib/ (required before committing)
|
|
70
|
-
npm test # optional:
|
|
70
|
+
npm test # optional: 309 offline cases, no board needed
|
|
71
71
|
```
|
|
72
72
|
|
|
73
73
|
Link it into your dsh profile — **while editing code use `link:`, never `file:`**:
|
|
@@ -90,7 +90,7 @@ This chain ran on a real board (acceptance A1, 2026-10-22), driven entirely by t
|
|
|
90
90
|
| --- | --- | --- | --- |
|
|
91
91
|
| 1 | Health check: toolchain, busy probes, ports, `.elf`, `.ioc` warnings | `stm32_doctor` | ~2 s |
|
|
92
92
|
| 2 | Empty directory → CMake project skeleton (14 template files + 629 firmware files + an `.ioc` with SWD configured) | `stm32_project_create` | ~2 s |
|
|
93
|
-
| 3 | Headless CubeMX run driven by the `.ioc`, output placed under `Core/` | `stm32_generate` |
|
|
93
|
+
| 3 | Headless CubeMX run driven by the `.ioc`, output placed under `Core/` | `stm32_generate` | 130–175 s the first time; later runs are **skipped outright** (<1 s) while the `.ioc` and outputs are unchanged |
|
|
94
94
|
| 4 | Build (first run configures with `cmake --preset`) | `stm32_build` | ~5 s configure + 3 s build |
|
|
95
95
|
| 5 | **Flash only**: program + verify + reset | `stm32_flash` | 2.1–2.6 s |
|
|
96
96
|
| 6 | Read `GPIOC_ODR` back to confirm the state really toggles | `stm32_regs_read` | 0.4–1.3 s |
|
|
@@ -99,6 +99,7 @@ On the model side it is one sentence: "create a blinking-LED project for STM32F1
|
|
|
99
99
|
|
|
100
100
|
```text
|
|
101
101
|
/stm32-doctor # health check before you start
|
|
102
|
+
/stm32-env # what each capability is missing (works even when incomplete)
|
|
102
103
|
/stm32-build # build, print memory usage and errors
|
|
103
104
|
/stm32-flash # flash only, no debug session
|
|
104
105
|
/stm32-debug # flash + halt at main
|
|
@@ -126,7 +127,10 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
126
127
|
| Capability | How it is provided |
|
|
127
128
|
| --- | --- |
|
|
128
129
|
| Environment health check | `stm32_env_probe` (read-only), `stm32_doctor` (toolchain + busy probes + ports + project warnings) |
|
|
129
|
-
|
|
|
130
|
+
| Pre-flight gate | Every tool that needs the toolchain runs `ensureToolchain` first: missing pieces are refused up front with what to install and what stops working; `envCheck: "block"` (default) / `"warn"` / `"off"` |
|
|
131
|
+
| Install the toolchain | `stm32_env_install`: plan first (what is downloaded, how large, which PATH entry changes), install only after you confirm — MSYS2 + 5 pacman packages + a **user-level** PATH entry, then it writes the config file itself |
|
|
132
|
+
| Choose the technical route | `stm32_route_plan`: for **this project's** requirements, lays out the HAL and register cost per peripheral (effort / readability / debugging), then says whether what is missing is installable-by-the-plugin or human-only (CubeMX is a GUI wizard needing an ST account; firmware packages are only maintained by the CubeMX package manager) |
|
|
133
|
+
| Project from scratch | `stm32_project_create`: `route: "hal"` uses the template snapshot + firmware Drivers (byte-identical to a CubeMX GUI project); `route: "register"` builds a register-level project with no CubeMX at all, pulling the CMSIS template into the cache on first use |
|
|
130
134
|
| `.ioc` as a transaction | `stm32_ioc_inspect` (read-only parse) → `stm32_ioc_plan` (diff, no writes) → `stm32_ioc_apply` (SHA check + backup + rollback) |
|
|
131
135
|
| USER CODE only | `stm32_code_patch`: writes only between `/* USER CODE BEGIN X */` and `END X`; everything else untouched |
|
|
132
136
|
| Code generation | `stm32_generate`: headless CubeMX + ST project layout + USER CODE carried over by label |
|
|
@@ -143,8 +147,12 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
143
147
|
| Tool | What it does |
|
|
144
148
|
| --- | --- |
|
|
145
149
|
| `stm32_env_probe` | Detects gcc / gdb / openocd / cmake / ninja / CubeMX / JRE paths and versions; for anything missing it states the impact (cannot build / flash / debug / generate), the recommended install command (pacman / winget, paste-ready), a self-check command, plus `capabilities` (which of the four jobs work) and `recommendations` (install order and an offer to install for you). Read-only, repeatable |
|
|
150
|
+
| `stm32_env_install` | One-stop install when the toolchain is missing: `dryRun` (default) only returns a plan — size of the official MSYS2 installer, the five packages, the PATH entry it would add; only `dryRun: false` + `confirm: true` actually work (download → install MSYS2 → `pacman -S` → user-level PATH → self-check → write `~/.dsh-stm32/config.json`). With an existing msys64 it only adds the packages. No uninstall |
|
|
151
|
+
| `stm32_route_plan` | Settle the route before writing code: `requirement` is required (e.g. "a button drives the LED, UART prints its state once a second"), and it returns `verdict` (`register-ok` / `both-viable` / `hal-only` / `unclear`), per-peripheral `halEffort`/`regEffort` with `advice`, how the two routes differ, the next concrete step, and toolchain gaps tagged `installability` (`auto` = the plugin can install it / `manual` = human only) plus the full manual install guide. No generic comparison table — the verdict only holds for the requirement you gave |
|
|
146
152
|
| `stm32_doctor` | Answers three questions at once: is the toolchain complete, who holds the probe (`openocd.exe` / gdb processes / port 3333), can this project be flashed |
|
|
147
|
-
| `stm32_project_create` | Empty directory → full CMake project (including both "flash only" and "flash and debug" launch configs in `.vscode`). Refuses a non-empty target unless `overwrite: true` |
|
|
153
|
+
| `stm32_project_create` | Empty directory → full CMake project. `route: "hal"` (default) is the CubeMX route (including both "flash only" and "flash and debug" launch configs in `.vscode`); `route: "register"` builds a **no-CubeMX, no-HAL** register-level project (`mcu` picks the part, CMSIS headers and startup file come from the cache). Refuses a non-empty target unless `overwrite: true` |
|
|
154
|
+
| `stm32_cache` | Inspect / verify / fetch / purge the download cache: `action: "list"` (default), `"verify"` (per-file check), `"fetch"` (pull the template for an `mcu`, reusing the cache without touching the network), `"purge"` (drop entries; clears everything without an `id`). The cache holds what the register route needs but the plugin does not ship — CMSIS device headers, startup file, core headers — downloaded once, reused forever |
|
|
155
|
+
| `stm32_firmware_install` | One-stop firmware-package install: `dryRun` (default) returns only the plan — where it would land, which two source repos it would download, which checks must pass; `dryRun: false` + `confirm: true` actually downloads (HAL driver + CMSIS device support + core headers, ~2 MB total from GitHub), assembles an official-shaped `STM32Cube_FW_<family>_V<version>` package (writing `package.xml` itself) and runs five checks. Does nothing when the official package is already installed; installs into `<CubeMX root>/dsh-firmware` by default (not `Repository` — a self-made version there is silently ignored), and `stm32_generate` points CubeMX at it with `setCustomFWPath` |
|
|
148
156
|
|
|
149
157
|
### .ioc: read-only and transactions
|
|
150
158
|
|
|
@@ -159,7 +167,7 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
159
167
|
| Tool | What it does |
|
|
160
168
|
| --- | --- |
|
|
161
169
|
| `stm32_code_patch` | replace/append inside `USER CODE` blocks only; bytes outside (including CRLF) are preserved; backs up first, then writes a temp file and renames it. A wrong label lists every available label in the file |
|
|
162
|
-
| `stm32_generate` | Runs `java -jar STM32CubeMX.exe -q` headless, then places output under `Core/Src` and `Core/Inc`, carrying USER CODE from the old files by label. Background job by default |
|
|
170
|
+
| `stm32_generate` | Runs `java -jar STM32CubeMX.exe -q` headless, then places output under `Core/Src` and `Core/Inc`, carrying USER CODE from the old files by label. Background job by default. **When the `.ioc`, the CubeMX build and every output hash are unchanged it reuses the previous result** (`skipped: true`, ~1 s; pass `skipIfUnchanged: false` or delete `.dsh-stm32/generate-cache.json` to force a rerun). Projects that use no X-CUBE pack (`Mcu.ThirdPartyNb=0`) have `~/.stm32cubemx/thirdparties/pdsc` parked for the run and restored afterwards, saving ~25 s; pass `thirdpartyPacks: "keep"` to keep the index. **The need for the index is not guessed from keywords**: `Mcu.ThirdParty0=STMicroelectronics.X-CUBE-ALGOBUILD.1.4.0` in the `.ioc` is matched by name against a built-in pack catalog (67 packs, generated by `scripts/gen-xcube-catalog.mjs`), and a pack this machine lacks is reported in the notes up front |
|
|
163
171
|
| `stm32_build` | `cmake --build`, with the build directory inferred from `CMakePresets.json` and `build/*/CMakeCache.txt`; configures on first build; rejects the "CMakeCache directory mismatch but ninja exits 0" false success |
|
|
164
172
|
|
|
165
173
|
### Flash and debug
|
|
@@ -180,6 +188,7 @@ Tools are for the model; when you want to act yourself, use a command — one co
|
|
|
180
188
|
| Command | What it does | Touches the board |
|
|
181
189
|
| --- | --- | --- |
|
|
182
190
|
| `/stm32-doctor` | Health check: toolchain, busy debug processes, ports, `.elf`, `.ioc` warnings | No |
|
|
191
|
+
| `/stm32-env` | Shows what each of the four capabilities (build / flash / debug / generate) is missing, what to install and how to self-check; a missing toolchain still renders the card | No |
|
|
183
192
|
| `/stm32-build [dir] [--clean]` | Build, printing memory usage / `.elf` / errors | No |
|
|
184
193
|
| `/stm32-flash [dir]` | **Flash**: program + verify + reset, no debug session, no breakpoints | Yes |
|
|
185
194
|
| `/stm32-debug [dir]` | **Flash + debug**: halt at `main` after flashing, session kept (3 min idle / 10 min limit, also closed when the turn ends) | Yes |
|
|
@@ -197,13 +206,66 @@ Tools are for the model; when you want to act yourself, use a command — one co
|
|
|
197
206
|
|
|
198
207
|
## Configuration
|
|
199
208
|
|
|
209
|
+
### User config file (`~/.dsh-stm32/config.json`)
|
|
210
|
+
|
|
211
|
+
The plugin remembers where the toolchain lives. `stm32_env_install` writes this file when it finishes, and every tool reads it — **no DSH restart, no environment variables**. Hand-writing it works too:
|
|
212
|
+
|
|
213
|
+
```json
|
|
214
|
+
{
|
|
215
|
+
"version": 1,
|
|
216
|
+
"msys64": "E:/msys64",
|
|
217
|
+
"binDirs": [],
|
|
218
|
+
"packages": ["mingw-w64-ucrt-x86_64-arm-none-eabi-gcc", "mingw-w64-ucrt-x86_64-cmake"],
|
|
219
|
+
"cubeMxRoot": "",
|
|
220
|
+
"updatedAt": "2026-02-01T00:00:00.000Z"
|
|
221
|
+
}
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
An empty `binDirs` is derived from `msys64` as `<msys64>/ucrt64/bin` — the shape the installer writes. A corrupt file (invalid JSON) never makes a tool fail; it is simply treated as "not configured".
|
|
225
|
+
|
|
226
|
+
**Precedence**: tool arguments (`binDirs` / `cubeMxRoots`) > environment variables > this config file > built-in defaults; auto-discovered installs are only appended when no argument was given.
|
|
227
|
+
|
|
228
|
+
### Settings panel (GUI)
|
|
229
|
+
|
|
230
|
+
The config file above can also be edited without a terminal: **Settings → STM32 toolchain** in DSH (a browser-side panel shipped with the plugin, same origin, no extra dependency). Three cards:
|
|
231
|
+
|
|
232
|
+
- **Where it is installed**: reads the current config; edit `msys64` / `cubeMxRoot` / extra `binDirs` and save — it writes the same file, and the next tool call picks it up without restarting DSH;
|
|
233
|
+
- **What is missing**: one probe run (it executes each tool's version command, installs nothing) showing the resolved path and version per tool, the `hint` for missing ones, plus four capability badges (build / flash / debug / generate);
|
|
234
|
+
- **Install the toolchain**: first a plan (steps, download size, how PATH and the config file would change), then **a second click to confirm** before anything is installed; progress and the log tail stream into the card. It drives the very same installer as `stm32_env_install`. When the toolchain is already complete, the plan is a single line — "toolchain complete, nothing to install" — instead of seven skipped steps.
|
|
235
|
+
|
|
236
|
+
The panel talks to six `/dsh-stm32/api/*` routes the plugin registers on the host (read config, save config, probe, install plan, install start, install state). The bundle is `lib/client.js`, source in `client/client.js`, copied verbatim by `npm run build` — hand-written plain JS requiring only `react`, no bundler and no runtime dependency. When the host has no `webServer` service (a pure CLI composition) this layer is skipped silently; tools and slash commands are unaffected.
|
|
237
|
+
|
|
238
|
+
### Download cache (register-route template)
|
|
239
|
+
|
|
240
|
+
What the register route needs — CMSIS device headers, the startup file, core headers — is **not vendored into the plugin** (covering any STM32 part would make the package unusable), so it is downloaded on first use into a searchable cache directory and reused from then on:
|
|
241
|
+
|
|
242
|
+
- Location: `DSH_STM32_CACHE` (supports `~`) > `%LOCALAPPDATA%\dsh-stm32\cache`;
|
|
243
|
+
- Index: `index.json` under the cache root records each entry's source URLs, byte counts and license (`THIRD_PARTY_NOTICES.md` is written alongside);
|
|
244
|
+
- Sources: tried in the order `fastly.jsdelivr` → `cdn.jsdelivr` → `raw.githubusercontent` → `ghproxy`; an HTTP error, HTML-looking body or an implausible byte count counts as a failed source;
|
|
245
|
+
- A partial download is deleted outright (a half cache is worse than none); missing or size-mismatched files trigger a re-download on the next run;
|
|
246
|
+
- Visible and removable: `stm32_cache` with `list` / `verify` / `fetch` / `purge`.
|
|
247
|
+
|
|
248
|
+
### Firmware packages (HAL route)
|
|
249
|
+
|
|
250
|
+
Having CubeMX installed does not mean the package for **this particular part** is there — it is not part of the installer and has to be added in the package manager. For the families the plugin can fetch, `stm32_firmware_install` assembles it from two GitHub source archives:
|
|
251
|
+
|
|
252
|
+
- What it downloads: `stm32f1xx-hal-driver` (HAL driver, BSD-3-Clause) + `cmsis-device-f1` (device headers and startup file, Apache-2.0) + five CMSIS core headers — about 2 MB, a few seconds;
|
|
253
|
+
- Why the `STM32CubeF1` source archive is not enough: its HAL and CMSIS device directories are **git submodules**, so the tarball ships them empty — unpacking it yields a package that cannot compile (no startup file, no HAL sources);
|
|
254
|
+
- Where it lands: `<CubeMX root>/dsh-firmware/<package>` by default (a plugin-owned folder next to `Repository`, official packages untouched); only if that root is not writable does it fall back to the user cache. **Do not drop self-made version names into `Repository`** — measured: CubeMX does not recognise that version, silently falls back to the package it knows, and reports a successful generation with stale HAL files;
|
|
255
|
+
- How generation picks it up: `stm32_generate` resolves the package named in the `.ioc` (`ProjectManager.FirmwarePackage`), looking in both `Repository` and `<CubeMX root>/dsh-firmware`, and passes `project setCustomFWPath <package dir>` to the CubeMX script — the only mechanism proven to work, and it leaves no absolute path in the `.ioc`;
|
|
256
|
+
- The assembled package matches the official layout: a six-line `package.xml` (version tags `FW.<family>.<x.y.z>`) and `THIRD_PARTY_NOTICES.md`, with **no manifest or hashes** — CubeMX does not verify provenance either (measured: generating with `setCustomFWPath` copies HAL sources byte-for-byte out of our directory);
|
|
257
|
+
- But "generation succeeded" proves nothing: with a non-existent package name in the `.ioc`, CubeMX prints no error, exits 0 and simply skips copying HAL. So five checks are mandatory (core headers / HAL Inc / HAL Src / device headers / `startup_*.s`), and the installer runs them right after assembling.
|
|
258
|
+
|
|
200
259
|
### Environment variables (optional)
|
|
201
260
|
|
|
202
261
|
| Variable | Purpose | Default |
|
|
203
262
|
| --- | --- | --- |
|
|
204
|
-
| `STM32_BIN_DIRS` | Toolchain directory candidates, `;`-separated; **replaces** the built-in list (auto-discovered dirs are still appended after it) | `
|
|
205
|
-
| `STM32_CUBEMX_ROOT` | STM32CubeMX installation root; **replaces** the built-in list | `
|
|
263
|
+
| `STM32_BIN_DIRS` | Toolchain directory candidates, `;`-separated; **replaces** the built-in list (auto-discovered dirs are still appended after it) | `C:/msys64/ucrt64/bin`, `C:/msys64/mingw64/bin` |
|
|
264
|
+
| `STM32_CUBEMX_ROOT` | STM32CubeMX installation root; **replaces** the built-in list | `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` |
|
|
206
265
|
| `STM32_NO_DISCOVER` | Set to `1` / `true` to turn auto-discovery off (CI, or when you only want the built-in list) | unset = on |
|
|
266
|
+
| `DSH_STM32_CONFIG` | Point the config file elsewhere (several toolchains / project isolation) | `%USERPROFILE%\.dsh-stm32\config.json` |
|
|
267
|
+
| `DSH_STM32_NO_CONFIG` | Set to `1` / `true` to ignore the config file entirely (environment variables only) | unset = read |
|
|
268
|
+
| `DSH_STM32_CACHE` | Download cache root (register-route template etc.), supports `~` | `%LOCALAPPDATA%\dsh-stm32\cache` |
|
|
207
269
|
| `DSH_STM32_E2E_PROJECT` | Project used by hardware e2e runs (with `openocd.cfg` and `build/Debug/*.elf`) | none |
|
|
208
270
|
| `DSH_STM32_E2E_ROOT` | Scratch directory for e2e copies | system temp |
|
|
209
271
|
|
|
@@ -257,22 +319,27 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
|
|
|
257
319
|
| Symptom | Cause and fix |
|
|
258
320
|
| --- | --- |
|
|
259
321
|
| SWD lost after flashing | The firmware generated `__HAL_AFIO_REMAP_SWJ_DISABLE()`. Hold BOOT0 while powering up to enter the system bootloader and reflash, then set SYS back to Serial Wire — `stm32_flash` now blocks this case first |
|
|
260
|
-
| `Error: No device found` / `transfer count mismatch` | Another process holds the probe. Run `/stm32-stop`, then use `stm32_doctor` to inspect openocd / gdb processes and port 3333 |
|
|
322
|
+
| `Error: No device found` / `transfer count mismatch` | Another process holds the probe. Run `/stm32-stop`, then use `stm32_doctor` to inspect openocd / gdb processes and port 3333. Reading registers while a debug session is open no longer hits this: `stm32_regs_read` reuses the session's openocd instead of starting a second one |
|
|
323
|
+
| Reading registers with a live session shows a `gdb-multiarch … target extended-remote 127.0.0.1:3333` `report.command` | That is the normal "reuse" shape: while `stm32_debug_session` is alive, `stm32_regs_read` drives the session's own gdb connection with `print/x $pc` and `print/x *(unsigned int *)0x…`, then `monitor resume` and detach; the first note reads "reusing the openocd of the debug session (port N), not starting another". Only without a session does it start its own openocd. Older builds failed here with `CMSIS-DAP transfer count mismatch: expected N, got M` |
|
|
261
324
|
| Build "succeeds" but the old firmware runs | The project was copied or renamed with `build/` included: the CMakeCache directory no longer matches, yet ninja still exits 0. `stm32_build` treats that as a failure; clean or delete `build/Debug` as prompted |
|
|
325
|
+
| A tool answers "missing arm-none-eabi-gcc …, X was not started" | That is the pre-flight gate (`envCheck` defaults to `block`) doing its job, not a bug: it is cheaper than discovering the problem halfway through. Answer "install", and the model runs `stm32_env_install` for a plan; after you confirm, the toolchain is installed and the config written — **the next call works without a restart**. Run `/stm32-env` for the whole picture, or pass `envCheck: "warn"` (continue with a warning) / `"off"` (skip the check) |
|
|
262
326
|
| `stm32_doctor` cannot find gcc / openocd | First read the "searched ..." list and the auto-discovery line in the doctor notes / error; if it is installed elsewhere, set `STM32_BIN_DIRS` or pass `binDirs`. **If you do not know what to install, run `stm32_env_probe` first**: every missing component carries `impact` (what stops working), `install` (recommended way, easiest first) and `verify` (self-check after installing), while the top-level `recommendations` gives the install order and offers to install for you |
|
|
263
|
-
| `stm32_generate` feels stuck |
|
|
327
|
+
| `stm32_generate` feels stuck | The first run (cold start, no cache) legitimately takes 3.5–4 minutes; later runs are skipped (<1 s) while the `.ioc` and outputs are unchanged. It runs as a background job by default — watch it with `job_output`, or pass `foreground: true`. Check `skipped` in the result and the reason in the notes to see whether the cache hit |
|
|
328
|
+
| It regenerates for 3 minutes even though nothing changed | The cache key covers the CubeMX `size:mtime` and every output hash, so swapping CubeMX, editing generated files or changing the layout invalidates it. Read the reason in the notes, or delete `.dsh-stm32/generate-cache.json` |
|
|
329
|
+
| Generate got faster but the CubeMX GUI no longer lists expansion packs | With `thirdpartyPacks: "auto"` the `thirdparties/pdsc` directory is parked as `pdsc.dsh-parked` when no pack is needed and restored after the run. Pass `thirdpartyPacks: "keep"` while picking packs by hand in the CubeMX GUI |
|
|
330
|
+
| The notes say the local pack index has no such pack | An X-CUBE pack the project needs is not installed here (the decision matches `Mcu.ThirdParty<k>` in the `.ioc` against the built-in catalog by name). Install it in the CubeMX *Manage embedded software packages* dialog, then generate again. This note also shows up in **failed** generate reports (a timeout or a CubeMX error still carries the notes — read them before guessing). The catalog is a snapshot: after installing new packs, rerun `node scripts/gen-xcube-catalog.mjs` (an older catalog only fails to recognise new packs, it never wrongly decides the index is unnecessary) |
|
|
264
331
|
| `stm32_code_patch` says the block does not exist | `main.c` uses short labels (`PV` = private variables, `PFP` = prototypes, `2` = init before while, `3` = loop body); the error lists every available label — copy one from there |
|
|
265
332
|
|
|
266
333
|
## Development and testing
|
|
267
334
|
|
|
268
335
|
```powershell
|
|
269
336
|
npm run build # tsc -> lib/ (lib/ is committed: rebuild before you commit)
|
|
270
|
-
npm test #
|
|
337
|
+
npm test # 24 offline suites, 309 cases; no board, CubeMX, or toolchain needed
|
|
271
338
|
```
|
|
272
339
|
|
|
273
340
|
CI (`.github/workflows/ci.yml`) runs `npm ci → build → check that the committed lib/ matches src/ → npm test` on every push and PR (windows-latest).
|
|
274
341
|
|
|
275
|
-
A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that need the real firmware package are skipped: CI reports **
|
|
342
|
+
A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that need the real firmware package are skipped: CI reports **307 passed + 2 skipped**, while a developer machine runs all 309. The offline suites only read the bundled [`test/fixtures/`](test/fixtures/README.md); the session cases build a fake toolchain directory with `fakeBinDirs()` (empty placeholder files for openocd / gdb), so nothing depends on what is installed locally.
|
|
276
343
|
|
|
277
344
|
Hardware e2e writes to the board and needs a project you point it at:
|
|
278
345
|
|
|
@@ -288,9 +355,9 @@ See the [development notes](docs/development-notes.md) for the suite breakdown a
|
|
|
288
355
|
```text
|
|
289
356
|
src/
|
|
290
357
|
index.ts plugin entry (name / inject / apply)
|
|
291
|
-
tools/ the
|
|
358
|
+
tools/ the 19 tools, L3 (parameter schema + output contract + rendering)
|
|
292
359
|
engine/ pure logic and workflows (generate / build / flash / debug / ioc / scaffold …)
|
|
293
|
-
commands/register.ts the
|
|
360
|
+
commands/register.ts the 6 slash commands
|
|
294
361
|
skill/stm32-workflow.ts the SKILL shipped with the plugin
|
|
295
362
|
data/ paths and chip data (paths are data, not logic)
|
|
296
363
|
templates/scaffold/ project template snapshot (CMake / .ld / .vscode / .ioc)
|