dsh-stm32 0.1.7 → 0.1.9
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 +567 -516
- package/README_EN.md +544 -510
- package/client/client.js +7033 -682
- package/docs/reading-guide.md +921 -859
- package/lib/client.js +7033 -682
- package/lib/commands/register.js +2 -0
- package/lib/data/firmware-packages.js +35 -0
- package/lib/data/firmware-pins.js +7 -0
- package/lib/data/install-guides.js +110 -0
- package/lib/data/ioc-presets.js +118 -0
- package/lib/engine/artifacts.js +123 -0
- package/lib/engine/breakpoint-hits.js +73 -0
- package/lib/engine/build.js +161 -5
- package/lib/engine/channel-tap.js +227 -0
- package/lib/engine/channels.js +48 -0
- package/lib/engine/clocks.js +192 -0
- package/lib/engine/datasheet/auto.js +74 -0
- package/lib/engine/datasheet/digest.js +74 -0
- package/lib/engine/datasheet/lcsc.js +60 -0
- package/lib/engine/datasheet/pinout.js +119 -0
- package/lib/engine/datasheet/price.js +152 -0
- package/lib/engine/datasheet/search.js +147 -0
- package/lib/engine/datasheet/store.js +371 -0
- package/lib/engine/debug-session.js +48 -2
- package/lib/engine/ecad/autobuild.js +156 -0
- package/lib/engine/ecad/bom.js +238 -0
- package/lib/engine/ecad/brief.js +205 -0
- package/lib/engine/ecad/checks.js +239 -0
- package/lib/engine/ecad/design.js +177 -0
- package/lib/engine/ecad/dfm.js +314 -0
- package/lib/engine/ecad/easyeda.js +454 -0
- package/lib/engine/ecad/fabrication.js +104 -0
- package/lib/engine/ecad/gen/footprint.js +159 -0
- package/lib/engine/ecad/gen/symbol.js +103 -0
- package/lib/engine/ecad/import.js +372 -0
- package/lib/engine/ecad/jlcpcb.js +141 -0
- package/lib/engine/ecad/libs.js +316 -0
- package/lib/engine/ecad/models3d.js +89 -0
- package/lib/engine/ecad/netgate.js +286 -0
- package/lib/engine/ecad/normalize.js +182 -0
- package/lib/engine/ecad/package.js +126 -0
- package/lib/engine/ecad/padmerge.js +128 -0
- package/lib/engine/ecad/padprecheck.js +123 -0
- package/lib/engine/ecad/part-import.js +257 -0
- package/lib/engine/ecad/pcb/apply.js +53 -0
- package/lib/engine/ecad/pcb/emc-deep.js +396 -0
- package/lib/engine/ecad/pcb/emc.js +275 -0
- package/lib/engine/ecad/pcb/geometry.js +63 -0
- package/lib/engine/ecad/pcb/gerber.js +499 -0
- package/lib/engine/ecad/pcb/hand-sync.js +242 -0
- package/lib/engine/ecad/pcb/impedance.js +119 -0
- package/lib/engine/ecad/pcb/ipc-open.js +78 -0
- package/lib/engine/ecad/pcb/ipc-script.js +276 -0
- package/lib/engine/ecad/pcb/ipc.js +129 -0
- package/lib/engine/ecad/pcb/krt.js +182 -0
- package/lib/engine/ecad/pcb/links.js +393 -0
- package/lib/engine/ecad/pcb/mech.js +201 -0
- package/lib/engine/ecad/pcb/model-fix.js +178 -0
- package/lib/engine/ecad/pcb/netlist.js +146 -0
- package/lib/engine/ecad/pcb/pcb-svg.js +199 -0
- package/lib/engine/ecad/pcb/placement.js +140 -0
- package/lib/engine/ecad/pcb/power.js +203 -0
- package/lib/engine/ecad/pcb/render3d.js +208 -0
- package/lib/engine/ecad/pcb/route.js +167 -0
- package/lib/engine/ecad/pcb/router.js +469 -0
- package/lib/engine/ecad/pcb/rules.js +122 -0
- package/lib/engine/ecad/pcb/scene.js +513 -0
- package/lib/engine/ecad/pcb/stackup.js +154 -0
- package/lib/engine/ecad/pcb/swap.js +222 -0
- package/lib/engine/ecad/pcb/tracks.js +70 -0
- package/lib/engine/ecad/runtime.js +227 -0
- package/lib/engine/ecad/toolchain.js +146 -0
- package/lib/engine/ecad/tsci.js +362 -0
- package/lib/engine/ecad/zip.js +98 -0
- package/lib/engine/event-bus.js +158 -0
- package/lib/engine/event-log.js +335 -0
- package/lib/engine/fault-hints.js +146 -0
- package/lib/engine/generate-script.js +4 -1
- package/lib/engine/generate.js +145 -5
- package/lib/engine/interrupts.js +247 -0
- package/lib/engine/ioc-diff.js +369 -0
- package/lib/engine/ioc-plan.js +12 -2
- package/lib/engine/ioc-sync.js +58 -0
- package/lib/engine/mcu-info.js +134 -0
- package/lib/engine/msys2-install.js +31 -6
- package/lib/engine/panel-actions.js +103 -0
- package/lib/engine/pdf/curve.js +321 -0
- package/lib/engine/pdf/png.js +83 -0
- package/lib/engine/pdf/reader.js +336 -0
- package/lib/engine/pdf/schematic.js +93 -0
- package/lib/engine/pdf/tables.js +249 -0
- package/lib/engine/pdf/toolchain.js +50 -0
- package/lib/engine/pinout.js +140 -0
- package/lib/engine/probe-info.js +95 -0
- package/lib/engine/probe.js +45 -0
- package/lib/engine/progress.js +99 -0
- package/lib/engine/project-conf.js +254 -0
- package/lib/engine/project-layout.js +198 -0
- package/lib/engine/project-repair.js +205 -0
- package/lib/engine/schematic/checks.js +153 -0
- package/lib/engine/schematic/draw.js +390 -0
- package/lib/engine/schematic/edit.js +229 -0
- package/lib/engine/schematic/kicad-sch.js +225 -0
- package/lib/engine/schematic/model.js +442 -0
- package/lib/engine/schematic/nets.js +219 -0
- package/lib/engine/schematic/pcb.js +144 -0
- package/lib/engine/schematic/review.js +134 -0
- package/lib/engine/schematic/sexpr.js +134 -0
- package/lib/engine/schematic/to-ioc.js +197 -0
- package/lib/engine/schematic/transform.js +25 -0
- package/lib/engine/session-context.js +106 -0
- package/lib/engine/source-slice.js +59 -0
- package/lib/engine/tool-events.js +119 -0
- package/lib/engine/toolchain-gate.js +8 -0
- package/lib/engine/watch-admin.js +101 -0
- package/lib/engine/watch-record.js +39 -0
- package/lib/engine/watch-recorder.js +116 -0
- package/lib/engine/web-api.js +1123 -4
- package/lib/engine/web-routes.js +18 -1
- package/lib/engine/workspace-memo.js +41 -0
- package/lib/index.js +118 -24
- package/lib/skill/stm32-workflow.js +1 -1
- package/lib/tools/build.js +10 -2
- package/lib/tools/code-patch.js +2 -2
- package/lib/tools/datasheet.js +447 -0
- package/lib/tools/debug-session.js +9 -4
- package/lib/tools/debug.js +2 -2
- package/lib/tools/doctor.js +2 -2
- package/lib/tools/ecad.js +903 -0
- package/lib/tools/flash.js +2 -2
- package/lib/tools/gen.js +166 -0
- package/lib/tools/generate.js +7 -5
- package/lib/tools/import-circuit.js +146 -0
- package/lib/tools/ioc-apply.js +11 -2
- package/lib/tools/ioc-inspect.js +2 -2
- package/lib/tools/ioc-plan.js +2 -2
- package/lib/tools/ioc-verify.js +2 -2
- package/lib/tools/layout.js +92 -0
- package/lib/tools/mcu-info.js +163 -0
- package/lib/tools/part-import.js +182 -0
- package/lib/tools/pcb.js +2316 -0
- package/lib/tools/pdf.js +423 -0
- package/lib/tools/project-create.js +28 -0
- package/lib/tools/project-dir.js +25 -1
- package/lib/tools/regs.js +2 -2
- package/lib/tools/route-plan.js +2 -2
- package/lib/tools/rtt.js +10 -2
- package/lib/tools/sch-draw.js +433 -0
- package/lib/tools/sch-edit.js +145 -0
- package/lib/tools/schematic.js +817 -0
- package/lib/tools/serial.js +22 -0
- package/lib/tools/watch.js +24 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,517 +1,568 @@
|
|
|
1
|
-
# dsh-stm32
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
[
|
|
8
|
-
|
|
9
|
-
[
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
|
41
|
-
|
|
|
42
|
-
|
|
|
43
|
-
|
|
|
44
|
-
|
|
|
45
|
-
| `
|
|
46
|
-
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
|
123
|
-
|
|
|
124
|
-
|
|
|
125
|
-
|
|
|
126
|
-
|
|
|
127
|
-
|
|
|
128
|
-
|
|
|
129
|
-
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
|
138
|
-
|
|
|
139
|
-
|
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
|
|
|
143
|
-
|
|
|
144
|
-
|
|
|
145
|
-
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
|
154
|
-
|
|
|
155
|
-
|
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
|
162
|
-
|
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
|
169
|
-
|
|
|
170
|
-
| `
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
| 工具 | 作用 |
|
|
177
|
-
| --- | --- |
|
|
178
|
-
| `stm32_ioc_inspect` | 解析 MCU 型号、引脚/信号/标签、外设与中断、时钟树、工程设置;会报「没开 Serial Wire 会生成 `SWJ_DISABLE`」这类致命风险 |
|
|
179
|
-
| `stm32_ioc_plan` | 改 `.ioc` 的第一步:算出逐键 diff 与源 SHA-256,返回 `planId`,**不动源文件**。支持改键、删键、按引脚表加 GPIO(上下拉/速度/开漏 `outputType: od`/初始电平 `initial`/`interrupt` 一次写全 EXTI 链路 + 中断组)、`interrupts` 使能外设中断(写 9 段 NVIC 值并按 db/SVD 校验中断名)、一键补 Serial Wire、按目标频率改时钟(`clock: { targetHz }`,就近取档 + 派生键重算 + 逐外设频率)。键名按 `src/data/ioc-schema.ts` 的 `.ioc` 真值表(49 条 spec)渲染。覆盖率闸门分两层:不在表里的键给 `[SCHEMA]` 警告;`{ip}.{name}` 这类只证「形状」的命中再按现场审计(db 的 `RefParameter` 参数名、`Mcu.IP<i>` 是否启用、Dma 参数白名单),拼错参数名/实例名同样报出来——拼错的键 CubeMX 静默忽略。启用外设时把 `Mcu.IP<i>` 按 CubeMX 自己的 natural 序重排(`TIM2…TIM4,TIM15`,板名等伪实例置尾),否则每次启用字典序靠前的外设,回写都会冒出几条假 diff |
|
|
180
|
-
| `stm32_ioc_apply` | 必须带 `planId`;写盘前再核 SHA(中途被手改就拒绝),备份后原子替换,写完重新解析校验,不过自动回滚。支持 `rollbackFrom` |
|
|
181
|
-
| `stm32_ioc_verify` | 让 CubeMX 自己说「它认了什么」:把 `.ioc` 复制到 `.dsh-stm32/verify/<stamp>/`,无头 `config load` + `config save` 回写后逐键 diff(实测一次 100–180 s,工程 `.ioc` 一个字节不动;CubeMX 没保存完直接判失败,不拿「零 diff」假通过)。报 `droppedPeripherals` / `plannedFunctions` / `signalRewrites` / `removedKeys` / `addedKeys` / `changedValues`,以及归因 `attribution`:`orderOnly`(值相同、行序不同)/ `valueNormalized`(只是成员顺序被规范化)/ `valueChanged`(值真被改)/ `ipOrderOnly`(只有 `Mcu.IP<i>` 换位、外设集合不变,不算实质差异)/ `derivedRecomputed`(`RCC.*Freq_Value` 这类**派生频率**被 CubeMX 按 PLL/分频重算——不是设定,计划里没写过就不算差异)/ `derivedAdded`(它按树自己补的派生键)/ `ipParametersAdded`(`RCC.IPParameters` 里它追加的派生名) / `droppedReasons` 与 `addedVerdicts`(**逐键给「为什么它不认」**:外设没进 `Mcu.IP<i>`、参数名不在 db 的 `RefParameter` 清单里、把引脚属性写成了外设参数、前缀纯拼错)/ `benign`——**`benign: true` 就是零实质差异**,可以放心去 `stm32_generate` |
|
|
182
|
-
|
|
183
|
-
### 代码与构建
|
|
184
|
-
|
|
185
|
-
| 工具 | 作用 |
|
|
186
|
-
| --- | --- |
|
|
187
|
-
| `stm32_code_patch` | 只在 `USER CODE` 块内 replace/append;块外字节(含 CRLF)原样保留;写前备份、临时文件 + rename 原子替换。标签写错会把该文件所有可用标签列给你 |
|
|
188
|
-
| `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 里警告 |
|
|
189
|
-
| `stm32_build` | `cmake --build`,构建目录从 `CMakePresets.json` 与 `build/*/CMakeCache.txt` 推断;首次构建自动 configure;会拦住"CMakeCache 目录不一致但 ninja 退出码 0"的假成功。`artifacts: ["hex","bin"]` 时链接后用 `arm-none-eabi-objcopy` 转出,转换失败只记 note、不判编译失败 |
|
|
190
|
-
|
|
191
|
-
### 烧录与调试
|
|
192
|
-
|
|
193
|
-
| 工具 | 作用 |
|
|
194
|
-
| --- | --- |
|
|
195
|
-
| `stm32_flash` | **烧录**:openocd `program verify reset exit`,不建调试会话、不停 `main`。烧前读 `.ioc`,调试口没开就拒绝(见 [设计要点](#设计要点))。失败会带结构化 `probeError`:`kind`(`no-probe` / `probe-interface-mismatch` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `timeout` / `unknown` 共 9 类)、`cause`(一句话根因)、`hint`(可执行的下一步,每类都有专属建议)、`evidence`(原始日志行)、`retryable`(照 hint 处理完再调一次有没有意义);成功时这个字段根本不出现。日志里找不到设备时,还会把 USB 形态(这台机器没有 USB / 没插探针 / 驱动异常)写进 notes |
|
|
196
|
-
| `stm32_debug_run` | 起 openocd + gdb,`break main` → `continue` → 抓 pc/sp/lr/bt/locals → `reset run` + `detach`,不写 Flash、不常驻。硬件断点 / 观察点超芯片上限(F1 是 6 个断点 / 4 个观察点)会在起 openocd **之前**就报错,不占探针 |
|
|
197
|
-
| `stm32_debug_session` | 常驻 openocd 会话(`.elf` 自动解析),空闲 90 s 自动关、硬上限 10 min |
|
|
198
|
-
| `stm32_debug_eval` | 在会话里执行 gdb 命令或读表达式(如 `g_led_blink_count`),读完立刻 `resume` + `detach` |
|
|
199
|
-
| `stm32_debug_stop` | 立刻释放探针,幂等 |
|
|
200
|
-
| `stm32_regs_read` | 读寄存器,`addresses` 五种写法:物理地址 `0x4001100C` / `4001100C`、符号名 `GPIOC.ODR` / `GPIOC->ODR`、只写外设名 `GPIOC`(按偏移升序把它的 7 个寄存器整体 dump,上限 64 条)。内置资源含 SVD(full 逻辑层)时,每条样本带规范化名与**置位位域**(`GPIOC.ODR (0x4001100C) = 0x00000020 → ODR5=1`);未知外设会列出可用的前 10 个(共 53 个),未知寄存器会列出该外设的已知寄存器;没有 SVD 时纯地址照读(只是没有名字与位域),符号名报错并提示「SVD 只在 profile=full:重装插件」。收尾用 `resume` 而不是 `reset run`,避免读一眼就把固件状态清零;连读时复用常驻 openocd 会话(毫秒级,不另起进程),没有会话才起一次并保留 90 s |
|
|
201
|
-
| `stm32_watch` | **变量监视与硬件观察点**:`action: "add"` 登记表达式(`expressions`,`kind` 默认 `value`=每次 `sample` 求值;`write` / `read` / `access` 走 gdb `watch` / `rwatch` / `awatch`,是**数据**比较器,和代码断点不共用预算,F1 只有 4 个,超出在起进程之前就拒绝)。`kind=value` 只登记、不需要会话。`action: "sample"` 停下→逐项求值→和上次值算 `delta`→原本在跑就 `monitor resume` 放回去(`resume: false` 可留住);出错时保留上一次的值并写 `lastError`。`action: "list"` / `"remove"`(`ids`)/ `"clear"` 管登记表。生命周期:会话 `stop` 时清表(观察点住在 gdb 进程里);MI 重建会把观察点标成失效并提示重新 `add`。gdb 退回**软件观察点**时会在 `notes` 里警告(会拖慢目标) |
|
|
202
|
-
| `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 端口被占 |
|
|
203
|
-
|
|
204
|
-
### 固件里怎么加 RTT(最短示例)
|
|
205
|
-
|
|
206
|
-
寄存器版工程(`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 块里加三行:
|
|
207
|
-
|
|
208
|
-
```c
|
|
209
|
-
/* USER CODE BEGIN 2 */ /* 必须在时钟初始化之后:时间戳按 SystemCoreClock 换算 */
|
|
210
|
-
rtt_init();
|
|
211
|
-
rtt_printf(RTT_LEVEL_INFO, "boot: sysclk=%lu", (unsigned long)SystemCoreClock);
|
|
212
|
-
/* USER CODE END 2 */
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
(`rtt.h` 已经在 `Core/Inc` 里,也可以再显式写一行 `#include "rtt.h"` 到 `USER CODE BEGIN Includes`。)编译后在宿主侧取控制块地址:
|
|
216
|
-
|
|
217
|
-
```powershell
|
|
218
|
-
arm-none-eabi-nm build/Debug/<工程名>.elf | findstr _SEGGER_RTT
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
然后让模型跑这三步(下面是 `stm32_rtt` 的三次工具调用,参数名与工具 schema 一致):
|
|
222
|
-
|
|
223
|
-
```text
|
|
224
|
-
stm32_rtt action=start addr=0x20000DE0 # 控制块地址,来自上面那行 nm
|
|
225
|
-
stm32_rtt action=dump seconds=3 level=3 # 读 3 秒内 info 及以上级别
|
|
226
|
-
stm32_rtt action=stop # 释放端口;turn 结束也会自动停
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
启用后 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()` 能查丢了多少。
|
|
230
|
-
|
|
231
|
-
## 串口(Windows P1)
|
|
232
|
-
|
|
233
|
-
`stm32_serial` 让模型自己开串口、收发、等回包——不用你先开串口助手再复制粘贴。它是 **P1**:只做 Windows 上的最小可用闭环,边界写在下面,不假装能做全。
|
|
234
|
-
|
|
235
|
-
| 动作 | 做什么 |
|
|
236
|
-
| --- | --- |
|
|
237
|
-
| `list` | 列所有 COM 口:PnP 名称、VID/PID、序列号、位置,以及每个口记住的参数(按 USB 身份记忆,换 USB 口 / 换 COM 号也能复用上次的波特率) |
|
|
238
|
-
| `open` | 起一个常驻 PowerShell 桥并等 `state=open`(最多 5 s);省略 `port` 时用 `serial.json` 里上次成功的口 |
|
|
239
|
-
| `read` | 读收到的行(`rx.ndjson` 尾部);给 `cursor`(上次返回的 `nextCursor`)就只拿新行,AI 不会每轮把历史重贴进上下文 |
|
|
240
|
-
| `send` | 发一行,等桥的 `done` 回执(最多 2 s);默认自动补 CRLF,`raw: true` 原样发 |
|
|
241
|
-
| `transact` | 发一行并等期望的回包:`until` 是正则(如 `OK|ERROR`),命中返回 `matched` / `matchedLine`,等到超时只报 `timedOut` 不算失败 |
|
|
242
|
-
| `status` | 只读快照:会话、桥 pid、`rx.ndjson` / `tx.ndjson` 大小、可能残留的会话目录 |
|
|
243
|
-
| `close` | 先礼后兵:发 `close` 等 3 s,还不退就杀 pid |
|
|
244
|
-
|
|
245
|
-
默认参数:**115200 8N1、无流控、DTR/RTS 都不拉高(拉高很多板子会复位)、UTF-8、发送补 CRLF**;`persist=false` 表示 turn 结束时自动关口(`persist=true` 才跨 turn 保留)。**单会话**:一个进程同时只开一个口,重复 `open` 报 `already-open` 并提示先 `close`——「同一个口被两个逻辑会话抢」这种最难查的问题在源头就不存在。
|
|
246
|
-
|
|
247
|
-
```text
|
|
248
|
-
stm32_serial action=list
|
|
249
|
-
stm32_serial action=open port=COM3 baudRate=115200
|
|
250
|
-
stm32_serial action=send text="AT"
|
|
251
|
-
stm32_serial action=transact text="AT" until="OK|ERROR" timeoutMs=1000
|
|
252
|
-
stm32_serial action=read cursor=0
|
|
253
|
-
stm32_serial action=close
|
|
254
|
-
```
|
|
255
|
-
|
|
256
|
-
**为什么是 PowerShell 桥**:插件有硬性的零 npm 依赖要求,而 Node 没有内建串口;Windows 自带 PowerShell 5.1 + `System.IO.Ports.SerialPort`。所以真正握着 COM 口的是一个独立于工具调用的桥进程(`templates/serial/bridge.ps1`,`spawn` + `unref`——Windows 上不能用 `detached`,那会翻成 `DETACHED_PROCESS`,PowerShell 5.1 直接退出),Node 侧只通过一个目录里的文件跟它说话(`cmd/<id>.json` 进、`done/<id>.json` 回、`rx.ndjson` / `tx.ndjson` 记流水、`status.json` 报状态)。桥每 5 s 查一次父进程:DSH 被杀(关窗口 / 重启宿主)时它自己放口退出——否则那个 COM 口会永远「被占用」。文件位置:`%USERPROFILE%\.dsh-stm32\serial\<sessionId>\`(`DSH_STM32_SERIAL_HOME` 可改根)。
|
|
257
|
-
|
|
258
|
-
端口参数记忆在 `%USERPROFILE%\.dsh-stm32\serial.json`(`DSH_STM32_SERIAL_CONFIG` 可改),身份按 `usb:VID:PID:序列号` → `usb:VID:PID@位置` → `com:COMx` 三档降级;只有成功的 `open` 才写记忆。失败会带 11 类结构化错误(`unsupported-platform` / `powershell-missing` / `port-not-found` / `port-busy` / `access-denied` / `settings-invalid` / `bridge-start-timeout` / `bridge-crashed` / `disconnected` / `already-open` / `no-session`),每类都给中文 `cause` / `hint`。
|
|
259
|
-
|
|
260
|
-
**P1 明确不含**:右侧串口面板(本工具只出文本报告,前端不画 UI)、SSE / WebSocket 推流(`read` 是拉取式)、Linux / macOS(桥是 PowerShell,非 Windows 直接 `unsupported-platform`)、**自动重连**(断开后由调用方重新 `open`)。真机成功路径(`state=open`、真实收数、DTR/RTS 实际电平)在 0.1.5 里只有假桥与失败路径证据,见[已知限制](#已知限制)与 development-notes §86。
|
|
261
|
-
|
|
262
|
-
## 斜杠命令
|
|
263
|
-
|
|
264
|
-
工具是给模型调的;你要自己动手时用命令,一条命令一个动作,不经过模型决策。
|
|
265
|
-
|
|
266
|
-
| 命令 | 做什么 | 会不会动板子 |
|
|
267
|
-
| --- | --- | --- |
|
|
268
|
-
| `/stm32-doctor` | 体检:工具链、被占用的调试进程、端口、`.elf`、`.ioc` 告警 | 否 |
|
|
269
|
-
| `/stm32-setup` | 体检 + 安装计划一次跑完;命令里带「装」字才真装(例如 `/stm32-setup 装上缺的`) | 否 |
|
|
270
|
-
| `/stm32-env` | 看四项能力(编译 / 烧录 / 调试 / 生成代码)各缺什么、装什么、装完怎么自检;缺件也照常出卡片 | 否 |
|
|
271
|
-
| `/stm32-build [dir] [--clean]` | 编译,打印内存占用 / `.elf` / 错误 | 否 |
|
|
272
|
-
| `/stm32-flash [dir]` | **烧录**:program + verify + reset,不建调试会话、不下断点 | 是 |
|
|
273
|
-
| `/stm32-debug [dir]` | **烧录 + 调试**:烧完停到 `main`,会话保留(空闲 3 分钟 / 上限 10 分钟,本轮结束也会自动关) | 是 |
|
|
274
|
-
| `/stm32-stop` | 关掉 `/stm32-debug` 开的会话,把探针还给 VS Code | 否 |
|
|
275
|
-
|
|
276
|
-
`[dir]` 省略时用当前会话的工作目录。
|
|
277
|
-
|
|
278
|
-
## 设计要点
|
|
279
|
-
|
|
280
|
-
- **烧录与调试是两条路。** `stm32_flash` 只用 openocd 的 `program/verify/reset/exit`,成功证据是日志里出现 `** Programming Finished **` 与 `** Verified OK **`,不是"没报错"。
|
|
281
|
-
- **只写 USER CODE。** 改逻辑用 `stm32_code_patch`;`stm32_generate` 重新生成时按标签把旧内容搬回新文件,所以手改生成区或整文件重写在重新生成后都会丢。
|
|
282
|
-
- **`.ioc` 是事务。** `plan` 只算 diff 出 `planId`,`apply` 才写盘,写前核 SHA、写后重新解析、失败回滚。
|
|
283
|
-
- **烧前守卫。** 如果 `.ioc` 的 SYS 调试口不是 Serial Wire(PA13/PA14 缺失或被设成 `No_Debug`),CubeMX 会生成 `__HAL_AFIO_REMAP_SWJ_DISABLE()`——烧进去 SWD 立刻失联,只能 BOOT0 救砖。这种工程 `stm32_flash` 直接拒绝;确实要烧得显式传 `allowNoDebug: true`。
|
|
284
|
-
- **探针只有一块。** 烧录、调试、后台会话同一时刻只能有一个;`build` / `flash` / `debug_run` / `generate` 开跑前会先把占着探针的会话关掉。
|
|
285
|
-
|
|
286
|
-
## 芯片、链接脚本与时钟
|
|
287
|
-
|
|
288
|
-
- **型号是参数,不是常量。** `stm32_project_create` / `stm32_generate` 按 `mcu` 一起换三样:启动文件(`startup_stm32f103xe.s`)、设备宏(`STM32F103xE`)、链接脚本(`STM32F103RCTx_FLASH.ld`)。HAL 路线走 `src/engine/hal-chip.ts`(`resolveHalChip()` 按族分发:F1 走手写 RAM 表,其它族走内置资源的 `device/<族>/chips.json`;`renderStartupAndDefine` / `renderLinkerScript` / `renderIoc` / `renderCmakeLists` / `renderOpenocdTarget`),寄存器路线走 `src/data/stm32f1.ts`(`resolveF1Chip()`,14 个容量档,每个启动文件都钉了上游 sha256)。认不出的型号直接给原因,不猜一个上游不存在的启动文件名。
|
|
289
|
-
- **链接脚本按 `DeviceId` 命名:`<DeviceId>_FLASH.ld`。** C8T6 → `STM32F103C8Tx_FLASH.ld`(64 KiB Flash / 20 KiB RAM),RCT6 → `STM32F103RCTx_FLASH.ld`(256 / 48),F107VCT6 → `STM32F107VCTx_FLASH.ld`(256 / 64)。模板里那份旧的 `STM32F103XX_FLASH.ld` 只作 C8T6 的兼容副本;CMake 的 `-T` 一律指向按型号渲染的那份(`pointLinkerFlagAt()` 把工具链文件里的旧名改指过去,避免两个 `-T` 让 ld 取错脚本)。
|
|
290
|
-
- **时钟就近,不可达就明说。** `stm32_ioc_plan` 的 `clock: { targetHz }`(也可 `pllMul` 钉死倍频、`pllSource` 选 HSE / HSI)枚举全部可行的 PLL 组合,取 |SYSCLK − 目标| 最小的一档,并把差距写进结论:要 60 MHz 时 F1 的 PLL 只能整数倍频、HSE 8 MHz 拼不出这一档,于是选 64 MHz 并标注「不可达,已选 64 MHz(+4 MHz)」(同距取更高档)。同一次 plan 里把 `SYSCLKFreq_VALUE` / `HCLKFre` / `PLLMUL` / APB1·APB2·ADC 分频这些派生键**全量重算**——只改 SYSCLK 不动它们,CubeMX 会按旧值重算或干脆不认;同时列出逐外设频率、UART 波特率的整除误差与几个备选档。超限(SYSCLK > 72 MHz、APB1 > 36 MHz、ADC > 14 MHz、USB 要 48 MHz 却不在 PLLCLK/1.5 这条路上)时**一个键都不写**。
|
|
291
|
-
- **烧前五项一致。** `stm32_doctor` 核对「`.ioc` 型号 ↔ 启动文件名 ↔ cmake 里的设备宏 ↔ `.ld` 的 MEMORY 容量 ↔ `.elf` 的 Flash 占用」,任一错配报 blocker。`.elf` 那份占用是读 ELF program header 的 `p_filesz` 累加,不是文件大小——带 `-g3` 时 20 KiB 固件的 `.elf` 能有 600 KB,按文件大小判会误报「超 Flash」。
|
|
292
|
-
- **寄存器路线按芯片给内存映射,不按族套一张表。** 21 族的启动文件、设备宏、Flash/RAM 都来自 `assets/device/<族>/chips.json`;H7 默认只用 DTCM 128 KiB(`0x20000000`,138 颗都带 `linkerRam`),U5 按 line 给 256 KiB / 768 KiB / 2496 KiB 的 SRAM 窗口,L4+ 与 L5 是单块连续(L5 的 192+64 KiB 相邻,合并成 256 KiB)。链接脚本的 `MEMORY` ORIGIN/LENGTH 随之渲染,`_estack` 落在窗口顶上——不会出现「编译过、上电 HardFault」的静默越界(见 development-notes §87)。
|
|
293
|
-
|
|
294
|
-
## 配置
|
|
295
|
-
|
|
296
|
-
### 用户配置文件(`~/.dsh-stm32/config.json`)
|
|
297
|
-
|
|
298
|
-
工具装在哪,插件自己记。`stm32_env_install` 装完会写这个文件,之后所有工具读它——**不用重启 DSH、也不用设环境变量**。手写也行:
|
|
299
|
-
|
|
300
|
-
```json
|
|
301
|
-
{
|
|
302
|
-
"version": 1,
|
|
303
|
-
"msys64": "E:/msys64",
|
|
304
|
-
"binDirs": [],
|
|
305
|
-
"packages": ["mingw-w64-ucrt-x86_64-arm-none-eabi-gcc", "mingw-w64-ucrt-x86_64-cmake"],
|
|
306
|
-
"cubeMxRoot": "",
|
|
307
|
-
"updatedAt": "2026-02-01T00:00:00.000Z"
|
|
308
|
-
}
|
|
309
|
-
```
|
|
310
|
-
|
|
311
|
-
`binDirs` 留空时由 `msys64` 推出 `<msys64>/ucrt64/bin`——安装器写的就是这个形状。文件坏了(JSON 不合法)不会让工具报错,只是当它不存在。
|
|
312
|
-
|
|
313
|
-
**优先级**:工具参数(`binDirs` / `cubeMxRoots`)> 环境变量 > 这个配置文件 > 内置默认值;自动发现只追加在"没点名参数"的那一档尾部。
|
|
314
|
-
|
|
315
|
-
**内置默认值里没有任何"某台机器专属"的路径**:只有 `C:/msys64/...` 与 `C:/Program Files/...` 这种 Windows 默认安装位置,装在别处靠自动发现兜底。配置或环境变量里点名的目录如果在本机不存在(典型情况:配置是从别的机器拷过来的,带着 `D:/app/msys64` 这种路径),门禁与 `stm32_doctor` 会明确写一句「配置文件里的 X 在本机不存在……这一条搜不到工具」,而**不会**悄悄改你的配置;安装器也不会拿这种路径当安装目标(盘符都没有时只提示、并要求你给 `targetDir`)。
|
|
316
|
-
|
|
317
|
-
### 设置面板(GUI)
|
|
318
|
-
|
|
319
|
-
上面那个配置文件也能不碰命令行改:DSH 的 **设置 → STM32 工具链**(插件自带的浏览器端面板,与宿主同源,零额外依赖)。三张卡:
|
|
320
|
-
|
|
321
|
-
- **装在哪**:读当前配置,改 `msys64` / `cubeMxRoot` / 额外 `binDirs` 后保存——写的就是上面那个文件,下一条工具调用就读得到,不用重开 DSH;
|
|
322
|
-
- **缺什么**:跑一次探测(会执行各工具的版本命令,不装任何东西),逐项显示找到的路径与版本、缺件的 `hint`,以及编译 / 烧录 / 调试 / 生成四项能力徽章;
|
|
323
|
-
- **装工具链**:先出计划(步骤、下载体积、PATH 与配置会怎么改),**再点一次确认**才真装;装的过程实时显示步骤与日志尾巴,实际执行与 `stm32_env_install` 是同一个安装器。工具链已经完整时,计划只回一句话「工具链完整,不需要装任何东西」,不列那七行「已跳过」。
|
|
324
|
-
|
|
325
|
-
接口是插件注册在宿主上的六条 `/dsh-stm32/api/*`(读配置、存配置、探测、安装计划、开始安装、安装进度);面板产物是 `lib/client.js`,源码在 `client/client.js`,由 `npm run build` 原样复制——手写纯 JS、只 `require("react")`,不引入打包器或运行时依赖。宿主没有 `webServer` 服务时(纯 CLI 组合)这层注册自动跳过,工具与斜杠命令不受影响。
|
|
326
|
-
|
|
327
|
-
### 下载缓存(寄存器版模板)
|
|
328
|
-
|
|
329
|
-
寄存器版工程要的 CMSIS 设备头、启动文件、内核头**不预置进插件**(要覆盖任意 STM32,每颗都打一份会让包大到不可用),而是第一次用时从网上下载,落到一个可检索的缓存目录,之后一直复用:
|
|
330
|
-
|
|
331
|
-
- 位置:`DSH_STM32_CACHE`(支持 `~`)> `%LOCALAPPDATA%\dsh-stm32\cache`;
|
|
332
|
-
- 索引:缓存根下 `index.json` 记录每条源 URL、字节数、许可(`THIRD_PARTY_NOTICES.md` 随条目一起写);
|
|
333
|
-
- 下载源:按 `fastly.jsdelivr` → `cdn.jsdelivr` → `raw.githubusercontent` → `ghproxy` 的顺序回退,HTTP 错误 / 内容像网页 / 字节数明显不对都算该源失败;
|
|
334
|
-
- 半截缓存会被整条删掉(比没有缓存更糟);条目文件缺失或大小对不上时下次自动重下;
|
|
335
|
-
- 看得见、清得掉:`stm32_cache` 的 `list` / `verify` / `fetch` / `purge`。
|
|
336
|
-
|
|
337
|
-
### 固件包下载(HAL 路线)
|
|
338
|
-
|
|
339
|
-
CubeMX 装好也不一定有**这一颗芯片**的固件包(安装包里不带,得在包管理器里另装)。`stm32_firmware_install` 有两条通道,默认先试官网:
|
|
340
|
-
|
|
341
|
-
- 官网直取(`source: "auto"` 的第一步):按 db 里那颗芯片的 `FwLibrary`(多数族为空,按族名兜底;H7RS / MP13 / WB0 / WL3 有专名)拼 `https://sw-center.st.com/packs/resource/firmware/stm32cube_fw_<族小写>_v<版本去点>.zip`,下载后验 `Content-Length` 与 zip 里每一条的 CRC32,再调 CubeMX 的 `swmgr install <本地 zip> ask` 装进 `Repository`——这个包是 CubeMX 自己记账的,包管理器里看得见、删得掉;
|
|
342
|
-
- 三种失败会把原因写进 `notes` 再回退下面的 GitHub 拼包:没装 CubeMX、CubeMX 正开着 GUI、**首次装某族的新版本时 CubeMX 要弹许可协议窗等人点同意**(无头只能超时,插件不替你点,也不代勾);`source: "official"` 则只走这条,失败直接报错;
|
|
343
|
-
|
|
344
|
-
回退通道(GitHub 拼包):
|
|
345
|
-
|
|
346
|
-
- 下什么:`stm32f1xx-hal-driver`(HAL 驱动,BSD-3-Clause)+ `cmsis-device-f1`(设备头与启动文件,Apache-2.0)+ 5 个 CMSIS 内核头,合计约 2 MB、几秒钟;
|
|
347
|
-
- 完整性:每个归档只走 `codeload.github.com/<repo>/tar.gz/refs/heads/<ref>` 一条源,归档与每个内核头都在 `src/data/firmware-pins.ts` 钉了 sha256(维护脚本 `scripts/firmware/pin-firmware.mjs` 重算);下载内容对不上哈希就整包拒收,不会解压落盘。上游 master 挪动文件时,报错会给出期望/实际哈希;
|
|
348
|
-
- 为什么不能直接解压 `STM32CubeF1` 的源码包:它的 HAL 与 CMSIS 设备目录是 **git 子模块**,tarball 里是空目录——解压出来编译必挂(缺 startup、缺 HAL 源文件);
|
|
349
|
-
- 装到哪:默认 `<CubeMX 根>/dsh-firmware/<包名>`(与 `Repository` 并列、插件自建,不动官方包);这个根写不进去才退回用户缓存目录。**别往 `Repository` 里塞自造版本号**——实测 CubeMX 认不出那个版本名,不报错地退回它自己认识的包(生成「成功」,HAL 却是旧版);
|
|
350
|
-
- 生成时怎么用上它:`stm32_generate` 按 `.ioc` 的 `ProjectManager.FirmwarePackage` 找包(`Repository` 与 `<CubeMX 根>/dsh-firmware` 都找),并在 CubeMX 脚本里发 `project setCustomFWPath <包目录>`——这是唯一被实测有效的机制,不往 `.ioc` 里写绝对路径;
|
|
351
|
-
- 组装包与官方包同构:自写 6 行 `package.xml`(版本串 `FW.<族>.<x.y.z>`)与 `THIRD_PARTY_NOTICES.md`;`package.xml` 里不写哈希清单(CubeMX 不校验来源),完整性由下载阶段逐文件 sha256 保证——已实测:用 `setCustomFWPath` 指过去生成,拷出的 HAL 源文件逐字节来自我们目录;
|
|
352
|
-
- 但「生成成功」不能当验收:`.ioc` 点名了不存在的包时 CubeMX 不报错、退出码 0、只是不拷 HAL。所以装完必须过五条判据(内核头 / HAL Inc / HAL Src / 设备头 / `startup_*.s`),插件装完自己就验一遍。
|
|
353
|
-
|
|
354
|
-
### 安装包下载(只下载,不安装)
|
|
355
|
-
|
|
356
|
-
`stm32_download` 把「拿到安装包」和「装它」分开:插件只负责下载/校验,安装由你自己双击。
|
|
357
|
-
|
|
358
|
-
| 组件 | 行为 |
|
|
359
|
-
| --- | --- |
|
|
360
|
-
| `jlink` | 从 SEGGER 官方直链下载 8.18.0(约 59 MB),边下边算 SHA256,和官方值 `63110b6fc55e494d197d6efa156d7f61c0dd0c1f776424995a05407e2d7f566f` 对比;已存在且哈希正确直接复用;失败/哈希不符删临时文件 |
|
|
361
|
-
| `cubemx` / `cubeprogrammer` | ST 官网要登录 myST、接受许可,直链会过期:默认只返回官方页;`dryRun:false + confirm:true` 打开浏览器。也可 `file: "D:/.../installer.exe"` 只计算 SHA256,供你自己核对 |
|
|
362
|
-
|
|
363
|
-
默认 `dryRun:true`,只出计划,不联网。下载目录 `%LOCALAPPDATA%\dsh-stm32\downloads`,可用 `DSH_STM32_DOWNLOADS` 或 `outDir` 覆盖。工具不会执行安装器、不写注册表、不改 PATH;J-Link 的 USB 驱动需要你在安装器里选 all users 并允许 UAC(现代探针默认 WinUSB,老探针才需要 legacy 驱动)。
|
|
364
|
-
|
|
365
|
-
### 环境变量(可选)
|
|
366
|
-
|
|
367
|
-
| 变量 | 作用 | 默认 |
|
|
1
|
+
# dsh-stm32
|
|
2
|
+
|
|
3
|
+
[](https://github.com/JingYu-er/dsh-stm32)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](#已知限制)
|
|
6
|
+
[](#已知限制)
|
|
7
|
+
[](https://github.com/JingYu-er/dsh-stm32/releases)
|
|
8
|
+
|
|
9
|
+
STM32 全流程工具层,以 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 插件形式分发:37 个工具、7 条斜杠命令与 1 个随包下发的 SKILL,把「工具链探测 → 建工程 → 改 `.ioc`(含时钟)→ 生成代码 → 编译 → 烧录 → 调试 → 回读寄存器」这条链交给模型执行,另含串口交互(Windows)与会话内的「调试台」面板。
|
|
10
|
+
|
|
11
|
+
在支持范围内,同一套工具从 F1 到 H7 用法一致;遇到不支持的芯片或功能,调用时会直接说明缺什么,不会给出一份猜出来的结果。
|
|
12
|
+
|
|
13
|
+
| 能力面 | 覆盖范围 |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| 芯片族 | 27 个族:C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / MP1 / MP2 / N6 / U0 / U3 / U5 / WB / WB0 / WBA / WL / WL3 |
|
|
16
|
+
| HAL 建工程 | 21 个单核族:C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / U0 / U3 / U5 / WBA / WL |
|
|
17
|
+
| 寄存器建工程 | 21 族,均通过 create→build 编译矩阵 |
|
|
18
|
+
| 时钟规划 | 18 族;其中 PLL1 为 H5 / U5 / WBA / L4+ |
|
|
19
|
+
| `.ioc` 外设预设 | 按 CubeMX 官方数据派生:串口 / SPI(全双工、只发、只收)/ I2C / TIM PWM / ADC |
|
|
20
|
+
| 寄存器名与位域 | F1 |
|
|
21
|
+
|
|
22
|
+
**English:** [README_EN.md](./README_EN.md)
|
|
23
|
+
|
|
24
|
+
[快速开始](#快速开始最小验证空目录到灯在闪) · [工具参考](#工具参考) · [斜杠命令](#斜杠命令) · [调试台](#调试台面板) · [配置](#配置) · [已知限制](#已知限制) · [排错](#排错) · [规格书](docs/dsh-stm32-plugin-规格.md)
|
|
25
|
+
|
|
26
|
+
## 拆分说明(0.1.9 起)
|
|
27
|
+
|
|
28
|
+
硬件侧能力(画原理图、PCB、Gerber、3D、BOM、叠层/阻抗、EMC、机械)已拆到独立插件 **dsh-ecad**,本插件只保留固件侧:工具链、`.ioc` 事务、建工程、编译、烧录、调试、串口/RTT/监视、证据与调试台,另保留「查看 KiCad 原理图、对照引脚、一键评审、导出 `.ioc` 草案」这些固件闭环需要的读图能力。
|
|
29
|
+
|
|
30
|
+
两个插件通过 `<工程>/dsh/mcu.json`(本插件写,`schema: dsh-mcu/1`,含 `.ioc` 的 sha256 指纹)交换 MCU 事实;同名工具不会重复注册。
|
|
31
|
+
|
|
32
|
+
## 它能做什么
|
|
33
|
+
|
|
34
|
+
多数「让 AI 编写 STM32 代码」的方案止于代码层:产出一段 `main.c`,能否编译、烧录后灯是否按预期闪烁,仍要在 CubeMX、终端与调试器之间手工确认。模型看不到板子,也就无法对结果负责。
|
|
35
|
+
|
|
36
|
+
本插件把硬件侧接入 DSH:`.ioc` 可读可改(事务 + 回滚),代码只写入 `USER CODE` 块,生成与编译返回真实报错行,烧录不与调试器抢占探针,烧录后读回寄存器状态。每一步都有可核对的结果(计划编号、`文件:行:列`、`Verified OK`、`GPIOC.ODR` 的 bit13,有寄存器表时直接给出 `ODR13=1`),模型据此决定下一步。
|
|
37
|
+
|
|
38
|
+
| 环节 | 手工流程 | 本插件 |
|
|
39
|
+
| --- | --- | --- |
|
|
40
|
+
| 建工程 | GUI 配置时钟树、引脚与工程参数,生成 CMake,手写 `launch.json` | `stm32_project_create` 约 2 秒产出模板工程(与 CubeMX GUI 产物一致,`.vscode` 内两份配置就位) |
|
|
41
|
+
| 改配置 | GUI 修改后重新生成,担心 `USER CODE` 丢失 | `stm32_ioc_plan` 先出差异(不写盘)→ 确认 → `stm32_ioc_apply` 带校验、备份与失败回滚 |
|
|
42
|
+
| 写代码 | 整文件编辑,易写入生成区,重新生成后丢失 | `stm32_code_patch` 只写 `USER CODE` 块,块外逐字节保留 |
|
|
43
|
+
| 编译 | Keil,或自行维护 CMake 与 VS Code 任务 | `/stm32-build [目录] [--clean]` |
|
|
44
|
+
| 烧录 | Keil,或手写 `tasks.json` 调 openocd | `/stm32-flash [目录]` |
|
|
45
|
+
| 验证 | 断点调试,手工查看寄存器 | `stm32_regs_read` 回读状态:`GPIOC.ODR` 两次采样确认计数递增,`AFIO.MAPR` 确认 SWD 未被固件关闭 |
|
|
46
|
+
| 调试 | 按 F5 手动下断点,结束再关会话 | `stm32_debug_run` 停在 `main` 抓取一次现场后释放探针;连续调试才开 `stm32_debug_session`,空闲自动关闭 |
|
|
47
|
+
|
|
48
|
+
## 安装
|
|
49
|
+
|
|
50
|
+
### 安装插件
|
|
51
|
+
|
|
52
|
+
只需先具备 DSH 本体,工具链可以稍后补。
|
|
53
|
+
|
|
54
|
+
```powershell
|
|
55
|
+
dsh plugin --profile desktop add dsh-stm32
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`dsh plugin` 等价于在 profile 目录执行 `pnpm add`,并把 `dsh-stm32` 写入该 profile 的 `dsh.profile.bundles`。安装后完全退出 DSH 再启动(插件层只在进程启动时加载)。
|
|
59
|
+
|
|
60
|
+
- 校验:`dsh plugin --profile desktop why dsh-stm32` 显示 `0.1.8`
|
|
61
|
+
- 卸载:`dsh plugin --profile desktop remove dsh-stm32`,随后重启 DSH
|
|
62
|
+
- 装到 Web:把 `desktop` 换成 `web`
|
|
63
|
+
|
|
64
|
+
### 补齐工具链
|
|
65
|
+
|
|
66
|
+
插件装好后即可解析 `.ioc`、查看引脚 / 时钟 / 中断、预览计划;真正编译、烧录、调试时才需要编译器与探针工具。
|
|
67
|
+
|
|
68
|
+
| 要做什么 | 需要什么 | 怎么补 |
|
|
69
|
+
| --- | --- | --- |
|
|
70
|
+
| 编译 | `arm-none-eabi-gcc`、`cmake`、`ninja` | `/stm32-setup` 一条命令装齐(MSYS2 + 工具链,约 300 MB),或自行安装后由插件自动发现 |
|
|
71
|
+
| 烧录、调试 | `openocd`、`arm-none-eabi-gdb`(或 `gdb-multiarch`)、CMSIS-DAP / ST-Link 探针 | 同上;探针驱动由系统识别,无需额外配置 |
|
|
72
|
+
| 生成代码、建 HAL 工程 | STM32CubeMX(含内置 JRE)与其固件包 | 从 ST 官网安装 CubeMX(需 ST 账号),插件自动定位安装位置;固件包在 CubeMX 包管理器内安装 |
|
|
73
|
+
|
|
74
|
+
不确定缺什么时,先看诊断:
|
|
75
|
+
|
|
76
|
+
```text
|
|
77
|
+
/stm32-env # 编译 / 烧录 / 调试 / 生成四项能力逐项列出缺件、安装位置与安装方式
|
|
78
|
+
/stm32-setup # 先出计划,确认后执行安装,结束后自检
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`/stm32-env` 在没有装任何工具链时也能用:它只执行版本查询,不写盘、不联网。
|
|
82
|
+
|
|
83
|
+
### 开工前检查
|
|
84
|
+
|
|
85
|
+
```text
|
|
86
|
+
/stm32-doctor
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
只读体检:工具链是否齐备、是否有残留的 openocd / gdb 进程占用探针、gdb 端口是否被占用、工程内 `.elf` 与 `.ioc` 是否就位、`.ioc` 是否存在会导致烧录后失联的配置。
|
|
90
|
+
|
|
91
|
+
### 内置资源
|
|
92
|
+
|
|
93
|
+
芯片型号到启动文件、设备宏、Flash / RAM 容量的映射,以及 `.ioc` 模板、链接脚本与寄存器表,随插件一起分发,安装后离线可用,不需要下载资源包。`stm32_assets verify` 校验完整性;报缺文件时按提示重装插件即可。
|
|
94
|
+
|
|
95
|
+
### 从源码安装
|
|
96
|
+
|
|
97
|
+
仅开发或需要改代码时使用。`npm install` 与 `npm run build` 的说明见[开发与测试](#开发与测试)。
|
|
98
|
+
|
|
99
|
+
```powershell
|
|
100
|
+
git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
101
|
+
cd dsh-stm32
|
|
102
|
+
npm install --no-audit --no-fund # 仅安装 typescript
|
|
103
|
+
npm run build # tsc -> lib/,提交前必须执行
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
挂载到 profile 时用 `link:`,不要用 `file:`:
|
|
107
|
+
|
|
108
|
+
```powershell
|
|
109
|
+
cd "$env:USERPROFILE\.dsh\profiles\desktop"
|
|
110
|
+
pnpm add "link:D:\path\to\dsh-stm32"
|
|
111
|
+
|
|
112
|
+
# 在同一目录的 package.json 中把 "dsh-stm32" 追加到 dsh.profile.bundles
|
|
113
|
+
# 随后重启 dsh(插件层只在进程启动时加载)
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
原因:`nodeLinker: hoisted` 下 `file:` 会被复制成真实目录,重新编译出的 `lib/` 不会被宿主读取,表现为「改完代码、重启仍为旧行为」。`link:` 读取工作区里的 `lib/`,改完仍需重启 DSH 重新加载。
|
|
117
|
+
|
|
118
|
+
## 快速开始:最小验证(空目录到灯在闪)
|
|
119
|
+
|
|
120
|
+
这条链路已在真板验证,全程由模型调用工具完成。各步使用同一套工具,闪灯只是最小样例。
|
|
121
|
+
|
|
122
|
+
| 步 | 动作 | 工具 | 实测耗时 |
|
|
123
|
+
| --- | --- | --- | --- |
|
|
124
|
+
| 1 | 体检:工具链、被占用探针、端口、`.elf`、`.ioc` 告警 | `stm32_doctor` | 约 2 秒 |
|
|
125
|
+
| 2 | 空目录建 CMake 工程骨架(含已配置 SWD 的 `.ioc`) | `stm32_project_create` | 约 2 秒 |
|
|
126
|
+
| 3 | 按 `.ioc` 无头运行 CubeMX,产物落到 `Core/` | `stm32_generate` | 首次 130–175 秒;`.ioc` 与产物未变时跳过(小于 1 秒) |
|
|
127
|
+
| 4 | 编译(首次自动 `cmake --preset`) | `stm32_build` | 配置约 5 秒 + 编译 3 秒 |
|
|
128
|
+
| 5 | 只烧录:program + verify + reset | `stm32_flash` | 2.1–2.6 秒 |
|
|
129
|
+
| 6 | 回读 `GPIOC.ODR`(或地址 `0x4001100C`),确认状态翻转 | `stm32_regs_read` | 0.4–1.3 秒 |
|
|
130
|
+
|
|
131
|
+
第 6 步的符号写法依赖内置寄存器表;安装不完整时可改用地址 `0x4001100C`,报告中不会有寄存器名与位域解释。
|
|
132
|
+
|
|
133
|
+
模型侧只需一句:「在 `D:\work\blink` 建一个 STM32F103C8T6 的闪灯工程,编译并烧录」。
|
|
134
|
+
|
|
135
|
+
最小验证覆盖「建工程 → 生成 → 编译 → 烧录 → 回读」整条链路,没有闪灯专用步骤;真实项目走同一链路,差异在于 `.ioc` 里的外设数量、`USER CODE` 块数量与代码规模。
|
|
136
|
+
|
|
137
|
+
| 完整项目中的操作 | 路径 | 验证状态 |
|
|
138
|
+
| --- | --- | --- |
|
|
139
|
+
| 外设配置:GPIO / 定时器 / USART / I2C / SPI / ADC / DMA / 中断 | `stm32_ioc_plan`(GPIO 按芯片引脚表校验)→ `stm32_ioc_apply` → `stm32_generate` | GPIO、时钟、SWD 已上板实测;其余外设机制相同,未逐项实测 |
|
|
140
|
+
| 新增外设后补 HAL 源 | 在 `cmake/stm32cubemx/CMakeLists.txt` 的 `STM32_Drivers_Src` 中加入 `stm32f1xx_hal_<外设>.c`,或写入 `cmake/user/CMakeLists.txt` | 需手工补齐:插件只放置 `Src/` 与 `Inc/`,CubeMX 生成的 `cmake/**` 不搬运 |
|
|
141
|
+
| 多源文件与自定义模块 | 写入 `cmake/user/CMakeLists.txt`,模板已留位置 | 位置就位,未单独实测 |
|
|
142
|
+
| 业务代码 | `stm32_code_patch` 按块写入,重新生成时按标签搬回 | 已实测(追加 / 替换;标签写错时会列出全部可用标签) |
|
|
143
|
+
| 调参、改时钟 | `.ioc` 事务:先出差异 → 校验 → 备份 → 失败回滚 | 已实测 |
|
|
144
|
+
| 确认外设运行 | `stm32_regs_read` 读任意外设寄存器:符号名 `TIM2.CNT` / `USART1.SR` / `ADC1.DR`,或物理地址 `0x40000024`;只写外设名 `GPIOC` 时输出该外设全部寄存器 | 地址写法已上板实测;符号名与位域复测中 |
|
|
145
|
+
| 查看现场 | `stm32_debug_run` 停在 `main` 抓取一次;连续调试用 `stm32_debug_session` + `stm32_debug_eval` | 已实测(停在 `main () at main.c:67`) |
|
|
146
|
+
|
|
147
|
+
边界集中在[已知限制](#已知限制):HAL 建工程覆盖 21 个单核族,寄存器建工程覆盖 21 族(验证板为 C8T6),宿主仅在 Windows 验证,探针默认 CMSIS-DAP,新增外设需手工补 HAL 源。外设种类不受工具限制:`.ioc` 里能配置的能力都走同一链路;除闪灯外的外设尚未逐项上板实测,正式开工前建议先执行 `/stm32-doctor`。
|
|
148
|
+
|
|
149
|
+
## 工具参考
|
|
150
|
+
|
|
151
|
+
### 环境与工程
|
|
152
|
+
|
|
153
|
+
| 工具 | 用途 |
|
|
154
|
+
| --- | --- |
|
|
155
|
+
| `stm32_doctor` | 只读体检:工具链是否齐备、是否有残留 openocd / gdb、gdb 端口是否占用、`.elf` 与 `.ioc` 是否就位;按芯片输出能力与已知问题 |
|
|
156
|
+
| `stm32_route_plan` | 按具体工程与需求评估 HAL 路线与寄存器路线的开发代价,并区分可自动安装与需人工安装的缺件 |
|
|
157
|
+
| `stm32_env_install` | 安装 MSYS2 与工具链组件(gcc / gdb / openocd / cmake / ninja),默认只出计划,`dryRun:false` + `confirm:true` 才执行;只写用户级 PATH,不请求管理员权限 |
|
|
158
|
+
| `stm32_download` | 只下载不安装:J-Link 官方直链 + 校验和;CubeMX / CubeProgrammer 打开官方页或校验本地文件 |
|
|
159
|
+
| `stm32_firmware_install` | 下载并组装 STM32Cube 固件包,优先官方压缩包,失败回退 GitHub 拼包;默认只出计划 |
|
|
160
|
+
| `stm32_assets` | 查看、校验、清理包内资源(芯片数据、`.ioc` 模板、链接脚本、启动文件、寄存器表) |
|
|
161
|
+
| `stm32_cache` | 查看、校验、拉取、清理下载缓存(寄存器版 CMSIS 模板) |
|
|
162
|
+
| `stm32_project_create` | 建工程:`route:"hal"` 用模板 + 固件包,`route:"register"` 建不依赖 CubeMX 的寄存器工程;两条路线均生成 `openocd.cfg` |
|
|
163
|
+
| `stm32_project_export` | 工程打包为 zip,默认排除 `build/`、`.dsh-stm32/`、`node_modules/`、`.git/`,可附编译产物 |
|
|
164
|
+
| `stm32_layout_fix` | 检查并把配置文件归位:工作区索引在 `<工作区>/.dsh-stm32/workspace.conf`、工程描述在工程根;默认只报计划,`apply=true` 才改文件(先备份 `.bak`) |
|
|
165
|
+
|
|
166
|
+
### `.ioc`:查看与修改
|
|
167
|
+
|
|
168
|
+
| 工具 | 用途 |
|
|
169
|
+
| --- | --- |
|
|
170
|
+
| `stm32_ioc_inspect` | 只读解析:型号、引脚、信号、使能外设、中断、时钟树、工程设置与风险提示 |
|
|
171
|
+
### 外设预设(S187)
|
|
172
|
+
|
|
173
|
+
`stm32_ioc_plan` 的 `peripherals` 直接用名字,插件负责写全套键(引脚 `Mode`+`Signal`、`<IP>.IPParameters` 与各参数):
|
|
174
|
+
|
|
175
|
+
| 预设 | 引脚 | 备注 |
|
|
368
176
|
| --- | --- | --- |
|
|
369
|
-
| `
|
|
370
|
-
| `
|
|
371
|
-
| `
|
|
372
|
-
| `
|
|
373
|
-
| `
|
|
374
|
-
| `
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
| `
|
|
379
|
-
| `
|
|
380
|
-
| `
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
-
|
|
389
|
-
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
###
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
`
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
|
424
|
-
|
|
|
425
|
-
|
|
|
426
|
-
|
|
|
427
|
-
|
|
|
428
|
-
|
|
|
429
|
-
|
|
|
430
|
-
|
|
|
431
|
-
|
|
|
432
|
-
|
|
|
433
|
-
|
|
|
434
|
-
|
|
|
435
|
-
|
|
|
436
|
-
|
|
|
437
|
-
|
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
|
442
|
-
|
|
|
443
|
-
|
|
|
444
|
-
|
|
|
445
|
-
| `
|
|
446
|
-
|
|
|
447
|
-
|
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
|
473
|
-
|
|
|
474
|
-
|
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
templates
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
177
|
+
| `USART1` / `USART2` / `USART3` | PA9+PA10 / PA2+PA3 / PB10+PB11 | 默认 115200 8N1 |
|
|
178
|
+
| `SPI1` / `SPI2` | SCK+MISO+MOSI(PA5/PA6/PA7、PB13/PB14/PB15) | **全双工三根脚必须齐**;缺一根 CubeMX 会把整个外设静默丢掉,生成结果里没有 `MX_SPI1_Init` |
|
|
179
|
+
| `SPI1:tx` / `SPI1:rx` | SCK+MOSI / SCK+MISO | 单向:`SPI_DIRECTION_1LINE` + `TransmitOnly_Master` / `ReceiveOnly_Master` |
|
|
180
|
+
| `I2C1` / `I2C2` | SCL+SDA(PB6/PB7、PB10/PB11) | 100 kHz、7 位地址,外部上拉自备 |
|
|
181
|
+
| `TIM2:1` … `TIM4:1` | PA0 / PA6 / PB6 | PWM,默认 1 kHz、50% |
|
|
182
|
+
| `ADC1` / `ADC2` | PA1 | 单通道单 rank |
|
|
183
|
+
|
|
184
|
+
生成完如果某个外设「启用了却没出现初始化函数」,`stm32_generate` 会点名提醒——这类丢弃是 CubeMX 的静默行为,不是编译错误。
|
|
185
|
+
|
|
186
|
+
| `stm32_ioc_plan` | 计算逐键差异(不写盘):支持外设预设、引脚、中断、调试口、时钟规划与批量置键 |
|
|
187
|
+
| `stm32_ioc_apply` | 写入计划:源文件校验 → 备份 → 原子替换;支持按备份回滚 |
|
|
188
|
+
| `stm32_ioc_verify` | 由 CubeMX 自己重读 `.ioc`,指出被静默丢弃的外设与缺失的初始化 |
|
|
189
|
+
|
|
190
|
+
### 流程图规则
|
|
191
|
+
|
|
192
|
+
`diagram` 是功能框架,不是逐元件原理图:
|
|
193
|
+
|
|
194
|
+
- 按功能聚合:主控、NFC 天线与标签、光检测、供电、调试接口、按键;模块内部连接不画线。
|
|
195
|
+
- 连线只在模块之间,标签归纳为 I2C / SPI / UART / ADC / LED / PWM / SWD 这类总线名。
|
|
196
|
+
- 电源网络(VCC、GND)单独列出,不进连线;端点过多的网络同样不进框图。
|
|
197
|
+
- 布局由插件生成:主控居中、模块绕环,连线从面对对方的一侧进出,能直不拐。
|
|
198
|
+
|
|
199
|
+
这些规则同时写在插件的技能文本里,读图与画图用的是同一套口径。
|
|
200
|
+
|
|
201
|
+
### 原理图(KiCad 10)
|
|
202
|
+
|
|
203
|
+
| 工具 | 用途 |
|
|
204
|
+
| --- | --- |
|
|
205
|
+
| `stm32_sch_read` | 只读解析 KiCad 工程:图纸树、元件、网络、电源网络,以及模块框图(哪两块电路相连、走什么总线) |
|
|
206
|
+
| `stm32_sch_pins` | 主控引脚矩阵:每个脚的网络名、类型、是否悬空,并按 CubeMX 数据库给出可复用信号候选 |
|
|
207
|
+
| `stm32_sch_check` | 检查原理图本身,并与 `.ioc`、`.kicad_pcb` 对账:缺值、缺封装、SWD / BOOT0 / 电源缺失、网络被拆开 |
|
|
208
|
+
| `stm32_sch_to_ioc` | 把引脚连接转成 `.ioc` 配置草案:每个脚给出建议信号、置信度与候选,纯 GPIO 网络给输入/输出建议;硬件复用对不上时给软件模拟退路与代价;只读,不写 `.ioc` |
|
|
209
|
+
|
|
210
|
+
版本范围是 KiCad 10(`version 20260306`)。元件库内嵌在图纸里,不要求安装 KiCad,也不读 `sym-lib-table`;只跟随根图纸引用到的子图,`.history/` 与其他历史版本不参与解析。对账判据是连通性:同一 PCB 网络上的焊盘,在原理图里必须属于同一网络;名字不一致只作提示。工具只读,不改原理图,也不改工程配置;`stm32_sch_to_ioc` 的草案要交给 `stm32_ioc_plan` 才落盘,且对不上库信号的脚会列在待确认里。
|
|
211
|
+
|
|
212
|
+
### 电路设计(tscircuit + KiCad)
|
|
213
|
+
|
|
214
|
+
在 `hardware/` 下用 tscircuit 写电路,导出真 KiCad 工程,再用 KiCad 自己的检查器验收。检查按嘉立创常规工艺进行:线宽与间距 ≥ 0.2 mm、孔径 ≥ 0.3 mm、丝印字高 ≥ 0.8 mm,规则写进工程的 `.kicad_dru`,报出来的是「能不能按这一档打板」,并附打样成本估算。
|
|
215
|
+
|
|
216
|
+
| 工具 | 用途 |
|
|
217
|
+
| --- | --- |
|
|
218
|
+
| `stm32_ecad_init` | 建 `hardware/{circuit,kicad,libs,out}` 与最小 `package.json`;依赖走共享运行时(见下),不再每工程各装一份 |
|
|
219
|
+
| `stm32_sch_review` | 原理图一键评审:读图、规则检查、配置草案与「需要人决策的脚」,只给结论不写盘 |
|
|
220
|
+
| `stm32_ecad_design` | 一键设计:构建 → 合并焊盘(可选)→ 导库 → ERC/DRC → 可制造性与成本 → STEP 与制造文件,逐步报告;传 `pcb=true` 会在导库后自动布线(需预装 KiCadRoutingTools,缺引擎则跳过该步) |
|
|
221
|
+
| `stm32_ecad_build` | 用 KiCad 自带的 bun 跑 `tsci build`:`.circuit.tsx` → `circuit.json`、SVG 与 `kicad/*.kicad_sch|.kicad_pcb`;并把 `tscircuit:` 生成名换回真库名(`footprint="kicad:…"` 时),官方封装复制进 `hardware/libs`;立创封装(`footprint="jlcpcb:C…"`)按位号固化进库并记在 `libs/sources.json`;构建前预检封装里同坐标的焊盘(USB-C 16P 的 A1/B12 这类),命中就跳过自动布线并忽略摆放间距告警,板子照常产出;需要把同坐标焊盘并成一个时,构建时传 `mergePads=true` |
|
|
222
|
+
| `stm32_ecad_check` | 先补齐工程库表与嘉立创工艺规则(`<工程>.kicad_dru`),再跑 `kicad-cli sch erc` 与 `pcb drc`,把违规收敛成规则、级别与涉及项清单;顺带报出未命名网络、板子尺寸、最细走线、最小孔径与打样成本 |
|
|
223
|
+
| `stm32_ecad_libs` | 把生成工程里内嵌的封装/符号抽成 `hardware/libs` 下的真库,并补齐 `fp-lib-table` / `sym-lib-table` |
|
|
224
|
+
| `stm32_ecad_step` | 导出 STEP 到 `hardware/out`;先按「官方 3D 目录 → `hardware/libs/3d` → 缓存」解析模型并改写路径,缺模型只报告,不阻断导出 |
|
|
225
|
+
| `stm32_ecad_export` | 一次导出 Gerber、钻孔、贴片坐标与 STEP 到 `hardware/out`,按最小可下单集合汇总 |
|
|
226
|
+
| `stm32_ds_fetch` | 把非 STM32 器件的数据手册抓到本地缓存:按立创编号、按本工程用到的器件,或手工导入 PDF |
|
|
227
|
+
| `stm32_ds_lookup` | 按用途查手册:引脚、绝对最大额定值、电气特性、时序、封装——给页号、标题与该页开头正文 |
|
|
228
|
+
| `stm32_ds_list` | 列出本地手册缓存:编号、型号、占用、抓取时间与来源 |
|
|
229
|
+
| `stm32_pdf_read` | 读 PDF:`info` 看页数与文字层、`text` 取指定页文字(保版面,表格可读)、`figures` 列图与表、`table` 把参数表切成行列、`render` 把页面或局部渲染成 PNG 交给视觉读图、`curve` 把曲线图数字化成可复核的 (x, y) 序列、`schematic` 列原理图的元件与网络标签(只给清单,不出网表) |
|
|
230
|
+
| `stm32_pcb_place` | 按 circuit.json 的元件与网络计算落位,再改 `.kicad_pcb` 把元件搬到位(默认清掉旧走线,写盘前留 `.bak`)|
|
|
231
|
+
| `stm32_pcb_autoroute` | 用 KiCadRoutingTools(Rust 网格布线器)铺平面、扇出并布线,回报未连接数;默认只出计划 |
|
|
232
|
+
| `stm32_pcb_render` | 把 `.kicad_pcb` 画成 SVG 板图:板框、顶层与底层走线、焊盘、过孔、丝印;默认只回尺寸与计数,给 `saveAs` 才落盘 |
|
|
233
|
+
| `stm32_emc` | EMC 体检:电源线按 IPC-2221 算所需线宽、查铺铜与参考平面、查换层过孔旁的地过孔;`deep` 再查差分对间距、回流路径覆盖与并行串扰 |
|
|
234
|
+
| `stm32_stackup` | 算叠层与阻抗:板子没有叠层定义时按层数取嘉立创常规叠层,给 50 Ω 单端与 90/100 Ω 差分的线宽,并列出板上现有线宽 |
|
|
235
|
+
| `stm32_bom` | 读 `circuit.json` 出 BOM:位号、数量、值、封装、立创编号与替代料;`prices` 为真才联网取价,`format=csv` 出嘉立创贴片列 |
|
|
236
|
+
| `stm32_power` | 算电源树电流预算:每个电源网络的电压、电流、挂着的元件、最窄走线 vs IPC-2221 需求宽度;只合计你填的电流,估算另计,未填标待定 |
|
|
237
|
+
| `stm32_pcb_links` | 布线体检:差分对长度差与过孔数、逐层铺铜与层上信号线数、去耦电容到 IC 电源脚的距离;只算几何与网络名,不做仿真 |
|
|
238
|
+
| `stm32_pcb_3d` | 3D 预览:用 KiCad 的 `kicad-cli pcb render` 把板子渲成 PNG(顶/底/左右/前后、可透视与旋转),并把封装引用的 3D 模型里缺文件的位号点名出来(那些器件在 3D 里是空的);缺模型时按族/引脚数/间距给出可换的官方封装(标出有没有 STEP);`format: glb\|step` 直接导几何给网页与机械;面板「3D 预览」有顶/底/斜视三档与「导出 GLB/STEP」 |
|
|
239
|
+
| `stm32_pcb_swap` | 换封装:把位号换成 KiCad 官方库里的封装,保留位号/值/位置/旋转并按焊盘编号搬网络;默认只预演,`apply` 才写盘(留 `.bak`);焊盘尺寸变了会提示重布 |
|
|
240
|
+
| `stm32_pcb_gerber` | 制造文件回看:把 `stm32_ecad_export` 导出的 Gerber 与钻孔读回来画成一张 SVG(可选层),交付前核对板框、铜、丝印与孔位;读不懂的构造计入 notes |
|
|
241
|
+
| `stm32_impedance` | 阻抗写回:按叠层算出 50 Ω 单端与 90 Ω 差分该用的线宽与间距,写成 `.kicad_dru` 里的自定义规则(只作用于点名的网络);KiCad 的 DRC 没有阻抗约束,写入的是可执行的几何量 |
|
|
242
|
+
| `stm32_netgate` | 网表与 PCB 的持续门禁:图纸比板子新、网络拆开、焊盘缺失 |
|
|
243
|
+
| `stm32_sch_import` | 从 KiCad 板子吸收改动回 `circuit.tsx`:只比网表与元件,坐标不保留(构建重排) |
|
|
244
|
+
| `stm32_sch_edit` | 原理图人工编辑:指令存 `schematic-edits.json`,构建收尾重放;KiCad 10 的 IPC 不提供原理图读写 |
|
|
245
|
+
| `stm32_board_info` | MCU 事实文件:把 `.ioc` 里的事实(型号/封装/时钟/调试口/引脚/外设/中断数)写进 `<工程>/dsh/mcu.json`(`schema: dsh-mcu/1`,带 `.ioc` 的 sha256 指纹与工程相对路径),别的插件只读它;默认只回事实,`write: true` 才落盘,`.ioc` 改过会报 `stale` 与原因 |
|
|
246
|
+
| `stm32_sch_sync` | 手绘层新放的器件补到板子:读 `hardware/schematic/*.kicad_sch` 的位号/值/封装/网络,`planHandSync` 出计划,`apply: true` 时交 KiCad 自带 python 用 `FootprintLoad` 把封装 `Add` 进最近一次构建的 `.kicad_pcb`(写前留 `.bak`);板上已有的位号跳过,`tscircuit:` 封装与没有 `Footprint` 的件不补,自动网名不赋;坐标暂定在板框下方,notes 会提醒布线前挪 |
|
|
247
|
+
| `stm32_sch_draw` | 图纸手绘层:`wire` 连两脚、`label` 标名、`clone` 复制元件、`place` 从符号库放新器件(内嵌 `lib_symbols`)、`move`/`remove`;写 `hardware/schematic/*.kicad_sch`(构建不碰),不需要打开 KiCad,写完用 `kicad-cli` 导网表校验 |
|
|
248
|
+
| `stm32_part_import` | 器件导入:按 `Lib:Name` 从 KiCad 官方库复制封装;库里没有且给了立创编号时,从立创页面取封装图形转成 `.kicad_mod`(`source=kicad` 可强制只查库)。按焊盘号生成符号骨架,立创编号写成封装属性(`LCSC`/`MPN`/`Brand`/`Datasheet`),封装引用的 3D 模型一并收进 `hardware/libs/3d` 并改写为 `${KIPRJMOD}` 相对路径,再登记 `fp-lib-table`/`sym-lib-table` |
|
|
249
|
+
| `stm32_symbol_footprint` | 符号与封装生成:按引脚表出 `.kicad_sym`,按封装尺寸出 `.kicad_mod`(QFP / SOIC / 两脚小件);尺寸与引脚号必须由调用方给出,缺一个就报错 |
|
|
250
|
+
| `stm32_part_search` | 器件搜索:按型号、参数或立创编号查编号、库存、阶梯价与手册地址;结果缓存 24 小时,封装字段接口不给时留空 |
|
|
251
|
+
| `stm32_mech` | 外壳与机械约束:板框尺寸、定位孔坐标与孔径、孔到边最小距离、面积;`export` 写 DXF(R12,外形 + 定位孔)给机械软件 |
|
|
252
|
+
| `stm32_brief` | 生成需求与设计说明的三段骨架:`docs/01-MRD.md`(为什么做)、`02-hardware-PRD.md`(电气指标)、`03-design-brief.md`(按什么做);主控、时钟、外设、板尺寸、元件成本自动填,需求与验收标准留「待定」不替人编,已有文件默认不覆盖 |
|
|
253
|
+
| `stm32_pcb_ipc` | 在**已打开的 KiCad PCB 编辑器**里做局部编辑:看板况、按位号移元件、布一段线、加过孔、重铺铜、保存;走 KiCad 官方 IPC,改动能被 Ctrl+Z 撤销。默认只回计划,`apply: true` + `expectBoard` 才动板子;连不上时自动用 pcbnew 打开本工程的板子并等就绪(`open: false` 可关) |
|
|
254
|
+
| `stm32_pcb_route` | 网格 A* 布线(0.5 mm 栅格):按网络逐张布、避开已有焊盘与走线;默认预览,`apply: true` 才写盘(写完必须跑 DRC) |
|
|
255
|
+
| `stm32_ecad_package` | 把 `hardware/` 打成可交付 zip(跳过 `node_modules`、`dist`、`.history`),写完读回自检 |
|
|
256
|
+
|
|
257
|
+
写者只有一个:`.kicad_sch` / `.kicad_pcb` 由 tscircuit 生成,插件只读。tscircuit 把符号与封装内嵌在工程里、名字归到 `tscircuit` 之类的生成名,检查前会先导出成 `hardware/libs` 下的真库并补齐库表,否则报告里只剩「库不在配置中」这类环境噪音;未命名网络(`.R1 > .pin1 to .C1 > .pin1`)会单独列出并给出 `<net name="VDD" />` 的修法。构建要求 KiCad 10 与其自带的 `bun.exe`。
|
|
258
|
+
|
|
259
|
+
依赖只装一次:`tscircuit` 与 `typescript` 装在共享运行时 `~/.dsh-stm32/ecad-runtime`(可用 `DSH_STM32_ECAD_RUNTIME` 改位置),各工程的 `hardware/circuit/node_modules` 用目录联接指向它——ESM 解析要求 `node_modules` 出现在工程树里,联接满足这一点,磁盘只占一份(约 730 MB)。首次是否自动安装由 `DSH_STM32_ECAD_AUTO_INSTALL` 决定:`auto` 直接装、`off` 从不装、缺省 `ask` 只提示命令。
|
|
260
|
+
|
|
261
|
+
改完电路源码、本轮对话结束时,插件会**自动构建一次**(只构建与检查,不导出成品),这样回到 KiCad 就能看到最新的原理图与 PCB。三条约束:只在源码比产物新或上次失败时跑、每回合最多一次、两次之间至少 60 秒;最近一次结果写在面板头(「自动构建 MM-DD HH:mm · 通过/有问题」)与 `<工程>/.dsh-stm32/ecad-state.json`。板子上的元件优先用 KiCad 官方库(`footprint="kicad:..."`),需要时再用立创编号兜底。
|
|
262
|
+
|
|
263
|
+
PCB 布线用外部引擎 `KiCadRoutingTools`(MIT,Rust 网格布线器)。它不在插件包里,装一次、所有工程共用:
|
|
264
|
+
|
|
265
|
+
```bash
|
|
266
|
+
git clone --depth 1 https://github.com/drandyhaas/KiCadRoutingTools ~/.dsh-stm32/kicad-routing-tools
|
|
267
|
+
# Rust 模块:python build_router.py 会下载预编译二进制;GitHub API 限流时直接下 release 的 grid_router-windows-x86_64.pyd
|
|
268
|
+
# 把它放进 KiCad python 的 Lib/site-packages(子进程要能 import 到)
|
|
269
|
+
"D:/app/KiCad/10.0/bin/python.exe" -m pip install numpy scipy shapely
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
位置可用 `DSH_STM32_KRT_ROOT` 改。装好后 `stm32_pcb_autoroute` 才能跑;没装时该工具直接报一句「还没安装」,其余功能不受影响。
|
|
273
|
+
|
|
274
|
+
设计规则跟着**铜层数**取嘉立创常规档:1–2 层 0.127 mm、多层 0.10 mm,与布线器的工艺档同表。布线与 DRC 用同一档,`clearance` 才不会整板误报;写成 `.kicad_dru` 的判定阈值再减 0.003 mm 的量化余量(布线器在栅格上落线,实测最少 0.0974 mm)。实测(41 元件 / 35 网络 / 4 层板,一键设计带布线)未连接 0,DRC 从 259 错降到 **0 错 / 132 警**,构建 52 秒、布线 32 秒。
|
|
275
|
+
|
|
276
|
+
### 代码与构建
|
|
277
|
+
|
|
278
|
+
| 工具 | 用途 |
|
|
279
|
+
| --- | --- |
|
|
280
|
+
| `stm32_code_patch` | 只写 `USER CODE BEGIN/END` 块内内容,块外逐字节保留;写前备份 |
|
|
281
|
+
| `stm32_generate` | 无头运行 CubeMX,产物落到 `Core/`,`USER CODE` 按标签搬回;`.ioc` 未变时跳过 |
|
|
282
|
+
| `stm32_build` | 编译:自动推断构建目录与 `.elf`,返回错误行、警告数、FLASH / RAM 占用;可转出 hex / bin;构建缓存(CMakeCache)与当前工程对不上时点名原因,`reconfigure: true` 清缓存重配 |
|
|
283
|
+
|
|
284
|
+
### 烧录、调试与运行时
|
|
285
|
+
|
|
286
|
+
| 工具 | 用途 |
|
|
287
|
+
| --- | --- |
|
|
288
|
+
| `stm32_flash` | 只烧录:program + verify + reset,烧完释放探针;烧前检查 Serial Wire;失败时给出探针错误的分类与处理建议 |
|
|
289
|
+
| `stm32_debug_run` | 烧录后停在 `main`,抓取寄存器、调用栈与局部变量,随后复位运行并释放探针 |
|
|
290
|
+
| `stm32_debug_session` | 开启长调试会话(空闲与总时长受限),供 `stm32_debug_eval` 连续使用 |
|
|
291
|
+
| `stm32_debug_eval` | 在调试会话中执行 gdb 命令:读变量、寄存器、调用栈、内存 |
|
|
292
|
+
| `stm32_debug_stop` | 关闭调试会话并释放探针 |
|
|
293
|
+
| `stm32_regs_read` | 按地址或符号名读寄存器,有寄存器表时解析位域;读取时短暂暂停,读完继续运行,不复位芯片 |
|
|
294
|
+
| `stm32_watch` | 登记表达式并采样(含差值);`kind=write/read/access` 装为硬件观察点,受芯片观察点数量限制 |
|
|
295
|
+
| `stm32_rtt` | RTT 通道:固件侧把控制块放在 RAM,主机侧经 openocd 读取,输出带级别与时间戳 |
|
|
296
|
+
| `stm32_serial` | 串口交互(Windows):`list` / `open` / `read` / `send` / `transact` / `status` / `close` |
|
|
297
|
+
|
|
298
|
+
### 固件中的 RTT 接入(最短示例)
|
|
299
|
+
|
|
300
|
+
```c
|
|
301
|
+
/* USER CODE BEGIN 0 */
|
|
302
|
+
static char rtt_buf[3][1024];
|
|
303
|
+
static void rtt_init(void) {
|
|
304
|
+
/* 控制块按 SEGGER 约定放在 RAM:acId / acName / 三个环,见 templates/ 中的 rtt.h */
|
|
305
|
+
}
|
|
306
|
+
/* USER CODE END 0 */
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
完整实现见 `templates/` 内的 RTT 模板;通道数与环大小由 `RTT_UP_CHANNELS` / `RTT_BUF_SIZE` 控制(默认 3×1 KB = 3 KB `.bss`,C8T6 只有 20 KB RAM)。
|
|
310
|
+
|
|
311
|
+
### PDF 读取(数据手册与原理图)
|
|
312
|
+
|
|
313
|
+
依赖 poppler(`pdftotext` / `pdfinfo` / `pdftoppm`):`pacman -S --needed mingw-w64-ucrt-x86_64-poppler` 装进 MSYS2,`stm32_doctor` 会显示版本。
|
|
314
|
+
|
|
315
|
+
| 用途 | 调法 | 得到什么 |
|
|
316
|
+
| --- | --- | --- |
|
|
317
|
+
| 判断这份 PDF 能不能读文字 | `mode=info` | 页数、纸张、有无文字层;描边字体的 PDF 会明确提示只能看图 |
|
|
318
|
+
| 查参数、读表格 | `mode=text` + `first`/`last` | 保版面的文字,表格按列对齐 |
|
|
319
|
+
| 找「第几页有什么图」 | `mode=figures` | 图注清单与页号 |
|
|
320
|
+
| 读某个参数表的行与列 | `mode=table` | 列名、行数据、置信度;切不全是 medium,配同页原文核对 |
|
|
321
|
+
| 看曲线、框图 | `mode=render` + `page`/`dpi`/`crop` | PNG 路径,交给视觉读图;抠数字用 300–400 dpi 并收紧裁切 |
|
|
322
|
+
|
|
323
|
+
读图得到的是形态与量级(约 ±0.5 个最小刻度),不是精确数值;精确参数优先查同页表格。
|
|
324
|
+
|
|
325
|
+
### 数据手册缓存
|
|
326
|
+
|
|
327
|
+
非 STM32 器件(LDO、运放、传感器、接口芯片)第一次用到时,把厂商手册抓下来存本地:
|
|
328
|
+
|
|
329
|
+
- `stm32_ds_fetch code=C25137` 按立创编号抓;`all=true` 抓本工程 `circuit` 源码里出现的全部 `jlcpcb:` 器件;`file=` 手工导入 PDF(反爬或没有编号时的退路)。
|
|
330
|
+
- 缓存位置 `~/.dsh-stm32/datasheets/<编号>/`(`meta.json` + 以内容 sha256 命名的 PDF),可用 `DSH_STM32_DATASHEETS` 改目录。命中缓存时**不联网**;抓取失败记 24 小时负缓存,`refresh=true` 可强制重试。
|
|
331
|
+
- `stm32_ecad_build` 成功后会自动补齐本工程用到的手册;面板「电路设计」头部显示「手册 2/3」,缺的标黄,点「补手册」走同一套逻辑。
|
|
332
|
+
- 16P USB-C 这类封装把同一块铜拆成两个脚(A1/B12),自动布线器选不出唯一焊盘会整板放弃;预检命中时构建会跳过布线并忽略摆放间距告警,布线在 KiCad 里手工完成。
|
|
333
|
+
- `stm32_ds_lookup code=C25137 kind=electrical` 直接翻到电气特性那一页:先读前 40 页建一次索引(只记页号),之后按页取正文。
|
|
334
|
+
- `stm32_ds_list` 看已缓存哪几份、占多少空间。
|
|
335
|
+
- 手册的引脚表可兜底 `stm32_sch_to_ioc`:`stm32_sch_to_ioc datasheet=C25137`,器件库没有这个脚的信号时,用手册「Pin name / Alternate functions」两列补候选,结果标 `(手册)`。
|
|
336
|
+
- 缓存清理:`stm32_ds_list remove=C25137` 或 `olderThanDays=180`,返回删了哪些、释放多少字节;面板「手册 x/y(N.N MB)」只读,删除走工具。
|
|
337
|
+
- 曲线图不用靠眼睛估:`stm32_pdf_read file=DS14721.pdf mode=curve page=44` 按色相分出每条曲线,用纵/横刻度做线性标定,返回 (x, y) 序列;图例文字认不出,序列按色相命名。
|
|
338
|
+
- 抓到之后直接 `stm32_pdf_read file=C25137`(或写型号)就能读,不必再给路径——引脚、电气参数、时序都从这里取,不靠记忆编。
|
|
339
|
+
|
|
340
|
+
## 斜杠命令
|
|
341
|
+
|
|
342
|
+
| 命令 | 说明 |
|
|
343
|
+
| --- | --- |
|
|
344
|
+
| `/stm32-doctor` | 体检:工具链、残留进程、端口、`.elf` 与 `.ioc` 告警 |
|
|
345
|
+
| `/stm32-env` | 工具链体检:编译 / 烧录 / 调试 / 生成四项能力缺什么、装在哪、如何安装 |
|
|
346
|
+
| `/stm32-setup` | 体检 → 安装计划 → 确认后安装 → 自检 |
|
|
347
|
+
| `/stm32-build [目录] [--clean]` | 编译(CMake + Ninja,默认 `build/Debug`),`--clean` 先全清 |
|
|
348
|
+
| `/stm32-flash [目录]` | 只烧录:program + verify + reset,结束后释放探针 |
|
|
349
|
+
| `/stm32-debug [目录]` | 烧录并进入调试,停在 `main`,之后可用 `stm32_debug_eval` |
|
|
350
|
+
| `/stm32-stop` | 关闭调试会话、释放探针,之后可在 VS Code 中按 F5 |
|
|
351
|
+
|
|
352
|
+
## 调试台(面板)
|
|
353
|
+
|
|
354
|
+
会话页签内的「调试台」用于人机同看同一条时间线:`stm32_*` 调用的开始、成功、失败与耗时,以及串口、RTT、监视、引脚、时钟、中断与 `.ioc` 变更。
|
|
355
|
+
|
|
356
|
+
| 页签 | 内容 | 操作 |
|
|
357
|
+
| --- | --- | --- |
|
|
358
|
+
| 概览 | 工程、型号、SYSCLK、容量、调试会话、工具链、构建与烧录、证据占用、告警摘要 | 跳转失败筛选与实时通道,导出操作记录 Markdown |
|
|
359
|
+
| 事件 | 调用起止、耗时、慢调用标记、参数摘要 | 只看失败、按工具筛选、按耗时排序、批量引用、导出 JSONL、事件深链 |
|
|
360
|
+
| 实时通道 | 串口 / RTT / 监视输出 | 暂停、清空、关键字过滤、RTT 级别过滤、发送串口行、常驻采集、导出 |
|
|
361
|
+
| 引脚 | 按外设分组、按端口排布、按封装画法(芯片型号 + 封装名 + 四边引脚小长条,1 脚圆点) | 筛选、复制引用、查看 `.ioc` 键、导出 CSV |
|
|
362
|
+
| 流程图 | 按功能模块聚合的网状框图(主控居中,NFC 天线与标签、光检测、供电、调试口、按键环绕摆放;原理图没写型号时按封装脚数与位号推断主控,并在页脚说明),连线从框的四个方向进出,按总线与信号用途标注,附检查结论 | 只读;元件不单独成框,电源网络单独列出;页签上的「一键评审」会跑读图 + 规则检查 + `.ioc` 草案并列出需要人决策的脚 |
|
|
363
|
+
| 电路设计 | tscircuit 工作区状态:初始化、依赖、入口、最近构建、库、导出产物 | 可在页签里直接触发构建、检查、导出库、导出 STEP、打包 Gerber、打包交付、补数据手册;构建与打包要几十秒 |
|
|
364
|
+
| 时钟 | 树与流向两种视图、各节点频率与分频 | 超限标记与「改为 ÷N」建议(按父时钟计算) |
|
|
365
|
+
| 中断 | NVIC 使能、抢占与子优先级 | 筛选、排序、就地修改、批量修改 |
|
|
366
|
+
| 故障 | 失败事件原文、规则解码、按规则合并 | 分类筛选、复制组提示、导出 CSV |
|
|
367
|
+
| 产物 | elf / hex / bin、大小、校验和、容量、两次构建对比 | 复制校验和 |
|
|
368
|
+
| 变更 | `.ioc` 与基线的差异 | 记基线、恢复单键、一次恢复全部 |
|
|
369
|
+
|
|
370
|
+
工程目录按约定解析,位置可显式指定:程序目录取 `program/`、`firmware/`、`app/`、`user/`、`fw/`、`code/` 或工程根;这些候选都不命中时按深度 2 内扫描 `*.ioc`,命中的父目录就是程序目录(目录名由使用者决定);KiCad 工程取 `hardware/`、`kicad/`、`hw/`、`pcb/`(都没有时扫描 `*.kicad_pro`);配置与基线在工程根的 `.dsh-stm32/`。两处位置可写进工程根的 `dsh-stm32.conf`(`firmware=` / `hardware=`),写了 `ioc=` 时以该文件所在的目录为准。工作区索引固定写在 `<工作区>/.dsh-stm32/workspace.conf`,工程描述固定写在工程根,放错时用 `stm32_layout_fix` 一键归位(先备份)。
|
|
371
|
+
|
|
372
|
+
打开面板会先补齐本会话最近的记录,之后实时追加。事件每 30 秒写入 `~/.dsh-stm32/evidence/<日期>/<会话>/`,可回放、导出;默认保留 7 天、最近 20 个会话,可在配置里调整。面板只展示本插件自己的工具调用,不含其他工具的调用。面板只显示本会话的工程与调试会话:换到另一个工作区的会话时,没有工程就是空面板,不会借用别的会话的工程与调试输出。
|
|
373
|
+
|
|
374
|
+
## 串口(Windows)
|
|
375
|
+
|
|
376
|
+
`stm32_serial` 提供七个动作:`list` / `open` / `read` / `send` / `transact` / `status` / `close`。打开端口后由插件持有,一次一个端口,默认 115200 8N1、无流控、DTR / RTS 不拉高,回合结束时自动关闭。
|
|
377
|
+
|
|
378
|
+
- 平台:仅 Windows;Linux 与 macOS 返回 `unsupported-platform`。
|
|
379
|
+
- 端口:`list` 枚举可用端口;端口参数按设备记忆,换 COM 号后可复用。
|
|
380
|
+
- 读:`read` 支持游标,只返回游标之后的新行。
|
|
381
|
+
- 写入:`send` 发送一行,`transact` 发送并等待匹配回包(正则)。
|
|
382
|
+
- 保留:`persist=true` 跨回合保留端口。
|
|
383
|
+
|
|
384
|
+
参考验证板为 CH340(`1A86:7523`,COM5,115200)。同一板上的 DAPLink 虚拟串口(`c251:f001`,COM4)不承载应用串口数据。
|
|
385
|
+
|
|
386
|
+
## 设计要点
|
|
387
|
+
|
|
388
|
+
- **只写自有文件**:`.ioc` 走事务(计划 → 校验 → 备份 → 替换),生成区只写 `USER CODE` 块,其余生成文件不由插件修改。
|
|
389
|
+
- **烧录与调试分离**:`stm32_flash` 不建立调试会话,烧完即释放探针;需要调试时才开 `stm32_debug_session`,空闲自动关闭,避免与 VS Code 抢占探针。
|
|
390
|
+
- **结论附证据**:失败时给出编译器 `文件:行:列`、探针错误分类、寄存器读数,而不是模糊描述。
|
|
391
|
+
- **缺什么就说什么**:芯片、时钟或调试脚本不受支持时,报错直接说明缺哪一项,不猜测、不静默跳过。
|
|
392
|
+
- **不接管宿主**:面板只展示状态与执行明确的工程动作,不做代码编辑与 Git 操作。
|
|
393
|
+
|
|
394
|
+
## 配置
|
|
395
|
+
|
|
396
|
+
### 配置文件(`~/.dsh-stm32/config.json`)
|
|
397
|
+
|
|
398
|
+
工具链位置由插件维护:`stm32_env_install` 安装后写入该文件,后续工具直接读取,无需重启 DSH 或设置环境变量。也可手工编辑:
|
|
399
|
+
|
|
400
|
+
```json
|
|
401
|
+
{
|
|
402
|
+
"version": 1,
|
|
403
|
+
"msys64": "E:/msys64",
|
|
404
|
+
"binDirs": [],
|
|
405
|
+
"packages": ["mingw-w64-ucrt-x86_64-arm-none-eabi-gcc", "mingw-w64-ucrt-x86_64-cmake"],
|
|
406
|
+
"cubeMxRoot": "",
|
|
407
|
+
"updatedAt": "2026-02-01T00:00:00.000Z"
|
|
408
|
+
}
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
`binDirs` 为空时由 `msys64` 推导 `<msys64>/ucrt64/bin`。文件损坏(JSON 非法)视为不存在,不影响其他功能。
|
|
412
|
+
|
|
413
|
+
优先级:工具参数(`binDirs` / `cubeMxRoots`)> 环境变量 > 配置文件 > 内置默认值。内置默认值只含 Windows 常见位置,不含任何机器专属路径。
|
|
414
|
+
|
|
415
|
+
### 设置面板
|
|
416
|
+
|
|
417
|
+
DSH 设置内的「STM32 工具链」页提供三张卡片:
|
|
418
|
+
|
|
419
|
+
- **装在哪**:读取并保存 `msys64` / `cubeMxRoot` / 额外 `binDirs`,保存后下一条工具调用即生效。
|
|
420
|
+
- **缺什么**:执行一次探测(只读版本查询),逐项显示路径、版本、缺失原因,以及编译 / 烧录 / 调试 / 生成四项能力徽章。
|
|
421
|
+
- **装工具链**:先出计划(步骤、下载体积、PATH 与配置变更),确认后执行;过程显示步骤与日志尾部。
|
|
422
|
+
|
|
423
|
+
### 下载缓存与固件包
|
|
424
|
+
|
|
425
|
+
- 寄存器版 CMSIS 模板首次使用时下载到缓存(默认 `%LOCALAPPDATA%\dsh-stm32\cache`),之后复用;逐文件校验,变更即拒收。`stm32_cache` 可查看、校验、拉取与清理。
|
|
426
|
+
- HAL 路线使用本机 CubeMX 固件包:F1 默认 `STM32Cube_FW_F1_V1.8.7`,其他族取已安装的最高版本;可用 `firmwarePackage` 指定。缺失时先在 CubeMX 包管理器中安装,或用 `stm32_firmware_install` 下载组装。
|
|
427
|
+
- 可自动组装的族:F1 / F2 / F3 / F4 / F7 / G0 / L1 / L4 / L5 / H5 / H7 / U0 / U3 / U5 / WB / WL / WBA / C0。F4 默认 `STM32Cube_FW_F4_V1.28.0`;不在清单里的族只给手动安装步骤。
|
|
428
|
+
- `stm32_download` 只下载或校验安装包(默认目录 `%LOCALAPPDATA%\dsh-stm32\downloads`),不执行安装器,不请求管理员权限。
|
|
429
|
+
|
|
430
|
+
### 环境变量(可选)
|
|
431
|
+
|
|
432
|
+
| 变量 | 作用 | 默认 |
|
|
433
|
+
| --- | --- | --- |
|
|
434
|
+
| `STM32_BIN_DIRS` | 工具链目录候选,`;` 分隔,整份替换内置列表(自动发现仍追加在尾部) | `C:/msys64/ucrt64/bin`、`C:/msys64/mingw64/bin` |
|
|
435
|
+
| `STM32_CUBEMX_ROOT` | CubeMX 安装根,整份替换内置列表 | `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` |
|
|
436
|
+
| `STM32_NO_DISCOVER` | 设为 `1` 关闭自动发现(仅用内置列表) | 不设 |
|
|
437
|
+
| `DSH_STM32_CONFIG` | 替换配置文件路径 | `%USERPROFILE%\.dsh-stm32\config.json` |
|
|
438
|
+
| `DSH_STM32_NO_CONFIG` | 设为 `1` 完全不读配置文件 | 不设 |
|
|
439
|
+
| `DSH_STM32_CACHE` | 下载缓存根目录,支持 `~` | `%LOCALAPPDATA%\dsh-stm32\cache` |
|
|
440
|
+
| `DSH_STM32_DOWNLOADS` | 安装包下载目录,支持 `~` | `%LOCALAPPDATA%\dsh-stm32\downloads` |
|
|
441
|
+
| `DSH_STM32_HOME` | 插件数据根目录(配置、证据、快照、备忘) | `%USERPROFILE%\.dsh-stm32` |
|
|
442
|
+
| `DSH_STM32_EVIDENCE` | 证据目录 | `~/.dsh-stm32/evidence` |
|
|
443
|
+
| `DSH_STM32_EVIDENCE_FLUSH_SECONDS` | 证据落盘间隔(5–3600 秒) | 30 |
|
|
444
|
+
| `DSH_STM32_EVIDENCE_KEEP_DAYS` | 证据保留天数(0–365,0 = 不清理) | 7 |
|
|
445
|
+
| `DSH_STM32_EVIDENCE_KEEP_SESSIONS` | 证据保留会话数(1–200) | 20 |
|
|
446
|
+
| `DSH_STM32_SNAPSHOTS` | `.ioc` 基线目录 | `~/.dsh-stm32/ioc-snapshots` |
|
|
447
|
+
| `DSH_STM32_OFFLINE` | 设为 `1` 禁止联网下载(模板与固件包仅用本地缓存) | 不设 |
|
|
448
|
+
| `MSYS2_MIRROR` | 安装包镜像,必须与 `MSYS2_INSTALLER_SHA256` 同时设置 | 官方 → TUNA → NJU → 阿里云 |
|
|
449
|
+
| `MSYS2_INSTALLER_URL` / `MSYS2_INSTALLER_SHA256` | 覆盖安装包地址与校验和,必须成对设置 | 官方固定版本 |
|
|
450
|
+
| `DSH_STM32_JLINK_URL` / `DSH_STM32_JLINK_SHA256` | 覆盖 J-Link 直链与校验和,必须成对设置 | SEGGER 官方 |
|
|
451
|
+
|
|
452
|
+
工具参数与上述变量等价:烧录与调试类接受 `binDirs`、`elfPath`、`buildDir`、`configFile`、`adapterSpeed`;生成与建工程类接受 `cubeMxRoots`、`firmwarePackage`。
|
|
453
|
+
|
|
454
|
+
工具链位置通常无需配置:未指定 `binDirs` / `STM32_BIN_DIRS` 时,插件会在常见位置查找并追加候选——`<盘>/msys64`、`<盘>/msys2`、`<盘>/app/msys64`、`<盘>/tools/msys64`、`%LOCALAPPDATA%/Programs/msys64` 下的 `ucrt64/bin`、`mingw64/bin`、`clang64/bin`,以及 `STM32CubeMX_PATH` 环境变量、CubeMX 卸载登记项、`Program Files\STMicroelectronics\STM32Cube` 等位置下的 CubeMX。找不到时,错误与 `stm32_doctor` 会列出已检查的目录。
|
|
455
|
+
|
|
456
|
+
### openocd.cfg(工程内优先)
|
|
457
|
+
|
|
458
|
+
CMSIS-DAP(默认):
|
|
459
|
+
|
|
460
|
+
```text
|
|
461
|
+
source [find interface/cmsis-dap.cfg]
|
|
462
|
+
source [find target/stm32f1x.cfg]
|
|
463
|
+
adapter speed 4000
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
ST-Link:
|
|
467
|
+
|
|
468
|
+
```text
|
|
469
|
+
source [find interface/stlink.cfg]
|
|
470
|
+
transport select hla_swd
|
|
471
|
+
source [find target/stm32f1x.cfg]
|
|
472
|
+
```
|
|
473
|
+
|
|
474
|
+
工程内没有 `openocd.cfg` 时按 `.ioc` 的芯片族选择调试脚本(F1 → `stm32f1x`、F4 → `stm32f4x`、G4 → `stm32g4x`;L4 与 L4+ 共用 `stm32l4x`)。C0 / U0 的脚本随插件提供并在建工程时复制到工程的 `openocd/` 目录;H5 / N6 / U3 / WBA / WB0 / WL3 / MP2 暂无脚本,烧录会被明确拒绝。
|
|
475
|
+
|
|
476
|
+
### `.ioc` 的两个硬要求
|
|
477
|
+
|
|
478
|
+
1. **SYS 调试口为 Serial Wire**(PA13 = `SYS_JTMS-SWDIO`、PA14 = `SYS_JTCK-SWCLK`);缺失时用 `stm32_ioc_plan` 的 `serialWire: true` 补齐。
|
|
479
|
+
2. **`ProjectManager.KeepUserCode=true`**;否则重新生成时 `USER CODE` 内容不保留。
|
|
480
|
+
|
|
481
|
+
## 已知限制
|
|
482
|
+
|
|
483
|
+
| 限制 | 说明 | 处理方式 |
|
|
484
|
+
| --- | --- | --- |
|
|
485
|
+
| 仅在 Windows 验证 | 生成代码依赖 CubeMX 的 Windows 安装形态 | 暂无可替代方案;烧录、调试、读寄存器在其他平台理论可用,未验证 |
|
|
486
|
+
| 部分芯片暂无官方调试脚本 | C0 / U0 用插件自带的适配脚本(未上板验证);H5 / N6 / U3 / WBA / WB0 / WL3 / MP2 暂无脚本 | 烧录前会明确说明,不会静默失败 |
|
|
487
|
+
| HAL 建工程不覆盖双核与 MPU 系列 | 双核 WB、MP1 / MP2 / N6、WB0 / WL3 不在范围内 | 建工程时直接说明不支持 |
|
|
488
|
+
| 深层能力按族分级 | HAL 21 族、寄存器 21 族、时钟 18 族;寄存器名与位域目前只有 F1 | 缺哪项就在调用时说明哪项 |
|
|
489
|
+
| 探针按 USB 实见选择 | ST-Link、DAPLink / CMSIS-DAP、J-Link 自动区分;工程内 `openocd.cfg` 优先 | 需要固定选择时手写 `openocd.cfg` |
|
|
490
|
+
| 新增外设需手工补 HAL 源 | 插件只放置 `Src/` 与 `Inc/`,CubeMX 生成的 `cmake/**` 不搬运 | 修改 `STM32_Drivers_Src` 或写入 `cmake/user/CMakeLists.txt` |
|
|
491
|
+
| 生成与建工程需要 CubeMX 与对应固件包 | F1 默认 `STM32Cube_FW_F1_V1.8.7` | 传 `firmwarePackage`,或先在 CubeMX 内安装固件包 |
|
|
492
|
+
| RTT 仅通道 0,帧头为自定义格式 | 13 字节头(长度 + 级别 + 时间戳 + UTF-8 正文) | 用级别过滤;结构化内容写入正文;通道与环大小见 `rtt.h` |
|
|
493
|
+
| 串口仅 Windows | 不含推流、自动重连,一次一个端口 | 使用系统串口工具,或等待后续版本 |
|
|
494
|
+
| 寄存器名与位域依赖内置寄存器表 | 目前覆盖 F1 的 100 / 101 / 102 / 103 / 105 / 107 | 使用 `0x` 开头的地址;`stm32_assets verify` 检查安装完整性 |
|
|
495
|
+
|
|
496
|
+
## 排错
|
|
497
|
+
|
|
498
|
+
| 现象 | 原因 | 处理 |
|
|
499
|
+
| --- | --- | --- |
|
|
500
|
+
| 插件未加载 | profile 的 `dsh.profile.bundles` 未包含 `dsh-stm32`,或未重启 | 重装并重启 DSH;用 `dsh plugin --profile desktop why dsh-stm32` 校验 |
|
|
501
|
+
| 修改代码后行为未变 | 用 `file:` 安装,宿主读取的是拷贝 | 改用 `link:`,重新 `npm run build` 并重启 DSH |
|
|
502
|
+
| 报缺工具链 | 未安装或路径未收录 | 先跑 `/stm32-env` 看缺什么,再 `/stm32-setup` 安装;或手工设置 `binDirs` |
|
|
503
|
+
| 烧录报探针占用 | 其他调试器(VS Code、残留 openocd)持有探针 | `/stm32-stop`,关闭其他调试器后重试;`stm32_doctor` 会列出残留进程 |
|
|
504
|
+
| 烧录后 SWD 失联 | `.ioc` 未启用 Serial Wire | 用 `stm32_ioc_plan` 的 `serialWire: true` 补齐后重新生成并烧录 |
|
|
505
|
+
| 生成后外设被丢弃 | `.ioc` 键与外设推导不一致 | 用 `stm32_ioc_verify` 让 CubeMX 诊断 |
|
|
506
|
+
| 面板空白或数据不更新 | 服务端改动未重启,或 `lib` 比进程新 | 完全退出 DSH 再启动;面板状态条会提示「有新构建」 |
|
|
507
|
+
| 串口无数据 | 端口选择错误(如选到 DAPLink 虚拟串口) | `stm32_serial list` 确认端口;应用串口通常在 CH340 等 USB 转串口设备上 |
|
|
508
|
+
|
|
509
|
+
## 开发与测试
|
|
510
|
+
|
|
511
|
+
| 命令 | 作用 |
|
|
512
|
+
| --- | --- |
|
|
513
|
+
| `npm run build` | `tsc` 编译到 `lib/`,并复制客户端与数据资源 |
|
|
514
|
+
| `node test/run-units.mjs` | 离线单测:81 个套件 / 1101 个用例,不需要板子 |
|
|
515
|
+
| `node .dsh-stm32/acceptance.mjs` | 本机验收脚本:面板 API、事件流、证据、产物、故障、中断、串口与探针 |
|
|
516
|
+
| `npm run test:pack` | 打包 tarball、解包、用解包产物实际建一次寄存器工程 |
|
|
517
|
+
| `npm run test:size` | 包体与资产护栏 |
|
|
518
|
+
|
|
519
|
+
发布形态:随包发布的内容限定在 `package.json` 的 `files`(`lib`、`client`、`templates`、`assets`、`docs/reading-guide.md`、`cordis.patch.yml`、两份 README、`LICENSE`)。开发用的 `docs/`、`test/`、`scripts/` 不进包。
|
|
520
|
+
|
|
521
|
+
开发调试用的环境变量(日常使用无需设置):`DSH_STM32_ASSETS`、`DSH_STM32_FACTS` 覆盖资源目录,`DSH_STM32_SERIAL_BRIDGE`、`DSH_STM32_SERIAL_POWERSHELL` 覆盖串口桥路径,`DSH_STM32_PYTHON` 指定解析用的 Python 解释器。
|
|
522
|
+
|
|
523
|
+
## 目录结构
|
|
524
|
+
|
|
525
|
+
```text
|
|
526
|
+
src/
|
|
527
|
+
index.ts 插件入口:注册工具、斜杠命令、面板 API 与 SKILL
|
|
528
|
+
tools/ 37 个工具的注册与参数校验
|
|
529
|
+
engine/ 引擎:工程、.ioc、生成、构建、烧录、调试、事件与面板 API
|
|
530
|
+
data/ 芯片数据、CubeMX 数据、时钟、搜索根、工具链配置
|
|
531
|
+
commands/ 7 条斜杠命令
|
|
532
|
+
skill/ 随包下发的 stm32-workflow SKILL
|
|
533
|
+
client/client.js 面板源码(纯 JS + react,无打包器)
|
|
534
|
+
lib/ tsc 产物与复制后的资源(随包发布)
|
|
535
|
+
assets/ 芯片数据、.ioc 模板、链接脚本、启动文件、寄存器表
|
|
536
|
+
templates/ 建工程模板、寄存器模板、串口桥与 RTT 模板
|
|
537
|
+
test/ 80 个离线套件与 e2e 脚本
|
|
538
|
+
scripts/ 构建、打包、体积与冒烟脚本
|
|
539
|
+
docs/ 开发笔记、精读指南、规格书、图表
|
|
540
|
+
```
|
|
541
|
+
|
|
542
|
+
## 文档
|
|
543
|
+
|
|
544
|
+
- [规格书](docs/dsh-stm32-plugin-规格.md):工具契约、状态机、验收判定标准
|
|
545
|
+
- [开发笔记](docs/development-notes.md):里程碑、宿主契约问题、各工具实现细节与实测数据
|
|
546
|
+
- [源码精读指南](docs/reading-guide.md):分层阅读顺序、文件职责与关键导出、流程图与不变量
|
|
547
|
+
- 发布说明:按版本随发布页提供,历史见 git 历史与开发笔记
|
|
548
|
+
- 可视化:[架构总览](docs/diagrams/dsh-stm32-architecture.html) / [主线旅程](docs/diagrams/dsh-stm32-journey.html)(单文件 HTML,离线可开)
|
|
549
|
+
|
|
550
|
+
## 致谢
|
|
551
|
+
|
|
552
|
+
电路设计与 PCB 能力的部分设计参考了以下两个开源项目(只借鉴设计思路与流程,代码按各自许可使用):
|
|
553
|
+
|
|
554
|
+
- [oh-my-embedded](https://github.com/captainluzik/oh-my-embedded)(MIT):把专家经验固化成可调用的小工具(功耗预算、去耦建议、引脚映射、阻抗计算),本插件的去耦与放置建议参照了这一思路。
|
|
555
|
+
- [PCB-Agent-Teams](https://github.com/Zane456/PCB-Agent-Teams)(PolyForm Noncommercial 1.0.0):分阶段流水线与"门禁不通过就回滚、每个结论双路校验、资产未落盘不许画板"的工程纪律;本插件借鉴其流程设计,未复制其代码。
|
|
556
|
+
|
|
557
|
+
同时致谢其依赖的上游项目,本插件以依赖或思路借鉴方式使用:
|
|
558
|
+
|
|
559
|
+
- [KiCad](https://www.kicad.org/):原理图与 PCB 的读写、`kicad-cli` 与 `pcbnew` Python API。
|
|
560
|
+
- [kicad-happy](https://github.com/aklofas/kicad-happy)(MIT):EMC、热与生命周期分析的规则来源。
|
|
561
|
+
- [KiCadRoutingTools](https://github.com/drandyhaas/KiCadRoutingTools)(MIT):网格自动布线的实现参考。
|
|
562
|
+
- [ngspice](https://ngspice.sourceforge.io/):SPICE 复核。
|
|
563
|
+
- [poppler](https://poppler.freedesktop.org/):PDF 文字、表格与渲染。
|
|
564
|
+
- [tscircuit](https://tscircuit.com/):电路源码到 KiCad 工程的生成。
|
|
565
|
+
|
|
566
|
+
## 许可证
|
|
567
|
+
|
|
568
|
+
[MIT](LICENSE)
|