dsh-stm32 0.0.0-stage → 0.1.0
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/LICENSE +21 -0
- package/README.md +308 -2
- package/README_EN.md +308 -0
- package/cordis.patch.yml +6 -0
- package/docs/development-notes.md +736 -0
- package/docs/dsh-stm32-plugin-/350/247/204/346/240/274.md +673 -0
- package/lib/commands/register.js +218 -0
- package/lib/data/chips.js +36 -0
- package/lib/data/search-roots.js +240 -0
- package/lib/engine/build.js +321 -0
- package/lib/engine/code-patch.js +157 -0
- package/lib/engine/debug-session.js +255 -0
- package/lib/engine/debug.js +281 -0
- package/lib/engine/doctor.js +157 -0
- package/lib/engine/flash.js +222 -0
- package/lib/engine/generate-script.js +73 -0
- package/lib/engine/generate.js +350 -0
- package/lib/engine/ioc-plan.js +430 -0
- package/lib/engine/ioc.js +142 -0
- package/lib/engine/layout.js +48 -0
- package/lib/engine/probe.js +245 -0
- package/lib/engine/regs.js +197 -0
- package/lib/engine/scaffold.js +184 -0
- package/lib/engine/subprocess-runner.js +192 -0
- package/lib/engine/usercode-merge.js +123 -0
- package/lib/index.js +72 -0
- package/lib/skill/stm32-workflow.js +30 -0
- package/lib/tools/build.js +170 -0
- package/lib/tools/code-patch.js +86 -0
- package/lib/tools/debug-session.js +187 -0
- package/lib/tools/debug.js +149 -0
- package/lib/tools/doctor.js +159 -0
- package/lib/tools/env-probe.js +238 -0
- package/lib/tools/flash.js +124 -0
- package/lib/tools/generate.js +203 -0
- package/lib/tools/ioc-apply.js +108 -0
- package/lib/tools/ioc-inspect.js +201 -0
- package/lib/tools/ioc-plan.js +151 -0
- package/lib/tools/project-create.js +90 -0
- package/lib/tools/regs.js +120 -0
- package/lib/types.js +8 -0
- package/package.json +60 -4
- package/templates/scaffold/CMakeLists.txt +68 -0
- package/templates/scaffold/CMakePresets.json +45 -0
- package/templates/scaffold/Core/Src/syscalls.c +244 -0
- package/templates/scaffold/Core/Src/sysmem.c +87 -0
- package/templates/scaffold/STM32F103XX_FLASH.ld +249 -0
- package/templates/scaffold/cmake/gcc-arm-none-eabi.cmake +43 -0
- package/templates/scaffold/cmake/starm-clang.cmake +65 -0
- package/templates/scaffold/cmake/stm32cubemx/CMakeLists.txt +86 -0
- package/templates/scaffold/cmake/user/CMakeLists.txt +4 -0
- package/templates/scaffold/demo.ioc +113 -0
- package/templates/scaffold/vscode/c_cpp_properties.json +12 -0
- package/templates/scaffold/vscode/launch.json +47 -0
- package/templates/scaffold/vscode/settings.json +16 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 dsh-stm32 contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,309 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-stm32
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> 让 DSH 接管 STM32F103C8T6 的整条开发链:探测工具链 → 建工程 → 改 .ioc → 生成代码 → 编译 → 调试 → 烧录。
|
|
4
|
+
|
|
5
|
+
**English:** STM32F103C8T6 toolchain for DeepSeek Harness — probe the toolchain, scaffold a CMake project, edit .ioc as a transaction, build, flash without starting a debug session, and debug only when you ask for it.
|
|
6
|
+
|
|
7
|
+
[English](./README_EN.md) · [快速开始](#快速开始最小验证空目录到灯在闪) · [功能一览](#功能一览) · [工具参考](#工具参考) · [斜杠命令](#斜杠命令) · [设计要点](#设计要点) · [已知限制](#已知限制) · [排错](#排错) · [规格书](docs/dsh-stm32-plugin-规格.md)
|
|
8
|
+
|
|
9
|
+
[](https://github.com/JingYu-er/dsh-stm32)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](#已知限制)
|
|
12
|
+
[](#已知限制)
|
|
13
|
+
[](https://github.com/JingYu-er/dsh-stm32/releases)
|
|
14
|
+
|
|
15
|
+
这是一个 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **插件**:注册 15 个工具、5 条斜杠命令和 1 个随插件下发的 SKILL,让模型能直接探测工具链、建cubemx cmake工程、改 `.ioc`、跑 CubeMX、编译、烧录和调试,烧完再把寄存器里的状态读回来确认——实现更彻底的面向DSH硬件编程。
|
|
16
|
+
|
|
17
|
+
## 为什么需要它
|
|
18
|
+
|
|
19
|
+
大多数「让 AI 帮忙写 STM32」的做法停在代码层:它给你一段 `main.c`,至于这段代码能不能编译、烧进去灯到底闪没闪,还是你自己开 CubeMX、切终端、按 F5。**模型看不到板子,也就没法对自己的代码负责。**
|
|
20
|
+
|
|
21
|
+
这个插件把硬件侧也接到 DSH 上:`.ioc` 能读能改(事务 + 回滚)、代码落在 `USER CODE` 块里、生成和编译能拿到真实的报错行、烧录是一条**不经过调试器**的独立路径、烧完还能用寄存器把状态读回来。每一步都返回结构化证据(`planId`、`file:line:col`、`Verified OK`、`GPIOC_ODR` 的 bit13),模型据此决定下一步,而不是猜。
|
|
22
|
+
|
|
23
|
+
这就是「更彻底的面向 DSH 硬件编程」:**模型不只是写代码——它能把代码烧进板子,再把板子上的状态从寄存器里读回来跟自己的预期对账。**
|
|
24
|
+
|
|
25
|
+
| 环节 | 以前(手写 + CubeMX GUI) | 现在(DSH 全流程) |
|
|
26
|
+
| --- | --- | --- |
|
|
27
|
+
| 建工程 | GUI 里点时钟树、引脚、工程设置,生成 CMake,再手写 `launch.json` | 一句话:`stm32_project_create` 2 s 出模板工程(与 GUI 产物逐字节一致),`.vscode` 里两份配置已就位 |
|
|
28
|
+
| 改配置 | GUI 里改完重新生成,祈祷 USER CODE 不丢 | `stm32_ioc_plan` 先给 diff(不动源文件)→ 你点头 → `stm32_ioc_apply` 带 SHA 校验、备份、失败回滚 |
|
|
29
|
+
| 写代码 | 整文件编辑,一不小心写进生成区,重新生成就没了 | `stm32_code_patch` 只写 `USER CODE` 块,块外逐字节不动 |
|
|
30
|
+
| 编译 | 使用keil编译或使用vscode插件编写cmake文件 | DSH 通过/stm32-build [dir] [--clean] 自动编译 |
|
|
31
|
+
| 烧录 | 使用keil烧录或自己写 `tasks.json` 调 openocd | DSH 通过/stm32-debug [dir]自动烧录 |
|
|
32
|
+
| 验证 | 断点调试,自己查看寄存器的值 | 烧完用 `stm32_regs_read` 把状态读回来:`GPIOC_ODR` 两次采样看计数器递增,`AFIO_MAPR` 确认 SWD 没被固件关掉 |
|
|
33
|
+
| 调试 | `F5` + 手动下断点、看完再关会话 | `stm32_debug_run` 停在 `main` 抓一次现场即释放;要连续调才开 `stm32_debug_session`,空闲自动关 |
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
## 安装
|
|
37
|
+
|
|
38
|
+
### 前置条件
|
|
39
|
+
|
|
40
|
+
| 依赖 | 用途 | 缺了会怎样 |
|
|
41
|
+
| --- | --- | --- |
|
|
42
|
+
| dsh(能加载 bundle 层) | 宿主 | 插件不会被加载 |
|
|
43
|
+
| Node ≥ 20 | 构建 / 测试 | `npm run build` 失败 |
|
|
44
|
+
| `arm-none-eabi-gcc`、`arm-none-eabi-gdb`(或 `gdb-multiarch`) | 编译 / 调试 | `stm32_doctor` 逐个提示缺哪个、去哪装 |
|
|
45
|
+
| `openocd` | 烧录 / 调试 | 烧录与调试不可用,只读工具照常 |
|
|
46
|
+
| `cmake` + `ninja` | 构建 | `stm32_build` 失败 |
|
|
47
|
+
| STM32CubeMX(含内置 JRE) | `stm32_generate`、`stm32_project_create` | 生成类工具不可用,其余照常 |
|
|
48
|
+
| STM32Cube 固件包 F1(随 CubeMX 装) | 建骨架时抄 Drivers | 报「找不到固件包」 |
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
### 安装(推荐:一条命令)
|
|
52
|
+
|
|
53
|
+
```powershell
|
|
54
|
+
dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`dsh plugin` 做的事就是在 profile 目录里跑 `pnpm add`。装完它会把 `dsh-stm32` 写进该 profile 的 `dsh.profile.bundles`,重启 dsh 即生效(把 `desktop` 换成 `web` 就装到 web profile)。
|
|
58
|
+
|
|
59
|
+
装完确认:`dsh plugin --profile desktop why dsh-stm32` 应显示 `0.1.0`;重启后 `/stm32-doctor` 有输出。
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
**卸载**:`dsh plugin --profile desktop remove dsh-stm32`,重启 dsh。
|
|
63
|
+
|
|
64
|
+
### 源码安装(要改代码时)
|
|
65
|
+
|
|
66
|
+
```powershell
|
|
67
|
+
git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
68
|
+
cd dsh-stm32
|
|
69
|
+
npm install --no-audit --no-fund # 只装 typescript
|
|
70
|
+
npm run build # tsc -> lib/(提交前必须跑)
|
|
71
|
+
npm test # 可选:80 个离线用例,不需要板子
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
挂进 dsh 的 profile——**改代码时必须用 `link:`,不要用 `file:`**:
|
|
75
|
+
|
|
76
|
+
```powershell
|
|
77
|
+
cd "$env:USERPROFILE\.dsh\profiles\desktop"
|
|
78
|
+
pnpm add "link:D:\path\to\dsh-stm32"
|
|
79
|
+
|
|
80
|
+
# 然后在同一目录的 package.json 里,把 "dsh-stm32" 加到 dsh.profile.bundles 数组末尾
|
|
81
|
+
# 最后重启 dsh(bundle 层只在进程启动时加载)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
> **为什么改代码必须 `link:`**:pnpm 在 `nodeLinker: hoisted` 下会把 `file:` 依赖复制成真实目录,之后你重新 `tsc` 出的 `lib/` 宿主读不到——表现为"改完代码、重启还是旧行为"。用 `link:` 时 `lib/` 是实时读的,但**仍然要重启 dsh** 才会重新加载插件。`github:` / npm 装的是拷贝,改代码后要重新构建、重新安装。
|
|
85
|
+
|
|
86
|
+
## 快速开始:最小验证(空目录到灯在闪)
|
|
87
|
+
|
|
88
|
+
下面这条链在真板上跑通过(A1 验收,2026-10-22),全程由模型调用工具完成。注意它只是**最小验证**——每一步用的都是同一套工具,闪灯只是最省的样例:
|
|
89
|
+
|
|
90
|
+
| 步 | 做什么 | 工具 | 实测耗时 |
|
|
91
|
+
| --- | --- | --- | --- |
|
|
92
|
+
| 1 | 体检:工具链、被占用的探针、端口、`.elf`、`.ioc` 告警 | `stm32_doctor` | ~2 s |
|
|
93
|
+
| 2 | 空目录建 CMake 工程骨架(14 个模板文件 + 629 个固件文件 + 配好 SWD 的 `.ioc`) | `stm32_project_create` | ~2 s |
|
|
94
|
+
| 3 | 按 `.ioc` 无头跑 CubeMX,产物落到 `Core/` | `stm32_generate` | 61–77 s |
|
|
95
|
+
| 4 | 编译(首次自动 `cmake --preset`) | `stm32_build` | 配置 ~5 s + 编译 3 s |
|
|
96
|
+
| 5 | **只烧录**:program + verify + reset | `stm32_flash` | 2.1–2.6 s |
|
|
97
|
+
| 6 | 读回 `GPIOC_ODR`,确认状态确实在翻 | `stm32_regs_read` | 0.4–1.3 s |
|
|
98
|
+
|
|
99
|
+
模型侧就是一句话:「在 `D:\work\blink` 建一个 STM32F103C8T6 的闪灯工程,编译并烧进去」。想自己敲就:
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
/stm32-doctor # 开工前体检
|
|
103
|
+
/stm32-build # 编译,打印内存占用与错误
|
|
104
|
+
/stm32-flash # 只烧录,不进调试会话
|
|
105
|
+
/stm32-debug # 烧录 + 停在 main
|
|
106
|
+
/stm32-stop # 关掉调试会话,把探针还给 VS Code
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### 这只是最小验证,不是能力上限
|
|
110
|
+
|
|
111
|
+
闪灯是这条链的**最小 smoke test**:它把「建工程 → 生成 → 编译 → 烧录 → 读回状态」每一步走了一遍,用的都是同一套工具,没有一步是闪灯专用的。真实项目走的是同一条链,区别只在 `.ioc` 里多几个外设、`USER CODE` 多几个块、代码更长:
|
|
112
|
+
|
|
113
|
+
| 完整项目里要做的事 | 走哪条路径 | 上板实测情况 |
|
|
114
|
+
| --- | --- | --- |
|
|
115
|
+
| 外设配置:GPIO / 定时器 / USART / I2C / SPI / ADC / DMA / 中断 | `stm32_ioc_plan` 改 `.ioc`(GPIO 按芯片引脚表校验,外设写 `Mcu.IP*` / `Periph.*` 键)→ `stm32_ioc_apply` → `stm32_generate` | GPIO、时钟、SWD 已实测;其他外设同一机制,未逐个实测 |
|
|
116
|
+
| 新增外设后补 HAL 源 | 在 `cmake/stm32cubemx/CMakeLists.txt` 的 `STM32_Drivers_Src` 里加 `stm32f1xx_hal_<外设>.c`,或写进 `cmake/user/CMakeLists.txt` | **这一步要手工补**:插件只落位 `Src/` 与 `Inc/`,CubeMX 生成的 `cmake/**` 不搬 |
|
|
117
|
+
| 多源文件、自己写的模块 | 写进 `cmake/user/CMakeLists.txt`,模板已留好位置 | 位置就位;未单独实测 |
|
|
118
|
+
| 业务代码 | `stm32_code_patch` 按块写入,重新生成时按标签搬回 | 已实测(append / replace / 标签写错会列出全部可用标签) |
|
|
119
|
+
| 调参数、改时钟 | `.ioc` 事务:先 diff → SHA 校验 → 备份 → 失败回滚 | 已实测 |
|
|
120
|
+
| 烧完确认外设真的在动 | `stm32_regs_read` 读任意外设寄存器(`TIM2_CNT`、`USART1_SR`、`ADC1_DR`…),或 `stm32_debug_eval` 读变量 | 按物理地址读寄存器已实测(`GPIOC_ODR` / `AFIO_MAPR`) |
|
|
121
|
+
| 出问题要看现场 | `stm32_debug_run` 停在 `main` 抓一次;要连续调就开 `stm32_debug_session` + `stm32_debug_eval` | 已实测(停在 `main () at main.c:67`) |
|
|
122
|
+
|
|
123
|
+
所以闪灯是验收用的最小样例,不是这套工具的能力上限:**它覆盖的是整条工程链,而不是一个 demo。** 真正的边界在[已知限制](#已知限制)里——芯片只支持 F103C8T6、宿主只在 Windows 上验证、探针默认 CMSIS-DAP,以及上面那条「新增外设要手工补 HAL 源」。外设种类本身不受工具限制:`.ioc` 里配得出来的,生成、编译、烧录、读回都走同一条链;只是除闪灯外还没有逐项上板实测,正式开项目前先跑一遍 `stm32_doctor`。
|
|
124
|
+
|
|
125
|
+
## 功能一览
|
|
126
|
+
|
|
127
|
+
| 能力 | 提供方式 |
|
|
128
|
+
| --- | --- |
|
|
129
|
+
| 环境体检 | `stm32_env_probe`(只读)、`stm32_doctor`(工具链 + 探针占用 + 端口 + 工程告警) |
|
|
130
|
+
| 从零建工程 | `stm32_project_create`:模板快照 + 固件包 Drivers,与 CubeMX GUI 新建的工程逐字节一致 |
|
|
131
|
+
| `.ioc` 事务 | `stm32_ioc_inspect`(只读解析)→ `stm32_ioc_plan`(算 diff,不写盘)→ `stm32_ioc_apply`(SHA 校验 + 备份 + 回滚) |
|
|
132
|
+
| 只改 USER CODE | `stm32_code_patch`:只写 `/* USER CODE BEGIN X */` 与 `END X` 之间,块外逐字节不动 |
|
|
133
|
+
| 生成代码 | `stm32_generate`:无头 CubeMX + 按 ST 结构落位 + USER CODE 按标签搬回 |
|
|
134
|
+
| 编译 | `stm32_build`:构建目录与 `.elf` 自动推断、错误去重、链接后解析 RAM/FLASH 占用 |
|
|
135
|
+
| 烧录 | `stm32_flash`:openocd `program verify reset exit`,烧完释放探针;烧前检查 `.ioc` 是否开了 Serial Wire |
|
|
136
|
+
| 调试 | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
|
|
137
|
+
| 验证"真的在跑" | `stm32_regs_read`:按物理地址把任意外设寄存器读回来,halt 读值后 `resume`,不复位芯片 |
|
|
138
|
+
| 给模型的工作纪律 | 随插件下发 SKILL `stm32-workflow`(只改 USER CODE、不动生成区、烧录与调试分开、结论要带寄存器证据) |
|
|
139
|
+
|
|
140
|
+
## 工具参考
|
|
141
|
+
|
|
142
|
+
### 环境与工程
|
|
143
|
+
|
|
144
|
+
| 工具 | 作用 |
|
|
145
|
+
| --- | --- |
|
|
146
|
+
| `stm32_env_probe` | 探测 gcc / gdb / openocd / cmake / ninja / CubeMX / JRE 的路径与版本;缺什么会写清影响(编译不了 / 烧不了 / 调不了 / 建不了工程)、推荐装法(含可粘贴的 pacman / winget 命令)、装完自检命令,并给 `capabilities`(四项能力是否可用)与 `recommendations`(安装顺序 + 要不要我帮你装)。只读、可重复调 |
|
|
147
|
+
| `stm32_doctor` | 一次回答三件事:工具链齐不齐、探针被谁占(`openocd.exe` / gdb 进程 / 3333 端口)、这个工程能不能烧 |
|
|
148
|
+
| `stm32_project_create` | 空目录 → 完整 CMake 工程(含 `.vscode` 里"① 只烧录 / ② 烧录并调试"两份配置)。目标目录非空默认拒绝,`overwrite: true` 才覆盖 |
|
|
149
|
+
|
|
150
|
+
### .ioc:只读与事务
|
|
151
|
+
|
|
152
|
+
| 工具 | 作用 |
|
|
153
|
+
| --- | --- |
|
|
154
|
+
| `stm32_ioc_inspect` | 解析 MCU 型号、引脚/信号/标签、外设与中断、时钟树、工程设置;会报「没开 Serial Wire 会生成 `SWJ_DISABLE`」这类致命风险 |
|
|
155
|
+
| `stm32_ioc_plan` | 改 `.ioc` 的第一步:算出逐键 diff 与源 SHA-256,返回 `planId`,**不动源文件**。支持改键、删键、按引脚表加 GPIO、一键补 Serial Wire |
|
|
156
|
+
| `stm32_ioc_apply` | 必须带 `planId`;写盘前再核 SHA(中途被手改就拒绝),备份后原子替换,写完重新解析校验,不过自动回滚。支持 `rollbackFrom` |
|
|
157
|
+
|
|
158
|
+
### 代码与构建
|
|
159
|
+
|
|
160
|
+
| 工具 | 作用 |
|
|
161
|
+
| --- | --- |
|
|
162
|
+
| `stm32_code_patch` | 只在 `USER CODE` 块内 replace/append;块外字节(含 CRLF)原样保留;写前备份、临时文件 + rename 原子替换。标签写错会把该文件所有可用标签列给你 |
|
|
163
|
+
| `stm32_generate` | 无头跑 `java -jar STM32CubeMX.exe -q`,成功后落位到 `Core/Src`、`Core/Inc`,旧文件的 USER CODE 按标签搬进新内容。默认后台 job |
|
|
164
|
+
| `stm32_build` | `cmake --build`,构建目录从 `CMakePresets.json` 与 `build/*/CMakeCache.txt` 推断;首次构建自动 configure;会拦住"CMakeCache 目录不一致但 ninja 退出码 0"的假成功 |
|
|
165
|
+
|
|
166
|
+
### 烧录与调试
|
|
167
|
+
|
|
168
|
+
| 工具 | 作用 |
|
|
169
|
+
| --- | --- |
|
|
170
|
+
| `stm32_flash` | **烧录**:openocd `program verify reset exit`,不建调试会话、不停 `main`。烧前读 `.ioc`,调试口没开就拒绝(见 [设计要点](#设计要点)) |
|
|
171
|
+
| `stm32_debug_run` | 起 openocd + gdb,`break main` → `continue` → 抓 pc/sp/lr/bt/locals → `reset run` + `detach`,不写 Flash、不常驻 |
|
|
172
|
+
| `stm32_debug_session` | 常驻 openocd 会话(`.elf` 自动解析),空闲 90 s 自动关、硬上限 10 min |
|
|
173
|
+
| `stm32_debug_eval` | 在会话里执行 gdb 命令或读表达式(如 `g_led_blink_count`),读完立刻 `resume` + `detach` |
|
|
174
|
+
| `stm32_debug_stop` | 立刻释放探针,幂等 |
|
|
175
|
+
| `stm32_regs_read` | 读 `GPIOC_ODR`、`AFIO_MAPR` 等物理地址;收尾用 `resume` 而不是 `reset run`,避免读一眼就把固件状态清零 |
|
|
176
|
+
|
|
177
|
+
## 斜杠命令
|
|
178
|
+
|
|
179
|
+
工具是给模型调的;你要自己动手时用命令,一条命令一个动作,不经过模型决策。
|
|
180
|
+
|
|
181
|
+
| 命令 | 做什么 | 会不会动板子 |
|
|
182
|
+
| --- | --- | --- |
|
|
183
|
+
| `/stm32-doctor` | 体检:工具链、被占用的调试进程、端口、`.elf`、`.ioc` 告警 | 否 |
|
|
184
|
+
| `/stm32-build [dir] [--clean]` | 编译,打印内存占用 / `.elf` / 错误 | 否 |
|
|
185
|
+
| `/stm32-flash [dir]` | **烧录**:program + verify + reset,不建调试会话、不下断点 | 是 |
|
|
186
|
+
| `/stm32-debug [dir]` | **烧录 + 调试**:烧完停到 `main`,会话保留(空闲 3 分钟 / 上限 10 分钟,本轮结束也会自动关) | 是 |
|
|
187
|
+
| `/stm32-stop` | 关掉 `/stm32-debug` 开的会话,把探针还给 VS Code | 否 |
|
|
188
|
+
|
|
189
|
+
`[dir]` 省略时用当前会话的工作目录。
|
|
190
|
+
|
|
191
|
+
## 设计要点
|
|
192
|
+
|
|
193
|
+
- **烧录与调试是两条路。** `stm32_flash` 只用 openocd 的 `program/verify/reset/exit`,成功证据是日志里出现 `** Programming Finished **` 与 `** Verified OK **`,不是"没报错"。
|
|
194
|
+
- **只写 USER CODE。** 改逻辑用 `stm32_code_patch`;`stm32_generate` 重新生成时按标签把旧内容搬回新文件,所以手改生成区或整文件重写在重新生成后都会丢。
|
|
195
|
+
- **`.ioc` 是事务。** `plan` 只算 diff 出 `planId`,`apply` 才写盘,写前核 SHA、写后重新解析、失败回滚。
|
|
196
|
+
- **烧前守卫。** 如果 `.ioc` 的 SYS 调试口不是 Serial Wire(PA13/PA14 缺失或被设成 `No_Debug`),CubeMX 会生成 `__HAL_AFIO_REMAP_SWJ_DISABLE()`——烧进去 SWD 立刻失联,只能 BOOT0 救砖。这种工程 `stm32_flash` 直接拒绝;确实要烧得显式传 `allowNoDebug: true`。
|
|
197
|
+
- **探针只有一块。** 烧录、调试、后台会话同一时刻只能有一个;`build` / `flash` / `debug_run` / `generate` 开跑前会先把占着探针的会话关掉。
|
|
198
|
+
|
|
199
|
+
## 配置
|
|
200
|
+
|
|
201
|
+
### 环境变量(可选)
|
|
202
|
+
|
|
203
|
+
| 变量 | 作用 | 默认 |
|
|
204
|
+
| --- | --- | --- |
|
|
205
|
+
| `STM32_BIN_DIRS` | 工具链目录候选,`;` 分隔,**整份替换**内置列表(之后的自动发现仍追加在尾部) | `D:/app/msys64/ucrt64/bin`、`C:/msys64/ucrt64/bin`、`C:/msys64/mingw64/bin` |
|
|
206
|
+
| `STM32_CUBEMX_ROOT` | STM32CubeMX 安装根目录,**整份替换**内置列表 | `D:/app/STM32CubeMX`、`C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` |
|
|
207
|
+
| `STM32_NO_DISCOVER` | 设为 `1` / `true` 关掉下面的自动发现(CI、只想用内置列表时) | 不设 = 开着 |
|
|
208
|
+
| `DSH_STM32_E2E_PROJECT` | 真机 e2e 用的工程(含 `openocd.cfg` 与 `build/Debug/*.elf`) | 无 |
|
|
209
|
+
| `DSH_STM32_E2E_ROOT` | e2e 临时副本目录 | 系统临时目录 |
|
|
210
|
+
|
|
211
|
+
也可以按调用传参:烧录/调试类工具都接受 `binDirs`、`elfPath`、`buildDir`、`configFile`、`adapterSpeed`;生成/建工程类接受 `cubeMxRoots`、`firmwarePackage`。
|
|
212
|
+
|
|
213
|
+
**自动发现(换台机器通常不用配任何变量)。** 没给 `binDirs` / `STM32_BIN_DIRS` 时,插件会扫一遍常见位置,把找到的目录**追加**在候选列表尾部:
|
|
214
|
+
|
|
215
|
+
- 工具链:`<盘>/msys64`、`<盘>/msys2`、`<盘>/app/msys64`、`<盘>/tools/msys64`、`%LOCALAPPDATA%/Programs/msys64` 下的 `ucrt64/bin`、`mingw64/bin`、`clang64/bin`(该目录里得真有 `arm-none-eabi-gcc.exe` / `openocd.exe` / `cmake.exe`)。
|
|
216
|
+
- CubeMX:注册表 `HKLM|HKCU\SOFTWARE\STMicroelectronics\STM32CubeMX` 的 `InstallDir`、`...\Uninstall\STM32CubeMX` 的 `InstallLocation`,以及 `<盘>/`、`<盘>/app`、`<盘>/tools`、`Program Files\STMicroelectronics\STM32Cube`、`%LOCALAPPDATA%/Programs` 下的 `STM32CubeMX`(要求 `STM32CubeMX.exe` 与 `jre/bin/java.exe` 都在)。
|
|
217
|
+
|
|
218
|
+
扫一次约 1 s,进程内缓存。**用工具参数点名 `binDirs` / `cubeMxRoots` 时不追加**——你指哪儿就用哪儿,免得"我明明指定了"变成假的。环境变量里的路径会先净化(去引号、反斜杠转正斜杠、折叠重复斜杠),不用怕 `setx "D:\app\msys64\ucrt64\bin"` 带进来的引号。找不到工具时,报错和 `stm32_doctor` 的 notes 都会列出「查过哪些目录」。
|
|
219
|
+
|
|
220
|
+
### openocd.cfg(工程内,优先于内置回退)
|
|
221
|
+
|
|
222
|
+
CMSIS-DAP(默认):
|
|
223
|
+
|
|
224
|
+
```text
|
|
225
|
+
source [find interface/cmsis-dap.cfg]
|
|
226
|
+
source [find target/stm32f1x.cfg]
|
|
227
|
+
adapter speed 4000
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
ST-Link(换成你的探针):
|
|
231
|
+
|
|
232
|
+
```text
|
|
233
|
+
source [find interface/stlink.cfg]
|
|
234
|
+
transport select hla_swd
|
|
235
|
+
source [find target/stm32f1x.cfg]
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
没有 `openocd.cfg` 时回退 `interface/cmsis-dap.cfg` + `target/stm32f1x.cfg`。ST-Link 用户请把上面第二段写进工程根目录的 `openocd.cfg`。
|
|
239
|
+
|
|
240
|
+
### .ioc 的两个硬要求
|
|
241
|
+
|
|
242
|
+
1. **SYS 调试口必须是 Serial Wire**(PA13 = `SYS_JTMS-SWDIO`、PA14 = `SYS_JTCK-SWCLK`);没有就用 `stm32_ioc_plan` 的 `serialWire: true` 补上。
|
|
243
|
+
2. **`ProjectManager.KeepUserCode=true`**;否则重新生成时 USER CODE 不会被保留。
|
|
244
|
+
|
|
245
|
+
## 已知限制
|
|
246
|
+
|
|
247
|
+
| 限制 | 说明 | 有没有办法 |
|
|
248
|
+
| --- | --- | --- |
|
|
249
|
+
| 只在 **Windows** 上验证 | `stm32_generate` 依赖 `<CubeMX>/STM32CubeMX.exe` + `jre/bin/java.exe`,Linux/macOS 上的 CubeMX 不是这个形态 | 暂无;烧录/调试/读寄存器在 Linux 上若 openocd 与 gdb 齐全可能可用,但未验证 |
|
|
250
|
+
| 只支持 **STM32F103C8T6** | 引脚表、`.ioc` 引脚校验、链接脚本模板都按 64 KiB Flash / 20 KiB RAM 的 C8T6 写 | 换芯片要改 `src/data/chips.ts` 与 `templates/` |
|
|
251
|
+
| 默认探针是 **CMSIS-DAP** | 没有 `openocd.cfg` 时回退 cmsis-dap | 用 `openocd.cfg` 换 `interface/stlink.cfg`(见上) |
|
|
252
|
+
| 新增外设要**手工补 HAL 源** | 插件只落位 CubeMX 的 `Src/` 与 `Inc/`(→ `Core/Src`、`Core/Inc`),CubeMX 生成的 `cmake/stm32cubemx/CMakeLists.txt` 不搬;开了定时器/串口/ADC 之后要自己把 `stm32f1xx_hal_<外设>.c` 加进源清单 | 改工程里 `cmake/stm32cubemx/CMakeLists.txt` 的 `STM32_Drivers_Src`,或写进 `cmake/user/CMakeLists.txt` 的 `target_sources` |
|
|
253
|
+
| 生成/建工程需要 **CubeMX + F1 固件包** | 固件包版本默认 `STM32Cube_FW_F1_V1.8.7` | 换版本传 `firmwarePackage` |
|
|
254
|
+
| 未在别人的机器上验证 | 本机:Windows 10 + MSYS2 UCRT64 + DAPLink + 蓝丸;其余组合靠反馈 | 遇到问题请附 `stm32_doctor` 的完整输出开 issue |
|
|
255
|
+
|
|
256
|
+
## 排错
|
|
257
|
+
|
|
258
|
+
| 现象 | 原因与处理 |
|
|
259
|
+
| --- | --- |
|
|
260
|
+
| 烧完连不上、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 端口 |
|
|
262
|
+
| 编译"成功"但跑的是旧固件 | 复制或改名过带 `build/` 的工程:CMakeCache 里的目录对不上,ninja 仍退出 0。`stm32_build` 会判失败;按提示 clean 或删 `build/Debug` |
|
|
263
|
+
| `stm32_doctor` 说找不到 gcc / openocd | 先看 doctor 的 notes / 报错里的「查过 …」列表与自动发现结果;装上后还找不到就设 `STM32_BIN_DIRS` 或给工具传 `binDirs`。**不知道装什么就先跑 `stm32_env_probe`**:每条缺失项都带 `impact`(缺了影响哪些功能)、`install`(推荐装法,第一条最省事)、`verify`(装完自检),顶层 `recommendations` 给出安装顺序,还会问要不要帮你装 |
|
|
264
|
+
| `stm32_generate` 很慢或像卡住 | CubeMX 冷启动 60–150 s 属正常;默认后台 job,用 `job_output` 看进度,或传 `foreground: true` 同步等 |
|
|
265
|
+
| `stm32_code_patch` 说块不存在 | `main.c` 里是短标签(`PV`=私有变量、`PFP`=函数原型、`2`=while 前初始化、`3`=循环体);报错会列出该文件全部可用标签,照抄即可 |
|
|
266
|
+
|
|
267
|
+
## 开发与测试
|
|
268
|
+
|
|
269
|
+
```powershell
|
|
270
|
+
npm run build # tsc -> lib/(lib/ 入库,改完 src 必须重建后一起提交)
|
|
271
|
+
npm test # 11 个离线套件、89 个用例;不需要板子、CubeMX、工具链
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
CI(`.github/workflows/ci.yml`)在每次 push / PR 上跑 `npm ci → build → 检查提交的 lib/ 是否与 src/ 同步 → npm test`(windows-latest)。
|
|
275
|
+
|
|
276
|
+
GitHub runner 上没有 msys64 / CubeMX,所以有两条依赖真固件包的脚手架用例会 skip:CI 上是 **87 pass + 2 skipped**,开发机上是 89 全跑。离线套件只读仓库自带的 [`test/fixtures/`](test/fixtures/README.md);会话类用例用 `fakeBinDirs()` 在临时目录造空文件占位的 openocd / gdb,不依赖本机装了什么。
|
|
277
|
+
|
|
278
|
+
真机 e2e 会写板子,需要你指一个能构建的工程:
|
|
279
|
+
|
|
280
|
+
```powershell
|
|
281
|
+
$env:DSH_STM32_E2E_PROJECT = 'D:\work\my-stm32'
|
|
282
|
+
node test\e2e-flash.mjs
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
分档与每个脚本的用途见 [开发笔记](docs/development-notes.md)。
|
|
286
|
+
|
|
287
|
+
## 目录结构
|
|
288
|
+
|
|
289
|
+
```text
|
|
290
|
+
src/
|
|
291
|
+
index.ts 插件入口(name / inject / apply)
|
|
292
|
+
tools/ 15 个工具的 L3 层(参数 schema + 输出契约 + 渲染)
|
|
293
|
+
engine/ 纯逻辑与工作流(generate / build / flash / debug / ioc / scaffold …)
|
|
294
|
+
commands/register.ts 5 条斜杠命令
|
|
295
|
+
skill/stm32-workflow.ts 随插件下发的 SKILL
|
|
296
|
+
data/ 路径与芯片数据(路径是数据不是逻辑)
|
|
297
|
+
templates/scaffold/ 建工程用的模板快照(CMake / .ld / .vscode / .ioc)
|
|
298
|
+
test/ 离线套件 + fixtures + 真机 e2e
|
|
299
|
+
docs/ 规格书 + 开发笔记
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
## 文档
|
|
303
|
+
|
|
304
|
+
- [规格书](docs/dsh-stm32-plugin-规格.md):工具契约、状态机、验收 A1–A13 的判定标准
|
|
305
|
+
- [开发笔记](docs/development-notes.md):里程碑、宿主契约踩坑、每个工具的实现细节与实测数据
|
|
306
|
+
|
|
307
|
+
## 许可证
|
|
308
|
+
|
|
309
|
+
[MIT](LICENSE)
|