dsh-stm32 0.1.2 → 0.1.3
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 +59 -21
- package/README_EN.md +59 -21
- package/docs/development-notes.md +374 -3
- package/docs/reading-guide.md +87 -66
- package/lib/data/chips.js +38 -51
- package/lib/data/cmsis-sources.js +27 -1
- package/lib/data/device-facts.js +201 -0
- package/lib/data/stm32f1.js +94 -150
- package/lib/data/svd.js +627 -0
- package/lib/engine/assets.js +924 -0
- package/lib/engine/breakpoints.js +242 -0
- package/lib/engine/debug-session.js +153 -5
- package/lib/engine/debug.js +75 -41
- package/lib/engine/doctor.js +2 -2
- package/lib/engine/flash.js +31 -59
- package/lib/engine/ioc-plan.js +5 -5
- package/lib/engine/probe-error.js +212 -0
- package/lib/engine/probe-session.js +311 -0
- package/lib/engine/register-template.js +32 -8
- package/lib/engine/regs.js +2 -0
- package/lib/engine/rtt.js +600 -0
- package/lib/index.js +8 -0
- package/lib/tools/assets.js +341 -0
- package/lib/tools/cache.js +8 -0
- package/lib/tools/debug-session.js +40 -5
- package/lib/tools/debug.js +41 -11
- package/lib/tools/doctor.js +11 -0
- package/lib/tools/flash.js +15 -6
- package/lib/tools/generate.js +3 -0
- package/lib/tools/ioc-apply.js +2 -0
- package/lib/tools/ioc-inspect.js +2 -0
- package/lib/tools/ioc-plan.js +3 -0
- package/lib/tools/project-create.js +24 -0
- package/lib/tools/regs.js +453 -61
- package/lib/tools/route-plan.js +3 -0
- package/lib/tools/rtt.js +347 -0
- package/package.json +1 -1
- package/templates/register/CMakeLists.txt +7 -1
- package/templates/register/Core/Inc/rtt.h +103 -0
- package/templates/register/Core/Src/main.c +25 -0
- package/templates/register/Core/Src/rtt.c +297 -0
- package/templates/scaffold/RTT.md +86 -0
- package/templates/scaffold/cmake/user/CMakeLists.txt +7 -0
- package/lib/data/f1-ram.generated.js +0 -34
package/README.md
CHANGED
|
@@ -10,15 +10,15 @@
|
|
|
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) **插件**:注册 21 个工具、7 条斜杠命令和 1 个随插件下发的 SKILL,让模型能直接探测工具链、建cubemx cmake工程、改 `.ioc`、跑 CubeMX、编译、烧录和调试,烧完再把寄存器里的状态读回来确认——实现更彻底的面向DSH硬件编程。
|
|
16
16
|
|
|
17
17
|
## 为什么需要它
|
|
18
18
|
|
|
19
19
|
大多数「让 AI 帮忙写 STM32」的做法停在代码层:它给你一段 `main.c`,至于这段代码能不能编译、烧进去灯到底闪没闪,还是你自己开 CubeMX、切终端、按 F5。**模型看不到板子,也就没法对自己的代码负责。**
|
|
20
20
|
|
|
21
|
-
这个插件把硬件侧也接到 DSH 上:`.ioc` 能读能改(事务 + 回滚)、代码落在 `USER CODE` 块里、生成和编译能拿到真实的报错行、烧录是一条**不经过调试器**的独立路径、烧完还能用寄存器把状态读回来。每一步都返回结构化证据(`planId`、`file:line:col`、`Verified OK`、`
|
|
21
|
+
这个插件把硬件侧也接到 DSH 上:`.ioc` 能读能改(事务 + 回滚)、代码落在 `USER CODE` 块里、生成和编译能拿到真实的报错行、烧录是一条**不经过调试器**的独立路径、烧完还能用寄存器把状态读回来。每一步都返回结构化证据(`planId`、`file:line:col`、`Verified OK`、`GPIOC.ODR` 的 bit13(有 SVD 时报告直接写 `ODR13=1`)),模型据此决定下一步,而不是猜。
|
|
22
22
|
|
|
23
23
|
这就是「更彻底的面向 DSH 硬件编程」:**模型不只是写代码——它能把代码烧进板子,再把板子上的状态从寄存器里读回来跟自己的预期对账。**
|
|
24
24
|
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
| 写代码 | 整文件编辑,一不小心写进生成区,重新生成就没了 | `stm32_code_patch` 只写 `USER CODE` 块,块外逐字节不动 |
|
|
30
30
|
| 编译 | 使用keil编译或使用vscode插件编写cmake文件 | DSH 通过/stm32-build [dir] [--clean] 自动编译 |
|
|
31
31
|
| 烧录 | 使用keil烧录或自己写 `tasks.json` 调 openocd | DSH 通过/stm32-debug [dir]自动烧录 |
|
|
32
|
-
| 验证 | 断点调试,自己查看寄存器的值 | 烧完用 `stm32_regs_read` 把状态读回来:`
|
|
32
|
+
| 验证 | 断点调试,自己查看寄存器的值 | 烧完用 `stm32_regs_read` 把状态读回来:`GPIOC.ODR` 两次采样看计数器递增(有 SVD 时直接显示 `ODR5=1`),`AFIO.MAPR` 确认 SWD 没被固件关掉 |
|
|
33
33
|
| 调试 | `F5` + 手动下断点、看完再关会话 | `stm32_debug_run` 停在 `main` 抓一次现场即释放;要连续调才开 `stm32_debug_session`,空闲自动关 |
|
|
34
34
|
|
|
35
35
|
|
|
@@ -56,7 +56,9 @@ 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.3`;重启后 `/stm32-doctor` 有输出。
|
|
60
|
+
|
|
61
|
+
> **首次使用要联网拉一次资源包**:插件不内置任何芯片表,设备事实(型号 → 启动文件 / 设备宏 / Flash·RAM 容量)在第一次用到时由 `stm32_assets` 自动装一次(`profile: "core"`,30 个文件约 237 KiB:芯片表 + 内存布局 + `.ioc` 模板 + 链接脚本)。装好之后整条链离线可用,换版本才会再联网。
|
|
60
62
|
|
|
61
63
|
|
|
62
64
|
**卸载**:`dsh plugin --profile desktop remove dsh-stm32`,重启 dsh。
|
|
@@ -68,7 +70,7 @@ git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
|
68
70
|
cd dsh-stm32
|
|
69
71
|
npm install --no-audit --no-fund # 只装 typescript
|
|
70
72
|
npm run build # tsc -> lib/(提交前必须跑)
|
|
71
|
-
npm test # 可选:
|
|
73
|
+
npm test # 可选:497 个离线用例、34 个套件,不需要板子
|
|
72
74
|
npm run test:pack # 打包 tarball → 解包 → 用解包出来的 lib 真建一次寄存器工程
|
|
73
75
|
npm run test:size # 包体护栏:tarball ≤1.2 MB、templates ≤60 KB、包内不许二进制/图表
|
|
74
76
|
```
|
|
@@ -96,7 +98,9 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
96
98
|
| 3 | 按 `.ioc` 无头跑 CubeMX,产物落到 `Core/` | `stm32_generate` | 首次 130–175 s;之后再跑,`.ioc` 与产物都没变会**直接跳过**(<1 s) |
|
|
97
99
|
| 4 | 编译(首次自动 `cmake --preset`) | `stm32_build` | 配置 ~5 s + 编译 3 s |
|
|
98
100
|
| 5 | **只烧录**:program + verify + reset | `stm32_flash` | 2.1–2.6 s |
|
|
99
|
-
| 6 | 读回 `
|
|
101
|
+
| 6 | 读回 `GPIOC.ODR`(或地址 `0x4001100C`),确认状态确实在翻 | `stm32_regs_read` | 0.4–1.3 s |
|
|
102
|
+
|
|
103
|
+
> 第 6 步用的是符号写法(`GPIOC.ODR`)。它靠资源包里的 SVD 表:`stm32_assets action="refresh" profile="full"`(128 个文件,其中 SVD 1.71 MiB)。只装了 `core` 也能读——但要写地址 `0x4001100C`,报告里没有寄存器名,也没有位域解释。
|
|
100
104
|
|
|
101
105
|
模型侧就是一句话:「在 `D:\work\blink` 建一个 STM32F103C8T6 的闪灯工程,编译并烧进去」。想自己敲就:
|
|
102
106
|
|
|
@@ -121,7 +125,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
121
125
|
| 多源文件、自己写的模块 | 写进 `cmake/user/CMakeLists.txt`,模板已留好位置 | 位置就位;未单独实测 |
|
|
122
126
|
| 业务代码 | `stm32_code_patch` 按块写入,重新生成时按标签搬回 | 已实测(append / replace / 标签写错会列出全部可用标签) |
|
|
123
127
|
| 调参数、改时钟 | `.ioc` 事务:先 diff → SHA 校验 → 备份 → 失败回滚 | 已实测 |
|
|
124
|
-
| 烧完确认外设真的在动 | `stm32_regs_read`
|
|
128
|
+
| 烧完确认外设真的在动 | `stm32_regs_read` 读任意外设寄存器——符号名 `TIM2.CNT` / `USART1.SR` / `ADC1.DR`…或物理地址 `0x40000024`;只写外设名 `GPIOC` 就把它的 7 个寄存器整体 dump。也可以 `stm32_debug_eval` 读变量 | 地址写法已上板实测(`0x4001100C` / `0x40010004`);符号名与位域解释用真实资源包 + 假探针验证,**真机待复测**(开发笔记 §31.11) |
|
|
125
129
|
| 出问题要看现场 | `stm32_debug_run` 停在 `main` 抓一次;要连续调就开 `stm32_debug_session` + `stm32_debug_eval` | 已实测(停在 `main () at main.c:67`) |
|
|
126
130
|
|
|
127
131
|
所以闪灯是验收用的最小样例,不是这套工具的能力上限:**它覆盖的是整条工程链,而不是一个 demo。** 真正的边界在[已知限制](#已知限制)里——芯片支持 F1 全系(F100/101/102/103/105/107,本机验证板是 C8T6)但只到 F1、宿主只在 Windows 上验证、探针默认 CMSIS-DAP,以及上面那条「新增外设要手工补 HAL 源」。外设种类本身不受工具限制:`.ioc` 里配得出来的,生成、编译、烧录、读回都走同一条链;只是除闪灯外还没有逐项上板实测,正式开项目前先跑一遍 `stm32_doctor`。
|
|
@@ -134,15 +138,17 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
134
138
|
| 开工前门禁 | 每个会动工具链的工具先过 `ensureToolchain`:缺件就拦住并写清装什么、缺了会怎样;`envCheck: "block"`(默认)/ `"warn"` / `"off"` 由调用方决定 |
|
|
135
139
|
| 装工具链 | `stm32_env_install`:先只出计划(下载什么、多大、要改哪条 PATH),你点头才真装 MSYS2 + 5 个 pacman 包 + 用户级 PATH,装完自己写进配置文件 |
|
|
136
140
|
| 选技术路线 | `stm32_route_plan`:先按**这个工程**的需求,把每个外设的 HAL 版与寄存器版代价摆出来(效率 / 可读性 / 排错),再告诉你缺的是「能代装的」还是「只能人装的」(CubeMX 是 GUI 向导 + 要 ST 账号、固件包只由 CubeMX 包管理器维护) |
|
|
141
|
+
| 设备事实(型号 → 启动文件 / 设备宏 / 容量) | 插件**不内置芯片表**:型号、启动文件、设备宏、Flash/RAM 这些事实只从本地资源包缓存读(`~/.dsh-stm32/assets/<版本>/device/f1/chips.json`,`DSH_STM32_ASSETS` 可换根目录),第一次用到时自动装一次(`stm32_assets` 的 `refresh`),装好之后离线可用。没网又没缓存时 `stm32_project_create` / `stm32_doctor` 会明说「先跑 stm32_assets refresh,或检查网络」,不会拿内置表凑一个可能错的启动文件名 |
|
|
137
142
|
| 从零建工程 | `stm32_project_create`:`route: "hal"` 用模板快照 + 固件包 Drivers(与 CubeMX GUI 新建的工程逐字节一致);`route: "register"` 建不用 CubeMX 的寄存器版工程,CMSIS 模板首次从网上下到缓存、之后复用(每个文件都钉了上游 sha256,改过就拒绝落盘);`mcu` 指定型号(两条路线都吃;HAL 路线按型号渲染启动文件 / 设备宏 / `<DeviceId>_FLASH.ld`);两条路线都会带一份 `openocd.cfg`(CMSIS-DAP + `hla_swd` + 2 MHz) |
|
|
138
143
|
| 导出工程 | `stm32_project_export`:源码打成一个 zip(默认不带 `build/`、`.dsh-stm32/`、`node_modules/`、`.git/`),可选把 `.elf` 一起带上,并写一份开箱 README |
|
|
139
144
|
| `.ioc` 事务 | `stm32_ioc_inspect`(只读解析)→ `stm32_ioc_plan`(算 diff,不写盘)→ `stm32_ioc_apply`(SHA 校验 + 备份 + 回滚) |
|
|
140
145
|
| 只改 USER CODE | `stm32_code_patch`:只写 `/* USER CODE BEGIN X */` 与 `END X` 之间,块外逐字节不动 |
|
|
141
146
|
| 生成代码 | `stm32_generate`:无头 CubeMX + 按 ST 结构落位 + USER CODE 按标签搬回 |
|
|
142
147
|
| 编译 | `stm32_build`:构建目录与 `.elf` 自动推断、错误去重、链接后解析 RAM/FLASH 占用;`artifacts` 里要 `hex` / `bin` 就用同一套 `arm-none-eabi-objcopy` 转出来 |
|
|
143
|
-
| 烧录 | `stm32_flash`:openocd `program verify reset exit`,烧完释放探针;烧前检查 `.ioc` 是否开了 Serial Wire
|
|
148
|
+
| 烧录 | `stm32_flash`:openocd `program verify reset exit`,烧完释放探针;烧前检查 `.ioc` 是否开了 Serial Wire;失败时给结构化 `probeError`(`kind` / `cause` / `hint` / `evidence` / `retryable`,`kind` 收 8 类) |
|
|
144
149
|
| 调试 | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
|
|
145
|
-
| 验证"真的在跑" | `stm32_regs_read
|
|
150
|
+
| 验证"真的在跑" | `stm32_regs_read`:按地址或符号名(`GPIOC.ODR`)把任意外设寄存器读回来,有 SVD 时顺带解位域(`→ ODR5=1`);halt 读值后 `resume`,不复位芯片 |
|
|
151
|
+
| 固件日志(RTT) | `stm32_rtt`:控制块按 SEGGER 约定放在 RAM,openocd 的 `rtt setup/start/server start` 把通道 0 搬成 TCP 流,再按 13 字节头解出级别与时间戳——不接串口、不改接线 |
|
|
146
152
|
| 给模型的工作纪律 | 随插件下发 SKILL `stm32-workflow`(只改 USER CODE、不动生成区、烧录与调试分开、结论要带寄存器证据) |
|
|
147
153
|
|
|
148
154
|
## 工具参考
|
|
@@ -156,6 +162,7 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
156
162
|
| `stm32_route_plan` | 动手前先把路线问清楚:`requirement` 必填(如「按键控制 LED,串口每秒打印一次状态」),返回 `verdict`(`register-ok` / `both-viable` / `hal-only` / `unclear`)、逐外设的 `halEffort`/`regEffort` 与 `advice`、两种写法的差别、落地的下一步、工具链缺件(每条标 `installability`:`auto` 可代装 / `manual` 只能人装)与手动安装指引全文。不做通用对照表——结论只对当前需求成立 |
|
|
157
163
|
| `stm32_doctor` | 一次回答三件事:工具链齐不齐、探针被谁占(`openocd.exe` / gdb 进程 / 3333 端口)、这个工程能不能烧 |
|
|
158
164
|
| `stm32_project_create` | 空目录 → 完整 CMake 工程。`route: "hal"`(默认)走 CubeMX 那套(含 `.vscode` 里"① 只烧录 / ② 烧录并调试"两份配置);`route: "register"` 建**不用 CubeMX、不用 HAL** 的寄存器版工程(`mcu` 指定型号——F1 全系都吃;寄存器版从缓存取 CMSIS 头与启动文件,HAL 版按型号渲染启动文件 / 设备宏 / `.ld`)。目标目录非空默认拒绝,`overwrite: true` 才覆盖 |
|
|
165
|
+
| `stm32_assets` | 管**设备事实资源包**(芯片表 / 内存布局 / .ioc 模板 / 链接脚本 / SVD,不是 CMSIS 下载缓存):`action: "refresh"`(默认 `profile: "core"`,30 个文件约 237 KiB;已装同版本直接复用;`profile: "full"` 是 128 个文件,多加 SVD 等表)从 GitHub → jsDelivr → gitcode 多源拉 `manifest.json`,逐文件钉 sha256 装到 `~/.dsh-stm32/assets/<版本>/`;`list` / `verify` / `prune` 管各版本。**插件不再内置任何芯片表**,设备事实只从这里读,第一次用要联网装一次,装好后离线可用 |
|
|
159
166
|
| `stm32_cache` | 看 / 验 / 拉 / 清下载缓存:`action: "list"`(默认)列条目、`"verify"` 逐文件校验、`"fetch"` 按 `mcu` 拉一次模板(已缓存则直接复用,不联网)、`"purge"` 删条目(不给 `id` 就清空)。缓存里放的是"不属于插件、但建工程要用"的 CMSIS 设备头 + 启动文件 + 内核头,第一次用时才下载,之后一直复用 |
|
|
160
167
|
| `stm32_project_export` | 把工程打成一个 zip 交给别人:默认收源码、CMake、`.vscode`、`.ioc`,跳过 `build/`、`.dsh-stm32/`、`node_modules/`、`.git/`;`includePrebuilt: true` 把 `.elf` 一起带上,`readme: false` 不写包内 README,`outDir` 指定落点(默认工程同级的 `<name>-export.zip`) |
|
|
161
168
|
| `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` 指过去 |
|
|
@@ -180,12 +187,40 @@ pnpm add "link:D:\path\to\dsh-stm32"
|
|
|
180
187
|
|
|
181
188
|
| 工具 | 作用 |
|
|
182
189
|
| --- | --- |
|
|
183
|
-
| `stm32_flash` | **烧录**:openocd `program verify reset exit`,不建调试会话、不停 `main`。烧前读 `.ioc`,调试口没开就拒绝(见 [设计要点](#设计要点)
|
|
184
|
-
| `stm32_debug_run` | 起 openocd + gdb,`break main` → `continue` → 抓 pc/sp/lr/bt/locals → `reset run` + `detach`,不写 Flash
|
|
190
|
+
| `stm32_flash` | **烧录**:openocd `program verify reset exit`,不建调试会话、不停 `main`。烧前读 `.ioc`,调试口没开就拒绝(见 [设计要点](#设计要点))。失败会带结构化 `probeError`:`kind`(`no-probe` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `timeout` / `unknown` 共 8 类)、`cause`(一句话根因)、`hint`(可执行的下一步,每类都有专属建议)、`evidence`(原始日志行)、`retryable`(照 hint 处理完再调一次有没有意义);成功时这个字段根本不出现。日志里找不到设备时,还会把 USB 形态(这台机器没有 USB / 没插探针 / 驱动异常)写进 notes |
|
|
191
|
+
| `stm32_debug_run` | 起 openocd + gdb,`break main` → `continue` → 抓 pc/sp/lr/bt/locals → `reset run` + `detach`,不写 Flash、不常驻。硬件断点 / 观察点超芯片上限(F1 是 6 个断点 / 4 个观察点)会在起 openocd **之前**就报错,不占探针 |
|
|
185
192
|
| `stm32_debug_session` | 常驻 openocd 会话(`.elf` 自动解析),空闲 90 s 自动关、硬上限 10 min |
|
|
186
193
|
| `stm32_debug_eval` | 在会话里执行 gdb 命令或读表达式(如 `g_led_blink_count`),读完立刻 `resume` + `detach` |
|
|
187
194
|
| `stm32_debug_stop` | 立刻释放探针,幂等 |
|
|
188
|
-
| `stm32_regs_read` |
|
|
195
|
+
| `stm32_regs_read` | 读寄存器,`addresses` 五种写法:物理地址 `0x4001100C` / `4001100C`、符号名 `GPIOC.ODR` / `GPIOC->ODR`、只写外设名 `GPIOC`(按偏移升序把它的 7 个寄存器整体 dump,上限 64 条)。装了资源包的 `full` profile 时,每条样本带规范化名与**置位位域**(`GPIOC.ODR (0x4001100C) = 0x00000020 → ODR5=1`);未知外设会列出可用的前 10 个(共 53 个),未知寄存器会列出该外设的已知寄存器;没有 SVD 时纯地址照读(只是没有名字与位域),符号名报错并提示 `stm32_assets refresh --profile full`。收尾用 `resume` 而不是 `reset run`,避免读一眼就把固件状态清零;连读时复用常驻 openocd 会话(毫秒级,不另起进程),没有会话才起一次并保留 90 s |
|
|
196
|
+
| `stm32_rtt` | **RTT 日志**(不占串口):`action: "start"` 先用 `mdw` 读三个字确认 RAM 里真有 `SEGGER RTT` 控制块(`addr` 填控制块起始地址,不是通道缓冲地址),再发 `rtt setup/start/server start`;没有活跃会话时自己起一个。`action: "dump"` 读 `seconds`(默认 3 s)或 `maxRecords`(默认 200 条),返回 `records[{ t, level, text }]`——`level` 是**保留到哪一级**(1 error / 2 warn / 3 info / 4 debug,默认 4 全要),`dropped` / `truncated` 如实报。`action: "stop"` 幂等(turn 结束也会自动停),`action: "status"` 看端口与已运行时长。目标必须**真在跑**(`rtt start` 读的是运行时 RAM)。失败带 `probeError`:控制块全 0 = 固件没调 `rtt_init()`、魔数不符 = `addr` 填错、连不上 = 会话掉了或 9090 端口被占 |
|
|
197
|
+
|
|
198
|
+
### 固件里怎么加 RTT(最短示例)
|
|
199
|
+
|
|
200
|
+
寄存器版工程(`route: "register"`)已经把 `Core/Src/rtt.c` 与 `Core/Inc/rtt.h` 建好,但**默认没启用**:没人引用时 `--gc-sections` 会把它们连同 3 KB 环形缓冲一起丢掉(默认固件 1576 B RAM / 1368 B FLASH,`nm` 里没有 `_SEGGER_RTT`)。要开日志,只往 USER CODE 块里加三行:
|
|
201
|
+
|
|
202
|
+
```c
|
|
203
|
+
/* USER CODE BEGIN 2 */ /* 必须在时钟初始化之后:时间戳按 SystemCoreClock 换算 */
|
|
204
|
+
rtt_init();
|
|
205
|
+
rtt_printf(RTT_LEVEL_INFO, "boot: sysclk=%lu", (unsigned long)SystemCoreClock);
|
|
206
|
+
/* USER CODE END 2 */
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
(`rtt.h` 已经在 `Core/Inc` 里,也可以再显式写一行 `#include "rtt.h"` 到 `USER CODE BEGIN Includes`。)编译后在宿主侧取控制块地址:
|
|
210
|
+
|
|
211
|
+
```powershell
|
|
212
|
+
arm-none-eabi-nm build/Debug/<工程名>.elf | findstr _SEGGER_RTT
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
然后让模型跑这三步(下面是 `stm32_rtt` 的三次工具调用,参数名与工具 schema 一致):
|
|
216
|
+
|
|
217
|
+
```text
|
|
218
|
+
stm32_rtt action=start addr=0x20000DE0 # 控制块地址,来自上面那行 nm
|
|
219
|
+
stm32_rtt action=dump seconds=3 level=3 # 读 3 秒内 info 及以上级别
|
|
220
|
+
stm32_rtt action=stop # 释放端口;turn 结束也会自动停
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
启用后 RAM 从 1576 B 涨到 5232 B(3 个 1 KB 环 + 控制块,约占 C8T6 20 KB 的 1/4),FLASH 随 `rtt_printf` 变大(大头是 newlib 的 `vsnprintf`;只要纯文本就改用 `rtt_write` 可以省掉它)。HAL 工程不自带这份源:按 `templates/scaffold/RTT.md` 把 `templates/register/Core/Src/rtt.c` 拷成 `App/rtt.c`、挂进 `cmake/user/CMakeLists.txt`,再照上面三行放进 USER CODE 块。环满时是**整条丢弃**(不写半条),固件侧 `rtt_dropped_count()` 能查丢了多少。
|
|
189
224
|
|
|
190
225
|
## 斜杠命令
|
|
191
226
|
|
|
@@ -328,6 +363,8 @@ source [find target/stm32f1x.cfg]
|
|
|
328
363
|
| 新增外设要**手工补 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` |
|
|
329
364
|
| 生成/建工程需要 **CubeMX + F1 固件包** | 固件包版本默认 `STM32Cube_FW_F1_V1.8.7` | 换版本传 `firmwarePackage` |
|
|
330
365
|
| 未在别人的机器上验证 | 本机:Windows 10 + MSYS2 UCRT64 + DAPLink + 蓝丸;其余组合靠反馈 | 遇到问题请附 `stm32_doctor` 的完整输出开 issue |
|
|
366
|
+
| **RTT 只有通道 0**,帧是我们自己的约定 | `stm32_rtt` 只解析通道 0,头是 13 字节(4 B 长度 + 1 B 级别 + 8 B 时间戳 + UTF-8 正文);既不是 defmt,也不是 SEGGER 原生裸字节——原生客户端(RTT Viewer / J-Link RTT Client)读通道 0 会把这 13 字节当正文。RTT 还依赖目标 RAM:不调 `rtt_init()` 就没有控制块,环满时整条丢 | 级别当过滤(`level: 3` 只看 info 以上),结构化内容塞进 `text` 里自己放 JSON;通道数与环大小改 `rtt.h` 的 `RTT_UP_CHANNELS` / `RTT_BUF_SIZE`(默认 3×1 KB = 3 KB `.bss`,C8T6 只有 20 KB);要 defmt 解码或原生 RTT 输出是另一个功能 |
|
|
367
|
+
| **寄存器符号名与位域解释要靠资源包的 `full` profile** | `GPIOC.ODR` / `GPIOC->ODR` 与外设 dump(只写 `GPIOC`)都从 `device/f1/svd/<line>.json` 解析,这份数据由 ST 的 SVD 派生(ST EULA,1.71 MiB),`core`(30 个文件约 237 KiB)里没有;覆盖线只有 100/101/102/103/105/107。没有 SVD 时纯地址照读,只是没有名字和位域;符号名会报错并提示怎么补 | `stm32_assets action="refresh" profile="full"`(128 个文件);不想装就写 `0x` 开头的地址 |
|
|
331
368
|
|
|
332
369
|
## 排错
|
|
333
370
|
|
|
@@ -336,9 +373,10 @@ source [find target/stm32f1x.cfg]
|
|
|
336
373
|
| 装插件时 `ERR_PNPM_GIT_UNKNOWN_ERROR … connect ETIMEDOUT …:443` | 这是**取包这一跳**连不上 GitHub(`dsh plugin add github:…` 会走 git 去拉仓库),跟 pnpm 11 的 `allowBuilds` 白名单、包体签名、包本身都没关系——换个网络就能装上。三条路按省事程度排:① 用 npm 上的正式包:`dsh plugin --profile desktop add dsh-stm32`(走 npm registry,不碰 GitHub);② 一定要从 GitHub 装,就只给这一条命令挂代理,用进程级 `GIT_CONFIG_*` 临时生效、**不动你的全局 git 配置**:`$env:GIT_CONFIG_COUNT="1"; $env:GIT_CONFIG_KEY_0="http.https://github.com.proxy"; $env:GIT_CONFIG_VALUE_0="http://127.0.0.1:7890"; dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main`(端口换成你自己的);③ 绕开 git、直接吃 HTTPS 包:`dsh plugin --profile desktop add https://codeload.github.com/JingYu-er/dsh-stm32/tar.gz/refs/heads/main`。**装最新**永远用 `github:JingYu-er/dsh-stm32#main`,已经 publish 的版本用 `dsh-stm32@latest`——两者内容一致,后者不依赖 GitHub |
|
|
337
374
|
| 烧完连不上、SWD 失联 | 固件里生成了 `__HAL_AFIO_REMAP_SWJ_DISABLE()`。按住 BOOT0 上电进系统 bootloader 重烧,然后把 SYS 设回 Serial Wire——`stm32_flash` 现在会先拦这种情况 |
|
|
338
375
|
| `Error: No device found` / `transfer count mismatch` | 探针被别的进程占着。先 `/stm32-stop`,再用 `stm32_doctor` 看 openocd / gdb 进程与 3333 端口。调试会话开着时读寄存器不会再有这个问题:`stm32_regs_read` 复用会话的 openocd,不另起第二个 |
|
|
339
|
-
| 调试会话开着时读寄存器,`report.command` 是一条 `gdb-multiarch … target extended-remote 127.0.0.1:3333` | 这是「复用会话」的正常形态:`stm32_debug_session` 活着时,`stm32_regs_read`
|
|
376
|
+
| 调试会话开着时读寄存器,`report.command` 是一条 `gdb-multiarch … target extended-remote 127.0.0.1:3333` | 这是「复用会话」的正常形态:`stm32_debug_session` 活着时,`stm32_regs_read` 借用会话里那个 openocd,notes 会写清「复用调试会话(gdb 端口 N,tcl 端口 M),没有另起 openocd」。B3 之后默认走 **Tcl RPC 直读**(一条 TCP 连接:halt → 读 pc → 连续 `mdw` → resume,毫秒级),所以 `report.command` 是 `gdb-multiarch …` 只说明 Tcl 快路径没成、回退到了会话里的 gdb,原因写在 notes 里;只有没有会话时才另起 openocd。旧版在这里会报 `CMSIS-DAP transfer count mismatch: expected N, got M` |
|
|
340
377
|
| 编译"成功"但跑的是旧固件 | 复制或改名过带 `build/` 的工程:CMakeCache 里的目录对不上,ninja 仍退出 0。`stm32_build` 会判失败;按提示 clean 或删 `build/Debug` |
|
|
341
378
|
| 工具直接回「缺 arm-none-eabi-gcc…,这次没有开始编译」 | 这是开工前门禁(`envCheck` 默认 `block`)拦下来的,不是 bug:它比跑到一半才发现省时间。回一句「装」,模型调 `stm32_env_install` 出计划;确认后装好并写配置文件,**下一条命令就能用,不必重启**。想先看全貌就 `/stm32-env`;只想先跑起来就传 `envCheck: "warn"`(照做但写警告)或 `"off"`(不查) |
|
|
379
|
+
| 第一次建工程回「设备事实还没就绪……先跑 stm32_assets refresh,或检查网络」 | 插件不内置芯片表:型号 → 启动文件 / 设备宏 / Flash / RAM 的事实只从本地资源包缓存(`~/.dsh-stm32/assets/<版本>/`)读。联网跑一次 `stm32_assets`(`action: "refresh"`,默认 `profile: "core"`,30 个文件约 237 KiB),装好后离线可用;`DSH_STM32_ASSETS` 可换根目录 |
|
|
342
380
|
| `stm32_doctor` 说找不到 gcc / openocd | 先看 doctor 的 notes / 报错里的「查过 …」列表与自动发现结果;装上后还找不到就设 `STM32_BIN_DIRS` 或给工具传 `binDirs`。**不知道装什么就先跑 `stm32_env_probe`**:每条缺失项都带 `impact`(缺了影响哪些功能)、`install`(推荐装法,第一条最省事)、`verify`(装完自检),顶层 `recommendations` 给出安装顺序,还会问要不要帮你装 |
|
|
343
381
|
| `stm32_generate` 很慢或像卡住 | 首次(冷启动、无缓存)3.5–4 分钟属正常,之后 .ioc 与产物没变会直接跳过(<1 s)。默认后台 job,用 `job_output` 看进度,或传 `foreground: true` 同步等。想确认是不是漏命中缓存,看返回里的 `skipped` 与 notes 给的 reason |
|
|
344
382
|
| 生成没变化却每次都跑满 3 分钟 | 缓存键里含 CubeMX 的 size+mtime 与产物 hash:换过 CubeMX、改过生成区文件、或改过落位布局都会失效。看 notes 里的 reason,或删 `.dsh-stm32/generate-cache.json` 从干净状态重来 |
|
|
@@ -350,14 +388,14 @@ source [find target/stm32f1x.cfg]
|
|
|
350
388
|
|
|
351
389
|
```powershell
|
|
352
390
|
npm run build # tsc -> lib/(lib/ 入库,改完 src 必须重建后一起提交)
|
|
353
|
-
npm test #
|
|
391
|
+
npm test # 34 个离线套件、497 个用例;不需要板子、CubeMX、工具链
|
|
354
392
|
npm run test:pack # 把包打成 tarball、解开、用解包出来的 lib 真建一次寄存器工程
|
|
355
393
|
npm run test:size # 包体护栏:tarball ≤1.2 MB、templates ≤60 KB、包内不许二进制/图表
|
|
356
394
|
```
|
|
357
395
|
|
|
358
396
|
CI(`.github/workflows/ci.yml`)在每次 push / PR 上跑 `npm ci → build → 检查提交的 lib/ 是否与 src/ 同步 → npm test → test:pack → test:size`(windows-latest)。
|
|
359
397
|
|
|
360
|
-
GitHub runner 上没有 msys64 / CubeMX,所以有两条依赖真固件包的脚手架用例会 skip:CI 上是 **
|
|
398
|
+
GitHub runner 上没有 msys64 / CubeMX,所以有两条依赖真固件包的脚手架用例会 skip:CI 上是 **495 pass + 2 skipped**,开发机上是 497 全跑。离线套件只读仓库自带的 [`test/fixtures/`](test/fixtures/README.md);会话类用例用 `fakeBinDirs()` 在临时目录造空文件占位的 openocd / gdb,不依赖本机装了什么。
|
|
361
399
|
|
|
362
400
|
### 发布形态三分法(先把东西放哪想清楚,再写包)
|
|
363
401
|
|
|
@@ -365,7 +403,7 @@ GitHub runner 上没有 msys64 / CubeMX,所以有两条依赖真固件包的
|
|
|
365
403
|
| --- | --- | --- |
|
|
366
404
|
| 随包(npm tarball) | `lib/**`(含 `lib/client.js`)、`client/client.js`、`templates/scaffold/**`、`cordis.patch.yml`、两份 README、`LICENSE`、`docs/*.md` | 99 个文件 / 525.7 KB,解包 1538.3 KB;其中 `templates/**` 38.5 KB |
|
|
367
405
|
| 进 git 不进包 | `src/**`、`test/**`、`scripts/**`、`docs/diagrams/**`(两张可交互 HTML) | diagrams 2 MB 原始 / 891 KB gz;`package.json` 的 `files` 把 `docs` 收窄成 `docs/*.md` |
|
|
368
|
-
| 远端按需下载 | CMSIS 设备头 / 启动文件 / 内核头(寄存器版首次用时下到缓存,逐文件钉 sha256);HAL
|
|
406
|
+
| 远端按需下载 | CMSIS 设备头 / 启动文件 / 内核头(寄存器版首次用时下到缓存,逐文件钉 sha256);HAL 固件包;**设备事实资源包**(chips.json / memory.json / .ioc 模板 / .ld / SVD,core 30 个文件约 237 KiB、full 128 个文件——SVD 在 full 里;插件不再内置芯片表,首次使用要联网拉一次 `stm32_assets refresh`,之后离线可用) | 缓存可用 `stm32_cache list/verify/purge` 与 `stm32_assets list/verify/prune` 管 |
|
|
369
407
|
| 现造 | `.ioc` 内容(`renderIoc`)、`.ld` 的 MEMORY(`renderLinkerScript`)、cmake 源清单 | 按型号渲染,模板里不落盘 |
|
|
370
408
|
|
|
371
409
|
护栏是 `scripts/pack-size.mjs`(`npm run test:size`):tarball ≤ 1.2 MB(1 200 000 B)、`templates/**` ≤ 60 KB、包内禁止 `.png/.jpg/.gif/.webp/.bmp/.pdf/.html/.zip/.7z/.exe/.dll`,且必须含 `README.md` / `README_EN.md` / `LICENSE` / `cordis.patch.yml` / `docs/reading-guide.md`。
|
|
@@ -384,14 +422,14 @@ node test\e2e-flash.mjs
|
|
|
384
422
|
```text
|
|
385
423
|
src/
|
|
386
424
|
index.ts 插件入口(name / inject / apply)
|
|
387
|
-
tools/
|
|
425
|
+
tools/ 21 个工具的 L3 层(参数 schema + 输出契约 + 渲染)
|
|
388
426
|
engine/ 纯逻辑与工作流(generate / build / flash / debug / ioc / scaffold …)
|
|
389
427
|
commands/register.ts 7 条斜杠命令
|
|
390
428
|
skill/stm32-workflow.ts 随插件下发的 SKILL
|
|
391
429
|
data/ 路径与芯片数据(路径是数据不是逻辑)
|
|
392
430
|
templates/scaffold/ 建工程用的模板快照(CMake / .ld / .vscode / .ioc)
|
|
393
|
-
test/ 离线套件(
|
|
394
|
-
scripts/ 护栏与生成脚本(pack-size / pack-smoke / gen-
|
|
431
|
+
test/ 离线套件(36 个,run-units 登记)+ fixtures + 真机 e2e
|
|
432
|
+
scripts/ 护栏与生成脚本(pack-size / pack-smoke / gen-xcube-catalog / copy-client)
|
|
395
433
|
docs/ 规格书 + 开发笔记 + 精读指南 + diagrams/(不进 npm 包)
|
|
396
434
|
```
|
|
397
435
|
|
|
@@ -399,7 +437,7 @@ docs/ 规格书 + 开发笔记 + 精读指南 + diagrams/
|
|
|
399
437
|
|
|
400
438
|
- [规格书](docs/dsh-stm32-plugin-规格.md):工具契约、状态机、验收 A1–A13 的判定标准
|
|
401
439
|
- [开发笔记](docs/development-notes.md):里程碑、宿主契约踩坑、每个工具的实现细节与实测数据
|
|
402
|
-
- [源码精读指南](docs/reading-guide.md):分层阅读顺序、每个文件的职责与关键导出、14 张流程图、
|
|
440
|
+
- [源码精读指南](docs/reading-guide.md):分层阅读顺序、每个文件的职责与关键导出、14 张流程图、23 条不变量
|
|
403
441
|
- 可视化:[架构总览](docs/diagrams/dsh-stm32-architecture.html) / [主线旅程](docs/diagrams/dsh-stm32-journey.html)(单文件 HTML,离线可开,可导出 PNG/SVG)
|
|
404
442
|
|
|
405
443
|
## 许可证
|
package/README_EN.md
CHANGED
|
@@ -8,15 +8,15 @@
|
|
|
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 21 tools, 7 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
|
|
|
17
17
|
Most "let the model write STM32 code" setups stop at the source file: you get a `main.c`, and whether it compiles, whether the LED actually blinks after flashing, is still your job — open CubeMX, switch to a terminal, press F5. **The model never sees the board, so it cannot be responsible for its own code.**
|
|
18
18
|
|
|
19
|
-
This plugin wires the hardware side into DSH as well: the `.ioc` can be read and edited (as a transaction, with rollback), code can only land inside `USER CODE` blocks, generation and builds return real error lines, flashing is an independent path that **never goes through a debugger**, and after flashing the model can read the state back out of the registers. Every step returns structured evidence — `planId`, `file:line:col`, `Verified OK`, bit13 of `
|
|
19
|
+
This plugin wires the hardware side into DSH as well: the `.ioc` can be read and edited (as a transaction, with rollback), code can only land inside `USER CODE` blocks, generation and builds return real error lines, flashing is an independent path that **never goes through a debugger**, and after flashing the model can read the state back out of the registers. Every step returns structured evidence — `planId`, `file:line:col`, `Verified OK`, bit13 of `GPIOC.ODR` (the report says `ODR13=1` when SVD data is installed) — so the next step is decided from evidence instead of guesswork.
|
|
20
20
|
|
|
21
21
|
That is what "hardware programming inside DSH" means here: **the model does not just write code — it puts that code on the board, then reads the board's state back out of the registers and reconciles it with what it expected.**
|
|
22
22
|
|
|
@@ -27,7 +27,7 @@ That is what "hardware programming inside DSH" means here: **the model does not
|
|
|
27
27
|
| Write code | Edit the whole file, accidentally touch a generated region, lose it on the next generate | `stm32_code_patch` writes only inside `USER CODE` blocks; everything outside stays byte-for-byte |
|
|
28
28
|
| Build | Build in Keil, or hand-write the CMake files for the VS Code extension | DSH builds automatically via `/stm32-build [dir] [--clean]` |
|
|
29
29
|
| Flash | Flash in Keil, or maintain a `tasks.json` that calls openocd | DSH flashes automatically via `/stm32-debug [dir]` |
|
|
30
|
-
| Verify | Set a breakpoint and read the register values yourself | After flashing, `stm32_regs_read` reads the state back: `
|
|
30
|
+
| Verify | Set a breakpoint and read the register values yourself | After flashing, `stm32_regs_read` reads the state back: `GPIOC.ODR` twice to see the counter grow (with the SVD data it also prints `ODR5=1`), `AFIO.MAPR` to confirm the firmware did not disable SWD |
|
|
31
31
|
| Debug | `F5`, set breakpoints by hand, remember to close the session | `stm32_debug_run` halts at `main`, captures one snapshot and releases the probe; use `stm32_debug_session` only for continuous debugging, it closes itself when idle |
|
|
32
32
|
|
|
33
33
|
|
|
@@ -55,7 +55,9 @@ 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.3`); after a restart `/stm32-doctor` should respond.
|
|
59
|
+
|
|
60
|
+
> **First run needs one online download of the asset pack**: the plugin embeds no chip table. Device facts (part → startup file / device define / Flash·RAM size) are installed on first use by `stm32_assets` (`profile: "core"`, 30 files ≈ 237 KiB: chip table + memory layout + `.ioc` templates + linker scripts). After that the whole chain works offline; it only goes online again when the version changes.
|
|
59
61
|
|
|
60
62
|
|
|
61
63
|
**Uninstall**: `dsh plugin --profile desktop remove dsh-stm32`, then restart dsh.
|
|
@@ -67,7 +69,7 @@ git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
|
67
69
|
cd dsh-stm32
|
|
68
70
|
npm install --no-audit --no-fund # typescript only
|
|
69
71
|
npm run build # tsc -> lib/ (required before committing)
|
|
70
|
-
npm test # optional:
|
|
72
|
+
npm test # optional: 497 offline cases in 34 suites, no board needed
|
|
71
73
|
npm run test:pack # pack a tarball, unpack it, scaffold a real register project from it
|
|
72
74
|
npm run test:size # package guard: tarball <=1.2 MB, templates <=60 KB, no binaries/diagrams inside
|
|
73
75
|
```
|
|
@@ -95,7 +97,9 @@ This chain ran on a real board (acceptance A1, 2026-10-22), driven entirely by t
|
|
|
95
97
|
| 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 |
|
|
96
98
|
| 4 | Build (first run configures with `cmake --preset`) | `stm32_build` | ~5 s configure + 3 s build |
|
|
97
99
|
| 5 | **Flash only**: program + verify + reset | `stm32_flash` | 2.1–2.6 s |
|
|
98
|
-
| 6 | Read `
|
|
100
|
+
| 6 | Read `GPIOC.ODR` (or the address `0x4001100C`) back to confirm the state really toggles | `stm32_regs_read` | 0.4–1.3 s |
|
|
101
|
+
|
|
102
|
+
> Step 6 uses the symbol form (`GPIOC.ODR`), which needs the SVD tables from the asset pack's `full` profile: `stm32_assets action="refresh" profile="full"` (128 files, of which 1.71 MiB is SVD). A `core`-only install still works — write the address `0x4001100C` instead, and the report has neither register names nor bit-field decoding.
|
|
99
103
|
|
|
100
104
|
On the model side it is one sentence: "create a blinking-LED project for STM32F103C8T6 in `D:\work\blink`, build it and flash it". To drive it yourself:
|
|
101
105
|
|
|
@@ -120,7 +124,7 @@ The blinking LED is the **smallest smoke test** for this chain: it walks create
|
|
|
120
124
|
| Several source files, your own modules | Put them in `cmake/user/CMakeLists.txt` (the template leaves that spot ready) | Spot is in place; not tested separately |
|
|
121
125
|
| Business logic | `stm32_code_patch` writes block by block, carried back by label on the next generate | Verified (append / replace / a wrong label lists every available label) |
|
|
122
126
|
| Tuning parameters, changing clocks | `.ioc` transactions: diff first → SHA check → backup → rollback on failure | Verified |
|
|
123
|
-
| Confirm a peripheral is really running after flashing | `stm32_regs_read` reads any peripheral register
|
|
127
|
+
| Confirm a peripheral is really running after flashing | `stm32_regs_read` reads any peripheral register — by name `TIM2.CNT` / `USART1.SR` / `ADC1.DR` … or by physical address `0x40000024`; naming just the peripheral (`GPIOC`) dumps all 7 of its registers. `stm32_debug_eval` reads variables too | Address form verified on hardware (`0x4001100C` / `0x40010004`); symbol names and bit-field decoding verified against the real asset pack with a fake probe, **hardware re-test pending** (development notes §31.11) |
|
|
124
128
|
| Something is wrong and you need the live state | `stm32_debug_run` halts at `main` for one snapshot; use `stm32_debug_session` + `stm32_debug_eval` for continuous debugging | Verified (halts at `main () at main.c:67`) |
|
|
125
129
|
|
|
126
130
|
So the blinking LED is the acceptance sample, not the ceiling: **this covers the whole engineering chain, not one demo.** The real boundaries are the ones under [Known limitations](#known-limitations) — the STM32F1 family only (F100/101/102/103/105/107; the verified board is a C8T6), verified on Windows only, CMSIS-DAP by default, plus the manual HAL-source step above. Peripheral types themselves are not limited by the tools: whatever the `.ioc` can configure goes through the same generate → build → flash → read-back chain; it just has not been tested peripheral by peripheral yet, so run `stm32_doctor` before starting a real project.
|
|
@@ -133,15 +137,17 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
133
137
|
| 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"` |
|
|
134
138
|
| 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 |
|
|
135
139
|
| 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) |
|
|
140
|
+
| Chip facts (part → startup file / device define / sizes) | The plugin **ships no chip table**: part, startup file, device define and Flash/RAM come only from the local assets cache (`~/.dsh-stm32/assets/<version>/device/f1/chips.json`, root overridable with `DSH_STM32_ASSETS`), installed once on first use (`stm32_assets` with `action: "refresh"`) and offline afterwards. With no network and no cache, `stm32_project_create` / `stm32_doctor` say "run stm32_assets refresh, or check the network" instead of inventing a startup file from a built-in table |
|
|
136
141
|
| 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 (every file is pinned by upstream sha256 and refused if it changed); `mcu` names the part (both routes accept it; the HAL route renders its startup file / device define / `<DeviceId>_FLASH.ld` from it); both routes also ship an `openocd.cfg` (CMSIS-DAP + `hla_swd` + 2 MHz) |
|
|
137
142
|
| Export a project | `stm32_project_export`: packs the sources into one zip (without `build/`, `.dsh-stm32/`, `node_modules/`, `.git/`), optionally including the `.elf`, plus a hand-off README |
|
|
138
143
|
| `.ioc` as a transaction | `stm32_ioc_inspect` (read-only parse) → `stm32_ioc_plan` (diff, no writes) → `stm32_ioc_apply` (SHA check + backup + rollback) |
|
|
139
144
|
| USER CODE only | `stm32_code_patch`: writes only between `/* USER CODE BEGIN X */` and `END X`; everything else untouched |
|
|
140
145
|
| Code generation | `stm32_generate`: headless CubeMX + ST project layout + USER CODE carried over by label |
|
|
141
146
|
| Build | `stm32_build`: build directory and `.elf` inferred, deduplicated errors, RAM/FLASH usage parsed after linking; ask for `artifacts: ["hex","bin"]` and the same toolchain's `arm-none-eabi-objcopy` produces them |
|
|
142
|
-
| Flash | `stm32_flash`: openocd `program verify reset exit`, probe released afterwards; checks that the `.ioc` has Serial Wire enabled; failures carry
|
|
147
|
+
| Flash | `stm32_flash`: openocd `program verify reset exit`, probe released afterwards; checks that the `.ioc` has Serial Wire enabled; failures carry a structured `probeError` (`kind` / `cause` / `hint` / `evidence` / `retryable`, `kind` is one of 8) |
|
|
143
148
|
| Debug | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
|
|
144
|
-
| Prove it is running | `stm32_regs_read`: reads any peripheral register back by
|
|
149
|
+
| Prove it is running | `stm32_regs_read`: reads any peripheral register back by address or symbol name (`GPIOC.ODR`), decoding bit fields when SVD data is installed (`→ ODR5=1`); halts, reads, then `resume` — no chip reset |
|
|
150
|
+
| Firmware logs (RTT) | `stm32_rtt`: a SEGGER-shaped control block in RAM, openocd `rtt setup/start/server start` turns channel 0 into a TCP stream, and a 13-byte frame header carries level and timestamp — no UART, no rewiring |
|
|
145
151
|
| Working discipline for the model | SKILL `stm32-workflow` shipped with the plugin (USER CODE only, never touch generated regions, flash and debug are separate, claims need register evidence) |
|
|
146
152
|
|
|
147
153
|
## Tool reference
|
|
@@ -155,6 +161,7 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
155
161
|
| `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 |
|
|
156
162
|
| `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 |
|
|
157
163
|
| `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` |
|
|
164
|
+
| `stm32_assets` | Manages the **device-facts asset pack** (chip table / memory layout / .ioc templates / linker scripts / SVD — not the CMSIS download cache): `action: "refresh"` (default `profile: "core"`, 30 files ≈ 237 KiB; an already installed version is reused; `profile: "full"` is 128 files, adding the SVD tables) fetches `manifest.json` from GitHub → jsDelivr → gitcode and installs it file-by-file, every file pinned by sha256, into `~/.dsh-stm32/assets/<version>/`; `list` / `verify` / `prune` manage versions. **The plugin no longer embeds any chip table**, so device facts come only from here — the first use needs one online install, offline afterwards |
|
|
158
165
|
| `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 |
|
|
159
166
|
| `stm32_project_export` | Hands the project to someone else as one zip: sources, CMake, `.vscode` and the `.ioc` by default, skipping `build/`, `.dsh-stm32/`, `node_modules/`, `.git/`; `includePrebuilt: true` also packs the `.elf`, `readme: false` skips the in-archive README, `outDir` moves the output (default `<name>-export.zip` next to the project) |
|
|
160
167
|
| `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` |
|
|
@@ -179,12 +186,40 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
179
186
|
|
|
180
187
|
| Tool | What it does |
|
|
181
188
|
| --- | --- |
|
|
182
|
-
| `stm32_flash` | **Flash**: openocd `program verify reset exit`, no debug session, no halt at `main`. Reads the `.ioc` first and refuses when the debug port is disabled (see [Design notes](#design-notes)). Failures carry
|
|
183
|
-
| `stm32_debug_run` | Starts openocd + gdb, `break main` → `continue` → captures pc/sp/lr/bt/locals → `reset run` + `detach`; no Flash write, nothing left running |
|
|
189
|
+
| `stm32_flash` | **Flash**: openocd `program verify reset exit`, no debug session, no halt at `main`. Reads the `.ioc` first and refuses when the debug port is disabled (see [Design notes](#design-notes)). Failures carry a structured `probeError`: `kind` (`no-probe` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `timeout` / `unknown`, 8 in total), `cause` (one-line root cause), `hint` (an actionable next step, a dedicated one per kind), `evidence` (the raw log lines) and `retryable` (whether retrying after following the hint makes sense); on success the field is absent entirely. When no device is found the USB shape (no USB on this machine / probe unplugged / driver problem) is added to the notes |
|
|
190
|
+
| `stm32_debug_run` | Starts openocd + gdb, `break main` → `continue` → captures pc/sp/lr/bt/locals → `reset run` + `detach`; no Flash write, nothing left running. Hardware breakpoints / watchpoints above the chip limit (F1: 6 / 4) fail **before** openocd is started, so the probe is never touched |
|
|
184
191
|
| `stm32_debug_session` | Long-lived openocd session (`.elf` resolved automatically), closed after 90 s idle, hard limit 10 min |
|
|
185
192
|
| `stm32_debug_eval` | Runs gdb commands or reads expressions (e.g. `g_led_blink_count`) inside the session, then `resume` + `detach` immediately |
|
|
186
193
|
| `stm32_debug_stop` | Releases the probe immediately, idempotent |
|
|
187
|
-
| `stm32_regs_read` | Reads
|
|
194
|
+
| `stm32_regs_read` | Reads registers; each `addresses` entry accepts five forms: physical address `0x4001100C` / `4001100C`, symbol name `GPIOC.ODR` / `GPIOC->ODR`, or a bare peripheral `GPIOC` (dumps all its 7 registers in ascending offset, capped at 64). With the asset pack's `full` profile every sample carries the canonical name and the **set bit fields** (`GPIOC.ODR (0x4001100C) = 0x00000020 → ODR5=1`); an unknown peripheral lists the first 10 of the 53 available, an unknown register lists that peripheral's known registers; without SVD data plain addresses still read (just no names or bit fields) while a symbol name fails with a hint to run `stm32_assets refresh --profile full`. Finishes with `resume` instead of `reset run`, so a read does not wipe the firmware state; repeated reads reuse the resident openocd session (milliseconds, no extra process), and without a session one is started and kept for 90 s |
|
|
195
|
+
| `stm32_rtt` | **RTT logs** without a UART: `action: "start"` first reads three words with `mdw` to confirm a `SEGGER RTT` control block is really there (`addr` is the control block address, not a channel buffer), then issues `rtt setup/start/server start`; with no live session it starts one itself. `action: "dump"` reads for `seconds` (default 3 s) or up to `maxRecords` (default 200) and returns `records[{ t, level, text }]` — `level` is the **highest level kept** (1 error / 2 warn / 3 info / 4 debug, default 4 = everything), with `dropped` / `truncated` reported honestly. `action: "stop"` is idempotent (also run at turn end), `action: "status"` shows the port and uptime. The target must **actually be running** (`rtt start` reads live RAM). Failures carry `probeError`: an all-zero control block means the firmware never called `rtt_init()`, a magic mismatch means a wrong `addr`, a refused connection means the session died or port 9090 is taken |
|
|
196
|
+
|
|
197
|
+
### Adding RTT to the firmware (shortest example)
|
|
198
|
+
|
|
199
|
+
A register-level project (`route: "register"`) already ships `Core/Src/rtt.c` and `Core/Inc/rtt.h`, but **they are off by default**: with nobody referencing them, `--gc-sections` drops the code and the 3 KB ring buffers (the default firmware is 1576 B RAM / 1368 B FLASH and `nm` shows no `_SEGGER_RTT`). To turn logging on, add three lines inside a USER CODE block:
|
|
200
|
+
|
|
201
|
+
```c
|
|
202
|
+
/* USER CODE BEGIN 2 */ /* must come after clock init: timestamps use SystemCoreClock */
|
|
203
|
+
rtt_init();
|
|
204
|
+
rtt_printf(RTT_LEVEL_INFO, "boot: sysclk=%lu", (unsigned long)SystemCoreClock);
|
|
205
|
+
/* USER CODE END 2 */
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
(`rtt.h` already sits in `Core/Inc`; you may also add an explicit `#include "rtt.h"` to `USER CODE BEGIN Includes`.) After building, grab the control block address on the host:
|
|
209
|
+
|
|
210
|
+
```powershell
|
|
211
|
+
arm-none-eabi-nm build/Debug/<project>.elf | findstr _SEGGER_RTT
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Then have the model run these three steps (three `stm32_rtt` tool calls, arguments named as in the tool schema):
|
|
215
|
+
|
|
216
|
+
```text
|
|
217
|
+
stm32_rtt action=start addr=0x20000DE0 # control block address from the nm line above
|
|
218
|
+
stm32_rtt action=dump seconds=3 level=3 # 3 s of info and above
|
|
219
|
+
stm32_rtt action=stop # releases the port; also runs at turn end
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Enabling it moves RAM from 1576 B to 5232 B (three 1 KB rings plus the control block, about a quarter of the C8T6's 20 KB); FLASH grows with `rtt_printf` (mostly newlib's `vsnprintf` — use `rtt_write` for plain text to avoid it). HAL projects do not ship this source: follow `templates/scaffold/RTT.md`, copy `templates/register/Core/Src/rtt.c` to `App/rtt.c`, wire it into `cmake/user/CMakeLists.txt`, then add the same three lines to the USER CODE block. When a ring is full the **whole record is dropped** (never half of one) and `rtt_dropped_count()` reports the loss.
|
|
188
223
|
|
|
189
224
|
## Slash commands
|
|
190
225
|
|
|
@@ -325,6 +360,8 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
|
|
|
325
360
|
| Adding a peripheral needs a **manual HAL source entry** | The plugin only relocates CubeMX's `Src/` and `Inc/` (→ `Core/Src`, `Core/Inc`); the `cmake/stm32cubemx/CMakeLists.txt` CubeMX emits is not applied. Enable a timer/UART/ADC and you must add the matching `stm32f1xx_hal_<peripheral>.c` yourself | Edit `STM32_Drivers_Src` in the project's `cmake/stm32cubemx/CMakeLists.txt`, or add a `target_sources` line in `cmake/user/CMakeLists.txt` |
|
|
326
361
|
| Generation/scaffolding needs **CubeMX + the F1 firmware package** | Package version defaults to `STM32Cube_FW_F1_V1.8.7` | Pass another version via `firmwarePackage` |
|
|
327
362
|
| Not yet verified on other machines | This machine: Windows 10 + MSYS2 UCRT64 + DAPLink + a Blue Pill; other combinations rely on your feedback | Open an issue with the full `stm32_doctor` output |
|
|
363
|
+
| **RTT channel 0 only**, and the frame format is ours | `stm32_rtt` parses channel 0 only, with a 13-byte header (4 B length + 1 B level + 8 B timestamp + UTF-8 text); it is neither defmt nor SEGGER raw bytes — a native client (RTT Viewer / J-Link RTT Client) reading channel 0 sees that header as payload. RTT also lives in target RAM: no `rtt_init()` means no control block, and a full ring drops records | Use `level` as a filter (`level: 3` keeps info and above), put JSON in `text` for structured output; change channel count and buffer size via `RTT_UP_CHANNELS` / `RTT_BUF_SIZE` in `rtt.h` (default 3 × 1 KB = 3 KB `.bss` on a 20 KB C8T6); defmt decoding or native RTT output would be a separate feature |
|
|
364
|
+
| Register **symbol names and bit-field decoding need the asset pack's `full` profile** | `GPIOC.ODR` / `GPIOC->ODR` and peripheral dumps (a bare `GPIOC`) are resolved from `device/f1/svd/<line>.json`, derived from ST's SVDs (ST EULA, 1.71 MiB), which `core` (30 files ≈ 237 KiB) does not contain; only lines 100/101/102/103/105/107 exist. Without SVD data plain addresses still read, just with no names or bit fields; a symbol name fails with an actionable hint | `stm32_assets action="refresh" profile="full"` (128 files); or just use `0x…` addresses |
|
|
328
365
|
|
|
329
366
|
## Troubleshooting
|
|
330
367
|
|
|
@@ -333,9 +370,10 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
|
|
|
333
370
|
| `ERR_PNPM_GIT_UNKNOWN_ERROR … connect ETIMEDOUT …:443` while installing | The **package fetch hop** cannot reach GitHub (`dsh plugin add github:…` clones over git). It is unrelated to the pnpm 11 `allowBuilds` allow-list, package signatures, or a broken tarball — the same command works from another network. Three options, easiest first: (1) install the published package: `dsh plugin --profile desktop add dsh-stm32` (npm registry, no GitHub); (2) if you must install from GitHub, proxy **only that one command** with process-scoped `GIT_CONFIG_*` (your global git config stays untouched): `$env:GIT_CONFIG_COUNT="1"; $env:GIT_CONFIG_KEY_0="http.https://github.com.proxy"; $env:GIT_CONFIG_VALUE_0="http://127.0.0.1:7890"; dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main` (use your own port); (3) skip git entirely and take the HTTPS tarball: `dsh plugin --profile desktop add https://codeload.github.com/JingYu-er/dsh-stm32/tar.gz/refs/heads/main`. For the newest code use `github:JingYu-er/dsh-stm32#main`; for a published release use `dsh-stm32@latest` — same content, no GitHub dependency |
|
|
334
371
|
| 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 |
|
|
335
372
|
| `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 |
|
|
336
|
-
| 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`
|
|
373
|
+
| 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` borrows that session's openocd and the notes say "reusing the debug session (gdb port N, tcl port M), no extra openocd". Since B3 the default path is **direct Tcl RPC** (one TCP connection: halt → read pc → consecutive `mdw` → resume, milliseconds), so a `gdb-multiarch …` `report.command` only means the Tcl fast path failed and it fell back to the session's gdb — the reason is in the notes. Only without a session does it start its own openocd. Older builds failed here with `CMSIS-DAP transfer count mismatch: expected N, got M` |
|
|
337
374
|
| 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 |
|
|
338
375
|
| 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) |
|
|
376
|
+
| The first project build answers "device facts are not ready … run stm32_assets refresh, or check the network" | The plugin ships no chip table: part → startup file / device define / Flash / RAM come only from the local assets cache (`~/.dsh-stm32/assets/<version>/`). Once online, run `stm32_assets` (`action: "refresh"`, default `profile: "core"`, 30 files ≈ 237 KiB); offline afterwards. `DSH_STM32_ASSETS` overrides the root |
|
|
339
377
|
| `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 |
|
|
340
378
|
| `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 |
|
|
341
379
|
| 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` |
|
|
@@ -347,14 +385,14 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
|
|
|
347
385
|
|
|
348
386
|
```powershell
|
|
349
387
|
npm run build # tsc -> lib/ (lib/ is committed: rebuild before you commit)
|
|
350
|
-
npm test #
|
|
388
|
+
npm test # 34 offline suites, 497 cases; no board, CubeMX, or toolchain needed
|
|
351
389
|
npm run test:pack # pack a tarball, unpack it, scaffold a real register project from the unpacked lib
|
|
352
390
|
npm run test:size # package guard: tarball <=1.2 MB, templates <=60 KB, no binaries/diagrams inside
|
|
353
391
|
```
|
|
354
392
|
|
|
355
393
|
CI (`.github/workflows/ci.yml`) runs `npm ci → build → check that the committed lib/ matches src/ → npm test → test:pack → test:size` on every push and PR (windows-latest).
|
|
356
394
|
|
|
357
|
-
A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that need the real firmware package are skipped: CI reports **
|
|
395
|
+
A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that need the real firmware package are skipped: CI reports **495 passed + 2 skipped**, while a developer machine runs all 497. 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.
|
|
358
396
|
|
|
359
397
|
### What ships where (decide before you add a file)
|
|
360
398
|
|
|
@@ -362,7 +400,7 @@ A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that nee
|
|
|
362
400
|
| --- | --- | --- |
|
|
363
401
|
| npm tarball | `lib/**` (including `lib/client.js`), `client/client.js`, `templates/scaffold/**`, `cordis.patch.yml`, both READMEs, `LICENSE`, `docs/*.md` | 99 files / 525.7 KB packed, 1538.3 KB unpacked; `templates/**` alone is 38.5 KB |
|
|
364
402
|
| Git only, not packed | `src/**`, `test/**`, `scripts/**`, `docs/diagrams/**` (two interactive HTML pages) | diagrams are 2 MB raw / 891 KB gz; `files` in `package.json` narrows `docs` to `docs/*.md` |
|
|
365
|
-
| Downloaded on demand | CMSIS device headers / startup files / core headers (fetched into the cache on first use, pinned per file by sha256); HAL firmware packages | manage the
|
|
403
|
+
| Downloaded on demand | CMSIS device headers / startup files / core headers (fetched into the cache on first use, pinned per file by sha256); HAL firmware packages; the **device-facts asset pack** (chips.json / memory.json / .ioc templates / .ld / SVD — 30 files ≈ 237 KiB for the core profile, 128 files for `full`, which is where the SVDs live — the plugin ships no chip table, the first run needs one online `stm32_assets refresh` and it is offline afterwards) | manage the caches with `stm32_cache list/verify/purge` and `stm32_assets list/verify/prune` |
|
|
366
404
|
| Rendered on the spot | `.ioc` content (`renderIoc`), `.ld` MEMORY (`renderLinkerScript`), the cmake source list | rendered per part, never stored as a template |
|
|
367
405
|
|
|
368
406
|
The guard is `scripts/pack-size.mjs` (`npm run test:size`): tarball ≤ 1.2 MB (1 200 000 B), `templates/**` ≤ 60 KB, no `.png/.jpg/.gif/.webp/.bmp/.pdf/.html/.zip/.7z/.exe/.dll` inside, and `README.md` / `README_EN.md` / `LICENSE` / `cordis.patch.yml` / `docs/reading-guide.md` all present.
|
|
@@ -381,14 +419,14 @@ See the [development notes](docs/development-notes.md) for the suite breakdown a
|
|
|
381
419
|
```text
|
|
382
420
|
src/
|
|
383
421
|
index.ts plugin entry (name / inject / apply)
|
|
384
|
-
tools/ the
|
|
422
|
+
tools/ the 21 tools, L3 (parameter schema + output contract + rendering)
|
|
385
423
|
engine/ pure logic and workflows (generate / build / flash / debug / ioc / scaffold …)
|
|
386
424
|
commands/register.ts the 7 slash commands
|
|
387
425
|
skill/stm32-workflow.ts the SKILL shipped with the plugin
|
|
388
426
|
data/ paths and chip data (paths are data, not logic)
|
|
389
427
|
templates/scaffold/ project template snapshot (CMake / .ld / .vscode / .ioc)
|
|
390
|
-
test/ offline suites (
|
|
391
|
-
scripts/ guards and generators (pack-size / pack-smoke / gen-
|
|
428
|
+
test/ offline suites (36, registered in run-units) + fixtures + hardware e2e
|
|
429
|
+
scripts/ guards and generators (pack-size / pack-smoke / gen-xcube-catalog / copy-client)
|
|
392
430
|
docs/ specification + development notes + reading guide + diagrams/ (not packed)
|
|
393
431
|
```
|
|
394
432
|
|
|
@@ -396,7 +434,7 @@ docs/ specification + development notes + reading guide + d
|
|
|
396
434
|
|
|
397
435
|
- [Specification](docs/dsh-stm32-plugin-规格.md): tool contracts, state machine, acceptance criteria A1–A13
|
|
398
436
|
- [Development notes](docs/development-notes.md): milestones, host-contract pitfalls, implementation details and measured numbers
|
|
399
|
-
- [Source reading guide](docs/reading-guide.md): layered reading order, per-file responsibilities and exports, 14 flow diagrams,
|
|
437
|
+
- [Source reading guide](docs/reading-guide.md): layered reading order, per-file responsibilities and exports, 14 flow diagrams, 23 invariants
|
|
400
438
|
- Visuals: [architecture](docs/diagrams/dsh-stm32-architecture.html) / [main journey](docs/diagrams/dsh-stm32-journey.html) — single-file HTML, opens offline, exports PNG/SVG
|
|
401
439
|
|
|
402
440
|
## License
|