dsh-stm32 0.1.3 → 0.1.5
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 +115 -43
- package/README_EN.md +106 -38
- package/assets/README.md +85 -0
- package/assets/VERSION +1 -0
- package/assets/device/c0/chips.json +1108 -0
- package/assets/device/f0/chips.json +1570 -0
- package/assets/device/f1/chips.json +1238 -0
- package/assets/device/f1/svd/100.json +943 -0
- package/assets/device/f1/svd/101.json +901 -0
- package/assets/device/f1/svd/102.json +522 -0
- package/assets/device/f1/svd/103.json +1139 -0
- package/assets/device/f1/svd/105.json +1117 -0
- package/assets/device/f1/svd/107.json +1195 -0
- package/assets/device/f2/chips.json +674 -0
- package/assets/device/f3/chips.json +1318 -0
- package/assets/device/f4/chips.json +2942 -0
- package/assets/device/f7/chips.json +1710 -0
- package/assets/device/g0/chips.json +2102 -0
- package/assets/device/g4/chips.json +2494 -0
- package/assets/device/h5/chips.json +898 -0
- package/assets/device/h7/chips.json +2639 -0
- package/assets/device/l0/chips.json +2494 -0
- package/assets/device/l1/chips.json +1234 -0
- package/assets/device/l4/chips.json +2130 -0
- package/assets/device/l4+/chips.json +856 -0
- package/assets/device/l5/chips.json +226 -0
- package/assets/device/u0/chips.json +688 -0
- package/assets/device/u3/chips.json +310 -0
- package/assets/device/u5/chips.json +1195 -0
- package/assets/device/wba/chips.json +506 -0
- package/assets/device/wl/chips.json +184 -0
- package/assets/headers/f1/stm32f100xb.h +5972 -0
- package/assets/headers/f1/stm32f100xe.h +6587 -0
- package/assets/headers/f1/stm32f101x6.h +5315 -0
- package/assets/headers/f1/stm32f101xb.h +5446 -0
- package/assets/headers/f1/stm32f101xe.h +6503 -0
- package/assets/headers/f1/stm32f101xg.h +6713 -0
- package/assets/headers/f1/stm32f102x6.h +6448 -0
- package/assets/headers/f1/stm32f102xb.h +6570 -0
- package/assets/headers/f1/stm32f103x6.h +10109 -0
- package/assets/headers/f1/stm32f103xb.h +10240 -0
- package/assets/headers/f1/stm32f103xe.h +11767 -0
- package/assets/headers/f1/stm32f103xg.h +11951 -0
- package/assets/headers/f1/stm32f105xc.h +14340 -0
- package/assets/headers/f1/stm32f107xc.h +15253 -0
- package/assets/headers/f1/stm32f1xx.h +273 -0
- package/assets/headers/f1/system_stm32f1xx.h +96 -0
- package/assets/ioc/family/C0.ioc +82 -0
- package/assets/ioc/family/F0.ioc +71 -0
- package/assets/ioc/family/F2.ioc +91 -0
- package/assets/ioc/family/F3.ioc +94 -0
- package/assets/ioc/family/F4.ioc +91 -0
- package/assets/ioc/family/F7.ioc +102 -0
- package/assets/ioc/family/G0.ioc +90 -0
- package/assets/ioc/family/G4.ioc +110 -0
- package/assets/ioc/family/H5.ioc +116 -0
- package/assets/ioc/family/H7.ioc +133 -0
- package/assets/ioc/family/L0.ioc +92 -0
- package/assets/ioc/family/L1.ioc +87 -0
- package/assets/ioc/family/L4+.ioc +92 -0
- package/assets/ioc/family/L4.ioc +93 -0
- package/assets/ioc/family/L5.ioc +91 -0
- package/assets/ioc/family/U0.ioc +103 -0
- package/assets/ioc/family/U3.ioc +113 -0
- package/assets/ioc/family/U5.ioc +102 -0
- package/assets/ioc/family/WBA.ioc +100 -0
- package/assets/ioc/family/WL.ioc +93 -0
- package/assets/ioc/minimal/STM32F100C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F100RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101C4Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F101RFTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F102C4Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F102C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103C4Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103C8Tx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F103RFTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F105RCTx.ioc +113 -0
- package/assets/ioc/minimal/STM32F107RCTx.ioc +113 -0
- package/assets/ld/f1/STM32F100C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F100RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101C4Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F101RFTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F102C4Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F102C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103C4Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103C8Tx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F103RFTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F105RCTx_FLASH.ld +249 -0
- package/assets/ld/f1/STM32F107RCTx_FLASH.ld +249 -0
- package/assets/manifest.json +1130 -0
- package/assets/startup/f1/startup_stm32f100xb.s +407 -0
- package/assets/startup/f1/startup_stm32f100xe.s +449 -0
- package/assets/startup/f1/startup_stm32f101x6.s +322 -0
- package/assets/startup/f1/startup_stm32f101xb.s +338 -0
- package/assets/startup/f1/startup_stm32f101xe.s +423 -0
- package/assets/startup/f1/startup_stm32f101xg.s +439 -0
- package/assets/startup/f1/startup_stm32f102x6.s +330 -0
- package/assets/startup/f1/startup_stm32f102xb.s +346 -0
- package/assets/startup/f1/startup_stm32f103x6.s +348 -0
- package/assets/startup/f1/startup_stm32f103xb.s +364 -0
- package/assets/startup/f1/startup_stm32f103xe.s +470 -0
- package/assets/startup/f1/startup_stm32f103xg.s +466 -0
- package/assets/startup/f1/startup_stm32f105xc.s +463 -0
- package/assets/startup/f1/startup_stm32f107xc.s +472 -0
- package/assets/templates/family/C0.ioc +82 -0
- package/assets/templates/family/F0.ioc +71 -0
- package/assets/templates/family/F2.ioc +91 -0
- package/assets/templates/family/F3.ioc +94 -0
- package/assets/templates/family/F4.ioc +91 -0
- package/assets/templates/family/F7.ioc +102 -0
- package/assets/templates/family/G0.ioc +90 -0
- package/assets/templates/family/G4.ioc +110 -0
- package/assets/templates/family/H5.ioc +116 -0
- package/assets/templates/family/H7.ioc +133 -0
- package/assets/templates/family/L0.ioc +92 -0
- package/assets/templates/family/L1.ioc +87 -0
- package/assets/templates/family/L4+.ioc +92 -0
- package/assets/templates/family/L4.ioc +93 -0
- package/assets/templates/family/L5.ioc +91 -0
- package/assets/templates/family/U0.ioc +103 -0
- package/assets/templates/family/U3.ioc +113 -0
- package/assets/templates/family/U5.ioc +102 -0
- package/assets/templates/family/WB.ioc +81 -0
- package/assets/templates/family/WBA.ioc +100 -0
- package/assets/templates/family/WL.ioc +93 -0
- package/docs/reading-guide.md +110 -42
- package/lib/commands/register.js +1 -1
- package/lib/data/chips.js +3 -3
- package/lib/data/clock-db.js +830 -0
- package/lib/data/clock-f1.js +12 -45
- package/lib/data/cmsis-sources.js +371 -18
- package/lib/data/db-presets.js +252 -0
- package/lib/data/device-facts.js +113 -26
- package/lib/data/family.js +515 -0
- package/lib/data/firmware-packages.js +595 -12
- package/lib/data/firmware-pins.js +128 -0
- package/lib/data/install-guides.js +2 -2
- package/lib/data/ioc-presets.js +248 -0
- package/lib/data/ioc-schema.js +1058 -0
- package/lib/data/rm-topics/stm32c0.json +227 -0
- package/lib/data/rm-topics.js +103 -0
- package/lib/data/search-roots.js +59 -4
- package/lib/data/serial-config.js +430 -0
- package/lib/data/stm32f1.js +15 -14
- package/lib/data/svd.js +32 -16
- package/lib/data/toolchain-config.js +0 -14
- package/lib/engine/assets.js +191 -456
- package/lib/engine/breakpoints.js +66 -11
- package/lib/engine/clock-derived.js +101 -0
- package/lib/engine/clock-direct.js +313 -0
- package/lib/engine/clock-plan.js +96 -52
- package/lib/engine/clock-pllmn.js +319 -0
- package/lib/engine/cmake-sources.js +67 -13
- package/lib/engine/cube-mx-guard.js +44 -0
- package/lib/engine/cube-programmer.js +137 -0
- package/lib/engine/cubemx-db.js +273 -0
- package/lib/engine/debug-session.js +423 -17
- package/lib/engine/debug.js +25 -6
- package/lib/engine/doctor.js +239 -19
- package/lib/engine/download.js +242 -0
- package/lib/engine/facts-acquire.js +416 -0
- package/lib/engine/facts.js +134 -0
- package/lib/engine/fetch.js +1 -1
- package/lib/engine/firmware-install.js +333 -39
- package/lib/engine/firmware-official.js +499 -0
- package/lib/engine/flash.js +290 -21
- package/lib/engine/gdb-mi.js +476 -0
- package/lib/engine/generate.js +9 -2
- package/lib/engine/hal-chip.js +124 -41
- package/lib/engine/ioc-plan.js +1244 -60
- package/lib/engine/ioc-rules.js +698 -0
- package/lib/engine/ioc-verify.js +706 -0
- package/lib/engine/ioc.js +43 -4
- package/lib/engine/msys2-install.js +241 -92
- package/lib/engine/probe-error.js +25 -6
- package/lib/engine/probe-session.js +50 -14
- package/lib/engine/probe.js +22 -5
- package/lib/engine/register-clock.js +41 -0
- package/lib/engine/register-gpio.js +132 -0
- package/lib/engine/register-linker.js +37 -13
- package/lib/engine/register-template.js +125 -40
- package/lib/engine/regs.js +41 -8
- package/lib/engine/rm-extract.js +144 -0
- package/lib/engine/rm-sources.js +360 -0
- package/lib/engine/rm-text.js +56 -0
- package/lib/engine/rtt.js +188 -30
- package/lib/engine/scaffold.js +185 -18
- package/lib/engine/serial.js +1692 -0
- package/lib/engine/tar.js +235 -3
- package/lib/engine/toolchain-gate.js +0 -4
- package/lib/engine/watch.js +227 -0
- package/lib/index.js +16 -2
- package/lib/skill/stm32-workflow.js +2 -2
- package/lib/tools/assets.js +39 -108
- package/lib/tools/cache.js +2 -2
- package/lib/tools/debug-session.js +2 -2
- package/lib/tools/doctor.js +61 -5
- package/lib/tools/download.js +303 -0
- package/lib/tools/firmware-install.js +31 -6
- package/lib/tools/flash.js +32 -4
- package/lib/tools/generate.js +22 -0
- package/lib/tools/ioc-inspect.js +1 -1
- package/lib/tools/ioc-plan.js +56 -2
- package/lib/tools/ioc-verify.js +237 -0
- package/lib/tools/project-create.js +41 -5
- package/lib/tools/regs.js +8 -8
- package/lib/tools/route-plan.js +1 -1
- package/lib/tools/rtt.js +157 -34
- package/lib/tools/serial.js +737 -0
- package/lib/tools/watch.js +256 -0
- package/package.json +5 -4
- package/templates/openocd/stm32c0x.cfg +83 -0
- package/templates/openocd/stm32u0x.cfg +64 -0
- package/templates/register/CMakeLists.txt +2 -2
- package/templates/register/Core/Inc/rtt.h +37 -2
- package/templates/register/Core/Src/main.c +17 -25
- package/templates/register/Core/Src/rtt.c +85 -9
- package/templates/scaffold/RTT.md +6 -2
- package/templates/scaffold/STM32F103XX_FLASH.ld +3 -0
- package/templates/scaffold/openocd.cfg +5 -3
- package/templates/scaffold/vscode/launch.json +8 -4
- package/templates/serial/bridge.ps1 +477 -0
- package/docs/development-notes.md +0 -2487
- package/docs/dsh-stm32-plugin-/350/247/204/346/240/274.md +0 -673
- package/docs/logic-audit.md +0 -607
package/README_EN.md
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
# dsh-stm32
|
|
2
2
|
|
|
3
|
-
> Hand the whole **
|
|
3
|
+
> Hand the whole **STM32 family** (27 families: 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) development chain to DSH: probe the toolchain → scaffold a project → edit the .ioc (clocks included) → generate code → build → debug → flash, plus serial interaction (`stm32_serial`, Windows P1). The family is read from the .ioc's `Mcu.Family`: pin names, SWD debug signal names, EXTI NVIC vector grouping, the openocd target and the hardware breakpoint/watchpoint budget all follow the family and its core. **HAL scaffolding** (firmware package, startup file, device define, linker script, .ioc template, cmake and debug configuration) is implemented per family for the 21 single-core families (C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / U0 / U3 / U5 / WBA / WL); the register route covers 21 families, all verified through create→build (the per-family results for the 8 new ones are in development-notes §87.5); clock planning covers 18 families (PLL1 on H5 / U5 / WBA / L4+), .ioc peripheral presets are derived from the CubeMX db, and SVD validation is still F1-only — uncovered capabilities are refused with a reason instead of silently reusing F1 tables (see [Known limitations](#known-limitations)).
|
|
4
4
|
|
|
5
5
|
[中文](./README.md) · [Quick start](#quick-start-a-minimal-end-to-end-check-empty-directory-to-a-blinking-led) · [Features](#features) · [Tool reference](#tool-reference) · [Slash commands](#slash-commands) · [Design notes](#design-notes) · [Known limitations](#known-limitations) · [Troubleshooting](#troubleshooting) · [Specification](docs/dsh-stm32-plugin-规格.md)
|
|
6
6
|
|
|
7
7
|
[](https://github.com/JingYu-er/dsh-stm32)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
[](#known-limitations)
|
|
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 25 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
|
|
|
@@ -50,14 +50,14 @@ Paths are searched as MSYS2 (`C:/msys64/ucrt64/bin`, `C:/msys64/mingw64/bin`)
|
|
|
50
50
|
### Install (recommended: one command)
|
|
51
51
|
|
|
52
52
|
```powershell
|
|
53
|
-
dsh plugin --profile desktop add
|
|
53
|
+
dsh plugin --profile desktop add dsh-stm32
|
|
54
54
|
```
|
|
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.5`); after a restart `/stm32-doctor` should respond.
|
|
59
59
|
|
|
60
|
-
> **
|
|
60
|
+
> **Chip facts ship with the plugin**: device facts (part → startup file / device define / Flash·RAM size) come from `assets/device/<family>/chips.json` inside the package (75 files for `core`, 105 for `full`: chip tables + memory layout + `.ioc` templates + linker scripts + SVD). Everything works offline once installed — no asset-pack download. Run `stm32_assets verify` to check integrity; missing files usually mean an incomplete install.
|
|
61
61
|
|
|
62
62
|
|
|
63
63
|
**Uninstall**: `dsh plugin --profile desktop remove dsh-stm32`, then restart dsh.
|
|
@@ -69,9 +69,9 @@ git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
|
69
69
|
cd dsh-stm32
|
|
70
70
|
npm install --no-audit --no-fund # typescript only
|
|
71
71
|
npm run build # tsc -> lib/ (required before committing)
|
|
72
|
-
npm test # optional:
|
|
72
|
+
npm test # optional: 947 offline cases in 60 suites, no board needed
|
|
73
73
|
npm run test:pack # pack a tarball, unpack it, scaffold a real register project from it
|
|
74
|
-
npm run test:size # package guard: tarball <=
|
|
74
|
+
npm run test:size # package guard: tarball <=3.9 MB, runtime assets under templates/ (.ioc/.xml/.ld/.json/.cfg) <=40 KB, no binaries/diagrams inside
|
|
75
75
|
```
|
|
76
76
|
|
|
77
77
|
Link it into your dsh profile — **while editing code use `link:`, never `file:`**:
|
|
@@ -99,7 +99,7 @@ This chain ran on a real board (acceptance A1, 2026-10-22), driven entirely by t
|
|
|
99
99
|
| 5 | **Flash only**: program + verify + reset | `stm32_flash` | 2.1–2.6 s |
|
|
100
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
101
|
|
|
102
|
-
> Step 6 uses the symbol form (`GPIOC.ODR`), which needs the SVD tables
|
|
102
|
+
> Step 6 uses the symbol form (`GPIOC.ODR`), which needs the SVD tables bundled with the plugin (`assets/device/f1/svd/`, `full` logical tier). A `core`-only or incomplete install still reads raw addresses — write `0x4001100C` instead, and the report has neither register names nor bit-field decoding.
|
|
103
103
|
|
|
104
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:
|
|
105
105
|
|
|
@@ -124,30 +124,33 @@ The blinking LED is the **smallest smoke test** for this chain: it walks create
|
|
|
124
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 |
|
|
125
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) |
|
|
126
126
|
| Tuning parameters, changing clocks | `.ioc` transactions: diff first → SHA check → backup → rollback on failure | Verified |
|
|
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
|
|
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 bundled SVDs with a fake probe, **hardware re-test pending** (development notes §31.11) |
|
|
128
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`) |
|
|
129
129
|
|
|
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
|
|
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) — HAL scaffolding covers 21 single-core families and the register route covers 21 families (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.
|
|
131
131
|
|
|
132
132
|
## Features
|
|
133
133
|
|
|
134
134
|
| Capability | How it is provided |
|
|
135
135
|
| --- | --- |
|
|
136
|
-
| Environment health check | `
|
|
136
|
+
| Environment health check | `stm32_doctor` (read-only), `stm32_doctor` (toolchain + busy probes + ports + project warnings) |
|
|
137
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"` |
|
|
138
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 |
|
|
139
|
+
| Installer downloads (download only) | `stm32_download`: J-Link direct link + SHA256; CubeMX / CubeProgrammer return the official page or verify a local file; it downloads/verifies but never runs an installer or asks for admin |
|
|
139
140
|
| 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
|
|
141
|
+
| Chip facts (part → startup file / device define / sizes) | The plugin **ships the chip table inside the npm package**: part, startup file, device define and Flash/RAM come from `assets/device/f1/chips.json` (`lib/engine/assets.js` resolves `assets/` from the package root; `DSH_STM32_ASSETS` can still point elsewhere for development). A missing file only means an incomplete install: locate it with `stm32_assets verify`, then reinstall the plugin — no network needed |
|
|
141
142
|
| 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) |
|
|
142
143
|
| 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 |
|
|
143
144
|
| `.ioc` as a transaction | `stm32_ioc_inspect` (read-only parse) → `stm32_ioc_plan` (diff, no writes) → `stm32_ioc_apply` (SHA check + backup + rollback) |
|
|
144
145
|
| USER CODE only | `stm32_code_patch`: writes only between `/* USER CODE BEGIN X */` and `END X`; everything else untouched |
|
|
145
146
|
| Code generation | `stm32_generate`: headless CubeMX + ST project layout + USER CODE carried over by label |
|
|
146
147
|
| 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 |
|
|
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
|
|
148
|
+
| 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 9) |
|
|
148
149
|
| Debug | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
|
|
149
150
|
| 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 |
|
|
151
|
+
| Variable watch / watchpoints | `stm32_watch`: `action=add` registers expressions (`kind=value` is sampling only and needs no session); `action=sample` halts, evaluates each expression, computes the delta, and resumes if the target was running; `kind=write/read/access` installs hardware watchpoints (gdb `watch`/`rwatch`/`awatch`), bounded by the F1's 4 data comparators |
|
|
150
152
|
| 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 |
|
|
153
|
+
| Serial interaction (Windows P1) | `stm32_serial`: `list` / `open` / `read` / `send` / `transact` / `status` / `close`; zero npm dependencies (a PowerShell 5.1 + `System.IO.Ports` bridge holds the COM port), default 115200 8N1, DTR/RTS not asserted, `persist=false`, one session at a time; **no GUI panel, no SSE, no Linux/macOS, no auto-reconnect** (see [Serial](#serial-windows-p1)) |
|
|
151
154
|
| 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) |
|
|
152
155
|
|
|
153
156
|
## Tool reference
|
|
@@ -156,22 +159,24 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
156
159
|
|
|
157
160
|
| Tool | What it does |
|
|
158
161
|
| --- | --- |
|
|
159
|
-
| `
|
|
160
|
-
| `stm32_env_install` | One-stop install when the toolchain is missing: `dryRun` (default) only returns a plan — size of the official MSYS2 installer, the five packages, the PATH entry it would add; only `dryRun: false` + `confirm: true` actually work (download → install MSYS2 → `pacman -S` → user-level PATH → self-check → write `~/.dsh-stm32/config.json`). With an existing msys64 it only adds the packages. No uninstall |
|
|
162
|
+
| `stm32_doctor` | Detects gcc / gdb / openocd / cmake / ninja / CubeMX / JRE paths and versions; for anything missing it states the impact (cannot build / flash / debug / generate), the recommended install command (pacman / winget, paste-ready), a self-check command, plus `capabilities` (which of the four jobs work; flashing is split into `flashOpenocd` / `flashCubeProgrammer` and debugging into `debugOpenocd`) and `recommendations` (install order and an offer to install for you). CubeProgrammer-only setups say plainly that flashing works over ST-LINK but debugging does not; a missing openocd target script for the part is reported as blocker/note based on the probe actually seen; a missing J-Link driver is called out separately. Read-only, repeatable |
|
|
163
|
+
| `stm32_env_install` | One-stop install when the toolchain is missing: `dryRun` (default) only returns a plan — size of the official MSYS2 installer, the five packages, the PATH entry it would add; only `dryRun: false` + `confirm: true` actually work (download → verify size/MZ/sha256 → install MSYS2 → `pacman -S` → user-level PATH → self-check → write `~/.dsh-stm32/config.json`). The installer is pinned to stable release `2026-09-27` with a sha256; a custom source must supply its own hash, and a mismatch is never executed. With an existing msys64 it only adds the packages. No uninstall |
|
|
164
|
+
| `stm32_download` | Downloads installers but never runs them: `component: "jlink"` fetches SEGGER's official 8.18.0 installer and verifies its SHA256; `"cubemx"` / `"cubeprogrammer"` return the ST download page (myST login + licence), and a local `file` can be hashed for your own comparison. J-Link has one official direct link by default; a corporate mirror overrides it only with `DSH_STM32_JLINK_URL` + `DSH_STM32_JLINK_SHA256`, otherwise the official source is kept. `dryRun: true` (default) returns a plan; `dryRun: false` + `confirm: true` actually downloads or opens the page. No registry writes, no PATH edits, no admin request |
|
|
161
165
|
| `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 |
|
|
162
166
|
| `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 |
|
|
163
167
|
| `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 **
|
|
168
|
+
| `stm32_assets` | Manages the **resources bundled with the plugin** (chip tables for 21 families, memory layout, .ioc templates, linker scripts, SVD — not the CMSIS download cache): `action: "list"` / `"verify"` inspect and checksum `assets/` (75 files for `core`, 105 for `full`, shipped offline); `"refresh"` is an alias of `verify` (no download); `"prune"` only removes historical versions left under `DSH_STM32_ASSETS`. Missing files mean an incomplete install — reinstall the plugin |
|
|
165
169
|
| `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 |
|
|
166
170
|
| `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) |
|
|
167
|
-
| `stm32_firmware_install` | One-stop firmware-package install: `
|
|
171
|
+
| `stm32_firmware_install` | One-stop firmware-package install with two channels: `source: "auto"` (default) first builds the official zip URL from the part's db `FwLibrary`, downloads it (verifying `Content-Length` and every zip entry's CRC32) and hands it to CubeMX's own `swmgr install`, which lands it in `Repository` — a package the package manager actually tracks. If that cannot work (no CubeMX, a running GUI, or the first install of a family/version needing a licence dialog clicked by a human) the reason goes into `notes` and it falls back to assembling the package from GitHub (HAL driver + CMSIS device support + core headers, ~2 MB, self-written `package.xml`, placed in `<CubeMX root>/dsh-firmware` and pointed at by `setCustomFWPath`). Official-zip CRC32 verification is streamed (only the central directory and one entry at a time, never the whole multi-hundred-MB archive in memory); the assembled package is extracted into a staging directory and atomically swapped in only after verification, keeping the old package on failure; a cross-process install lock rejects a concurrent second install. `source: "official"` uses only the official channel and reports failure instead of falling back. `dryRun` (default) plans only; `dryRun: false` + `confirm: true` installs; does nothing when the package already exists |
|
|
168
172
|
|
|
169
173
|
### .ioc: read-only and transactions
|
|
170
174
|
|
|
171
175
|
| Tool | What it does |
|
|
172
176
|
| --- | --- |
|
|
173
177
|
| `stm32_ioc_inspect` | Parses MCU part, pins/signals/labels, peripherals and interrupts, clock tree, project settings; reports fatal risks such as "no Serial Wire means a generated `SWJ_DISABLE`" |
|
|
174
|
-
| `stm32_ioc_plan` | Step one of any `.ioc` change: computes a per-key diff plus the source SHA-256 and returns a `planId`, **without touching the source**. Supports setting/removing keys, adding GPIO from the chip pin table, one-shot Serial Wire repair, and retargeting clocks to the nearest reachable frequency (`clock: { targetHz }`, derived keys recomputed, per-peripheral frequencies reported) |
|
|
178
|
+
| `stm32_ioc_plan` | Step one of any `.ioc` change: computes a per-key diff plus the source SHA-256 and returns a `planId`, **without touching the source**. Supports setting/removing keys, adding GPIO from the chip pin table (pull/speed, open-drain `outputType: od`, initial level `initial`, and `interrupt` which writes the whole EXTI chain plus its IRQ group), enabling peripheral interrupts via `interrupts` (9-segment NVIC value, name checked against the db/SVD), one-shot Serial Wire repair, and retargeting clocks to the nearest reachable frequency (`clock: { targetHz }`, derived keys recomputed, per-peripheral frequencies reported). Key names are rendered from the `.ioc` truth table in `src/data/ioc-schema.ts` (49 specs). The coverage gate runs on two levels: keys outside the table raise a `[SCHEMA]` warning, and shape-only hits such as `{ip}.{name}` are additionally audited against live context (the db `RefParameter` name list, whether the instance is enabled in `Mcu.IP<i>`, and the DMA parameter whitelist), so a misspelled parameter or instance name is reported too — CubeMX silently ignores such keys. Enabling a peripheral also re-sorts `Mcu.IP<i>` into CubeMX's own natural order (`TIM2…TIM4,TIM15`, board-name pseudo instances last); otherwise every enable of an alphabetically-early peripheral produces a handful of phantom diffs on write-back |
|
|
179
|
+
| `stm32_ioc_verify` | Lets CubeMX say what it actually accepted: copies the `.ioc` to `.dsh-stm32/verify/<stamp>/`, rewrites it headlessly (`config load` + `config save`), then diffs key by key (100–180 s in practice, the project `.ioc` is not touched; if CubeMX never finished saving, the run fails instead of reporting a fake zero diff). Reports `droppedPeripherals` / `plannedFunctions` / `signalRewrites` / `removedKeys` / `addedKeys` / `changedValues` plus the `attribution` buckets: `orderOnly` (same value, different line order) / `valueNormalized` (only member order normalized) / `valueChanged` (value really changed) / `ipOrderOnly` (only `Mcu.IP<i>` slots moved, same peripheral set — not a substantive difference) / `derivedRecomputed` (derived clock outputs such as `RCC.*Freq_Value` recomputed by CubeMX from the PLL/dividers — not settings, so not a difference unless the plan wrote them) / `derivedAdded` (derived keys it adds on its own) / `ipParametersAdded` (derived names it appends to `RCC.IPParameters`) / `droppedReasons` and `addedVerdicts` (**per key, why CubeMX would not take it**: the peripheral never made it into `Mcu.IP<i>`, the parameter name is not in the db `RefParameter` list, a pin attribute written as a peripheral parameter, or a plainly misspelled prefix) / `benign` — **`benign: true` means zero substantive difference**, so it is safe to run `stm32_generate` |
|
|
175
180
|
| `stm32_ioc_apply` | Requires a `planId`; re-checks the SHA before writing (refuses if the file changed meanwhile), backs up, replaces atomically, re-parses to validate, rolls back on failure. Supports `rollbackFrom` |
|
|
176
181
|
|
|
177
182
|
### Code and build
|
|
@@ -191,7 +196,8 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
191
196
|
| `stm32_debug_session` | Long-lived openocd session (`.elf` resolved automatically), closed after 90 s idle, hard limit 10 min |
|
|
192
197
|
| `stm32_debug_eval` | Runs gdb commands or reads expressions (e.g. `g_led_blink_count`) inside the session, then `resume` + `detach` immediately |
|
|
193
198
|
| `stm32_debug_stop` | Releases the probe immediately, idempotent |
|
|
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
|
|
199
|
+
| `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 bundled SVD data (`full` logical tier) 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 reinstall the plugin (SVD ships in the `full` tier). 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 |
|
|
200
|
+
| `stm32_watch` | **Variable watch and hardware watchpoints**: `action: "add"` registers expressions (`expressions`; `kind` defaults to `value` = evaluated on every `sample`, while `write` / `read` / `access` go through gdb `watch` / `rwatch` / `awatch` — **data** comparators that do not share the code-breakpoint budget; an F1 has only 4, and overflow is rejected before any process starts). `kind=value` only registers and needs no session. `action: "sample"` halts, evaluates each entry, computes `delta` against the previous value, and runs `monitor resume` if the target had been running (`resume: false` keeps it halted); on error the previous value is kept and `lastError` is set. `action: "list"` / `"remove"` (`ids`) / `"clear"` manage the table. Lifecycle: the table is cleared when the session stops (watchpoints live inside the gdb process); a rebuilt MI marks watchpoints stale and asks you to `add` again. When gdb falls back to a **software watchpoint** the report warns, since it slows the target down |
|
|
195
201
|
| `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
202
|
|
|
197
203
|
### Adding RTT to the firmware (shortest example)
|
|
@@ -221,6 +227,37 @@ stm32_rtt action=stop # releases the port; also runs at tur
|
|
|
221
227
|
|
|
222
228
|
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.
|
|
223
229
|
|
|
230
|
+
## Serial (Windows P1)
|
|
231
|
+
|
|
232
|
+
`stm32_serial` lets the model open a serial port, send, receive and wait for replies itself — no serial terminal on the side, no copy-paste. This is **P1**: the smallest end-to-end loop, Windows only, with the boundaries stated below.
|
|
233
|
+
|
|
234
|
+
| Action | What it does |
|
|
235
|
+
| --- | --- |
|
|
236
|
+
| `list` | Every COM port with its PnP name, VID/PID, serial number and location, plus the settings remembered for that port (keyed by USB identity, so a different USB socket or COM number still finds the last baud rate) |
|
|
237
|
+
| `open` | Starts the resident PowerShell bridge and waits for `state=open` (up to 5 s); omit `port` to reuse the last successful port from `serial.json` |
|
|
238
|
+
| `read` | Reads received lines from the tail of `rx.ndjson`; pass the previous `nextCursor` as `cursor` to get only new lines, so the model never re-pastes history into context |
|
|
239
|
+
| `send` | Sends one line and waits for the bridge's `done` ack (up to 2 s); CRLF is appended by default, `raw: true` sends verbatim |
|
|
240
|
+
| `transact` | Sends a line and waits for an expected reply: `until` is a regex (e.g. `OK|ERROR`); on a hit it returns `matched` / `matchedLine`, on timeout it only reports `timedOut` — not a failure |
|
|
241
|
+
| `status` | Read-only snapshot: session, bridge pid, `rx.ndjson` / `tx.ndjson` sizes, session directories that may have been left behind |
|
|
242
|
+
| `close` | Graceful first: sends `close`, waits 3 s, then kills the pid |
|
|
243
|
+
|
|
244
|
+
Defaults: **115200 8N1, no flow control, DTR and RTS both de-asserted (asserting them resets many boards), UTF-8, CRLF appended on send**; `persist=false` closes the port at turn end (`persist=true` keeps it across turns). **One session at a time**: a second `open` returns `already-open` and asks you to `close` first — the "two logical sessions fighting over one port" class of bug cannot happen.
|
|
245
|
+
|
|
246
|
+
```text
|
|
247
|
+
stm32_serial action=list
|
|
248
|
+
stm32_serial action=open port=COM3 baudRate=115200
|
|
249
|
+
stm32_serial action=send text="AT"
|
|
250
|
+
stm32_serial action=transact text="AT" until="OK|ERROR" timeoutMs=1000
|
|
251
|
+
stm32_serial action=read cursor=0
|
|
252
|
+
stm32_serial action=close
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
**Why a PowerShell bridge**: the plugin has a hard zero-npm-dependency rule and Node ships no serial support; Windows ships PowerShell 5.1 and `System.IO.Ports.SerialPort`. The process that actually holds the COM port is therefore a bridge independent of the tool call (`templates/serial/bridge.ps1`, started with `spawn` + `unref` — not `detached`, which maps to `DETACHED_PROCESS` on Windows and makes PowerShell 5.1 exit immediately). The Node side only talks to it through files in one directory: `cmd/<id>.json` in, `done/<id>.json` back, `rx.ndjson` / `tx.ndjson` for the streams, `status.json` for state. The bridge checks its parent every 5 s: if DSH dies (window closed, host restarted) it releases the port and exits — otherwise that COM port would stay "in use" forever. Location: `%USERPROFILE%\.dsh-stm32\serial\<sessionId>\` (`DSH_STM32_SERIAL_HOME` moves the root).
|
|
256
|
+
|
|
257
|
+
Port settings are remembered in `%USERPROFILE%\.dsh-stm32\serial.json` (`DSH_STM32_SERIAL_CONFIG` overrides it), keyed by `usb:VID:PID:serial` → `usb:VID:PID@location` → `com:COMx`, three levels of fallback; only a successful `open` writes them. Failures carry one of 11 structured kinds (`unsupported-platform` / `powershell-missing` / `port-not-found` / `port-busy` / `access-denied` / `settings-invalid` / `bridge-start-timeout` / `bridge-crashed` / `disconnected` / `already-open` / `no-session`) with a `cause` / `hint` / `evidence` / `retryable` payload.
|
|
258
|
+
|
|
259
|
+
**P1 explicitly does not include**: a serial panel in the UI (the tool returns text only), SSE / WebSocket streaming (`read` is pull-based), Linux / macOS (the bridge is PowerShell; other hosts get `unsupported-platform`), or **auto-reconnect** (reopen after a disconnect). The real-hardware success path — `state=open`, actual received bytes, real DTR/RTS levels — has only fake-bridge and failure-path evidence in 0.1.5; see [Known limitations](#known-limitations) and development-notes §86.
|
|
260
|
+
|
|
224
261
|
## Slash commands
|
|
225
262
|
|
|
226
263
|
Tools are for the model; when you want to act yourself, use a command — one command, one action, no model decision in between.
|
|
@@ -247,9 +284,10 @@ Tools are for the model; when you want to act yourself, use a command — one co
|
|
|
247
284
|
|
|
248
285
|
## Chips, linker scripts and clocks
|
|
249
286
|
|
|
250
|
-
- **The part is a parameter, not a constant.** `stm32_project_create` / `stm32_generate` swap three things together from `mcu`: the startup file (`startup_stm32f103xe.s`), the device define (`STM32F103xE`) and the linker script (`STM32F103RCTx_FLASH.ld`). The HAL route goes through `src/engine/hal-chip.ts` (`resolveHalChip()` + `renderStartupAndDefine` / `renderLinkerScript` / `renderIoc`); the register route
|
|
287
|
+
- **The part is a parameter, not a constant.** `stm32_project_create` / `stm32_generate` swap three things together from `mcu`: the startup file (`startup_stm32f103xe.s`), the device define (`STM32F103xE`) and the linker script (`STM32F103RCTx_FLASH.ld`). The HAL route goes through `src/engine/hal-chip.ts` (`resolveHalChip()` + `renderStartupAndDefine` / `renderLinkerScript` / `renderIoc`); the register route resolves F1 through `src/data/stm32f1.ts` (`resolveF1Chip()`, 14 density grades, every startup file pinned by upstream sha256) and the other 20 families through `CMSIS_FAMILIES` in `src/data/cmsis-sources.ts` plus their bundled `assets/device/<family>/chips.json`. An unknown part returns a reason instead of inventing a startup file that does not exist upstream.
|
|
251
288
|
- **Linker scripts are named after the `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). The old `STM32F103XX_FLASH.ld` in the template survives only as a C8T6 compatibility copy; CMake's `-T` always points at the rendered one (`pointLinkerFlagAt()` rewrites the old name inside the toolchain file so you never end up with two `-T` flags and the wrong script).
|
|
252
289
|
- **Clocks: nearest, and say so when unreachable.** `stm32_ioc_plan`'s `clock: { targetHz }` (or `pllMul` to pin the multiplier, `pllSource` to pick HSE / HSI) enumerates every reachable PLL combination, takes the one with the smallest |SYSCLK − target| and states the gap: for 60 MHz the F1 PLL only multiplies integers and HSE 8 MHz cannot hit that step, so it picks 64 MHz and reports "unreachable, chose 64 MHz (+4 MHz)" (ties go to the higher step). The same plan **recomputes every derived key** (`SYSCLKFreq_VALUE`, `HCLKFre`, `PLLMUL`, APB1/APB2/ADC dividers) — changing only SYSCLK leaves CubeMX recomputing from stale values or ignoring them — and lists per-peripheral frequencies, UART baud error and a few alternatives. On an out-of-range request (SYSCLK > 72 MHz, APB1 > 36 MHz, ADC > 14 MHz, USB wanting 48 MHz outside PLLCLK/1.5) it **writes no key at all**.
|
|
290
|
+
- **The register route maps memory per chip, not per family template.** Startup file, device define and Flash/RAM all come from `assets/device/<family>/chips.json` for the 21 families; H7 uses only the 128 KiB DTCM (`0x20000000`) by default — all 138 parts carry a `linkerRam` window — U5 follows the per-line SRAM window (256 / 768 / 2496 KiB), while L4+ and L5 are single contiguous blocks (L5's 192 + 64 KiB are adjacent and merge to 256 KiB). The rendered `MEMORY` ORIGIN/LENGTH and `_estack` follow that window, so "builds fine, HardFaults on boot" from silent RAM overflow does not happen (see development-notes §87).
|
|
253
291
|
- **Five consistency checks before flashing.** `stm32_doctor` cross-checks `.ioc` part ↔ startup file name ↔ device define in cmake ↔ `.ld` MEMORY sizes ↔ `.elf` Flash usage, and reports a blocker on any mismatch. The `.elf` figure sums `p_filesz` from the ELF program headers rather than using the file size — with `-g3` a 20 KiB firmware produces a 600 KB `.elf`, which would false-alarm "over Flash".
|
|
254
292
|
## Configuration
|
|
255
293
|
|
|
@@ -294,15 +332,32 @@ What the register route needs — CMSIS device headers, the startup file, core h
|
|
|
294
332
|
|
|
295
333
|
### Firmware packages (HAL route)
|
|
296
334
|
|
|
297
|
-
Having CubeMX installed does not mean the package for **this particular part** is there — it is not part of the installer and has to be added in the package manager.
|
|
335
|
+
Having CubeMX installed does not mean the package for **this particular part** is there — it is not part of the installer and has to be added in the package manager. `stm32_firmware_install` has two channels and tries the official one first:
|
|
336
|
+
|
|
337
|
+
- Official download (first step of `source: "auto"`): build `https://sw-center.st.com/packs/resource/firmware/stm32cube_fw_<family>_v<version digits>.zip` from the part's db `FwLibrary` (empty for most families, where the family name is used; H7RS / MP13 / WB0 / WL3 have their own), download it, verify `Content-Length` plus the CRC32 of every zip entry, then run CubeMX's `swmgr install <local zip> ask` to land it in `Repository` — this package is tracked by CubeMX itself, visible and removable in the package manager;
|
|
338
|
+
- Three failures are recorded in `notes` before falling back to the GitHub route below: no CubeMX installed, CubeMX GUI already running, and **the first install of a family/version, where CubeMX opens a licence dialog and waits for a human** (headless can only time out; the plugin never clicks it for you). With `source: "official"` this channel is the only one and failure is reported instead;
|
|
339
|
+
|
|
340
|
+
Fallback channel (GitHub assembly):
|
|
298
341
|
|
|
299
342
|
- What it downloads: `stm32f1xx-hal-driver` (HAL driver, BSD-3-Clause) + `cmsis-device-f1` (device headers and startup file, Apache-2.0) + five CMSIS core headers — about 2 MB, a few seconds;
|
|
343
|
+
- Integrity: every archive comes from exactly one source, `codeload.github.com/<repo>/tar.gz/refs/heads/<ref>`, and every archive plus every core header is pinned by sha256 in `src/data/firmware-pins.ts` (regenerate with `scripts/firmware/pin-firmware.mjs`). A hash mismatch rejects the whole package before anything is unpacked; the error reports the expected and actual hashes when upstream master moves.
|
|
300
344
|
- Why the `STM32CubeF1` source archive is not enough: its HAL and CMSIS device directories are **git submodules**, so the tarball ships them empty — unpacking it yields a package that cannot compile (no startup file, no HAL sources);
|
|
301
345
|
- Where it lands: `<CubeMX root>/dsh-firmware/<package>` by default (a plugin-owned folder next to `Repository`, official packages untouched); only if that root is not writable does it fall back to the user cache. **Do not drop self-made version names into `Repository`** — measured: CubeMX does not recognise that version, silently falls back to the package it knows, and reports a successful generation with stale HAL files;
|
|
302
346
|
- How generation picks it up: `stm32_generate` resolves the package named in the `.ioc` (`ProjectManager.FirmwarePackage`), looking in both `Repository` and `<CubeMX root>/dsh-firmware`, and passes `project setCustomFWPath <package dir>` to the CubeMX script — the only mechanism proven to work, and it leaves no absolute path in the `.ioc`;
|
|
303
|
-
- The assembled package matches the official layout: a six-line `package.xml` (version tags `FW.<family>.<x.y.z>`) and `THIRD_PARTY_NOTICES.md
|
|
347
|
+
- The assembled package matches the official layout: a six-line `package.xml` (version tags `FW.<family>.<x.y.z>`) and `THIRD_PARTY_NOTICES.md`; `package.xml` carries no hash manifest (CubeMX does not verify provenance), because integrity is enforced per file by sha256 at download time — measured: generating with `setCustomFWPath` copies HAL sources byte-for-byte out of our directory;
|
|
304
348
|
- But "generation succeeded" proves nothing: with a non-existent package name in the `.ioc`, CubeMX prints no error, exits 0 and simply skips copying HAL. So five checks are mandatory (core headers / HAL Inc / HAL Src / device headers / `startup_*.s`), and the installer runs them right after assembling.
|
|
305
349
|
|
|
350
|
+
### Installer downloads (download only)
|
|
351
|
+
|
|
352
|
+
`stm32_download` separates getting an installer from installing it: the plugin downloads and verifies, you double-click when ready.
|
|
353
|
+
|
|
354
|
+
| Component | Behaviour |
|
|
355
|
+
| --- | --- |
|
|
356
|
+
| `jlink` | Downloads SEGGER 8.18.0 from the official direct link (~59 MB), hashing while it writes and comparing against `63110b6fc55e494d197d6efa156d7f61c0dd0c1f776424995a05407e2d7f566f`; an existing file with the right hash is reused; a failed or mismatched download deletes its temp file |
|
|
357
|
+
| `cubemx` / `cubeprogrammer` | ST requires a myST login and licence acceptance and direct links expire: the default is the official page; `dryRun:false + confirm:true` opens it in the browser. A downloaded `file: "D:/.../installer.exe"` is hashed so you can compare it yourself |
|
|
358
|
+
|
|
359
|
+
`dryRun:true` is the default: plan only, no network. The download root is `%LOCALAPPDATA%\dsh-stm32\downloads`, overridable with `DSH_STM32_DOWNLOADS` or `outDir`. The tool never executes an installer, writes the registry or edits PATH; J-Link's USB driver is installed by choosing all users and allowing UAC in its installer (modern probes use WinUSB; only legacy probes need the old driver).
|
|
360
|
+
|
|
306
361
|
### Environment variables (optional)
|
|
307
362
|
|
|
308
363
|
| Variable | Purpose | Default |
|
|
@@ -313,6 +368,12 @@ Having CubeMX installed does not mean the package for **this particular part** i
|
|
|
313
368
|
| `DSH_STM32_CONFIG` | Point the config file elsewhere (several toolchains / project isolation) | `%USERPROFILE%\.dsh-stm32\config.json` |
|
|
314
369
|
| `DSH_STM32_NO_CONFIG` | Set to `1` / `true` to ignore the config file entirely (environment variables only) | unset = read |
|
|
315
370
|
| `DSH_STM32_CACHE` | Download cache root (register-route template etc.), supports `~` | `%LOCALAPPDATA%\dsh-stm32\cache` |
|
|
371
|
+
| `DSH_STM32_DOWNLOADS` | Installer download root for `stm32_download`, supports `~` | `%LOCALAPPDATA%\dsh-stm32\downloads` |
|
|
372
|
+
| `DSH_STM32_JLINK_URL` | Overrides the J-Link installer URL; **requires `DSH_STM32_JLINK_SHA256`**, otherwise ignored and the official source is used | SEGGER 8.18.0 official link |
|
|
373
|
+
| `DSH_STM32_JLINK_SHA256` | sha256 of the override source (64 hex chars) | official 8.18.0 hash |
|
|
374
|
+
| `MSYS2_INSTALLER_URL` | Override the `stm32_env_install` installer URL (full exe URL); **`MSYS2_INSTALLER_SHA256` is required with it**, or the install is refused | official pinned release `2026-09-27` |
|
|
375
|
+
| `MSYS2_MIRROR` | Override the installer directory (appends `msys2-base-x86_64-20260927.sfx.exe`); a hash is still required | none |
|
|
376
|
+
| `MSYS2_INSTALLER_SHA256` | sha256 for the override source (64 hex chars, optional `sha256:` prefix) | official package hash |
|
|
316
377
|
| `DSH_STM32_E2E_PROJECT` | Project used by hardware e2e runs (with `openocd.cfg` and `build/Debug/*.elf`) | none |
|
|
317
378
|
| `DSH_STM32_E2E_ROOT` | Scratch directory for e2e copies | system temp |
|
|
318
379
|
|
|
@@ -343,7 +404,8 @@ transport select hla_swd
|
|
|
343
404
|
source [find target/stm32f1x.cfg]
|
|
344
405
|
```
|
|
345
406
|
|
|
346
|
-
Without an `openocd.cfg` the plugin
|
|
407
|
+
Without an `openocd.cfg` the plugin **picks the target from the .ioc's `Mcu.Family`** (F1 → `target/stm32f1x.cfg`, F4 → `target/stm32f4x.cfg`, G4 → `target/stm32g4x.cfg`, …; L4 and L4+ share `stm32l4x`).
|
|
408
|
+
C0 / U0 have no official script in openocd 0.12, so the plugin ships adapted copies: scaffolding puts them at `openocd/stm32c0x.cfg` (or `stm32u0x.cfg`) inside the project, `openocd.cfg` uses `source [find openocd/stm32c0x.cfg]` and `launch.json` uses `${workspaceFolder}/openocd/stm32c0x.cfg`. Families with no script at all (H5 / N6 / U3 / WBA / WB0 / WL3 / MP2) are **refused** instead of borrowing another family's script. ST-Link users put the second block into the project root as `openocd.cfg`.
|
|
347
409
|
|
|
348
410
|
### Two hard requirements on the .ioc
|
|
349
411
|
|
|
@@ -355,13 +417,17 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
|
|
|
355
417
|
| Limitation | Detail | Workaround |
|
|
356
418
|
| --- | --- | --- |
|
|
357
419
|
| Only verified on **Windows** | `stm32_generate` depends on `<CubeMX>/STM32CubeMX.exe` + `jre/bin/java.exe`; CubeMX on Linux/macOS is not shaped like that | None yet; flash/debug/register reads may work on Linux with openocd and gdb present, but are untested |
|
|
358
|
-
| **
|
|
359
|
-
|
|
|
420
|
+
| **C0 / U0 target scripts are bundled** | openocd 0.12 ships no `stm32c0x.cfg` / `stm32u0x.cfg`; the plugin bundles adapted copies (only `dap create … -tap` → `-chain-position`) and copies them into the project's `openocd/` when scaffolding | Verified that openocd 0.12 loads the script completely (only the probe is missing); **no real C0/U0 board has been flashed yet** |
|
|
421
|
+
| Deeper capabilities are graded per family | The family profile covers 27 families (`src/data/family.ts`): pin names, SWD debug signals, EXTI vector grouping, openocd target and breakpoint budget all follow the family and its core; HAL scaffolding covers 21 single-core families and the register route 21 families (all verified through create→build; per-family results for the 8 new ones are in development-notes §87.5). **.ioc peripheral presets** are derived from the CubeMX db (`src/data/db-presets.ts`: serial / TIM PWM / ADC; the hand-written table is down to what db cannot express, plus an offline fallback). **Clock planning** is db-derived too (`src/data/clock-db.ts`): pllmul families F1/F0/L0 and pllmn families F4/F7/G4/L4 round-trip, PLL1 families H5/U5/WBA/L4+ are wired in — 18 families in total. Still F1-only: **SVD validation** (the bundled resources only ship `device/f1/svd`) | Uncovered capabilities are refused with a reason (the profile's `capabilities` are false, or the exact blocker is reported) — nothing is silently done with F1 tables. Dual-core WB, MP1/MP2/N6 and WB0/WL3 are out of HAL scaffolding scope |
|
|
422
|
+
| The probe is picked from what USB actually shows | ST-Link → `interface/stlink-dap.cfg` (dapdirect), DAPLink/CMSIS-DAP → `interface/cmsis-dap.cfg`, J-Link → `interface/jlink.cfg` + `transport select swd`; a project `openocd.cfg` overrides all of it | Swap probes without editing config; pin one by writing `openocd.cfg` |
|
|
360
423
|
| 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` |
|
|
361
424
|
| Generation/scaffolding needs **CubeMX + the F1 firmware package** | Package version defaults to `STM32Cube_FW_F1_V1.8.7` | Pass another version via `firmwarePackage` |
|
|
362
425
|
| 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
426
|
| **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
|
-
|
|
|
427
|
+
| **Serial P1 is Windows-only** | `stm32_serial`'s bridge is PowerShell 5.1 + `System.IO.Ports` (the plugin has zero npm dependencies); Linux / macOS get `unsupported-platform`. P1 has no serial panel in the UI, no SSE streaming, no auto-reconnect, and one port at a time | use a system serial terminal, or wait for the UI / cross-platform work |
|
|
428
|
+
| **Serial success path has no real-hardware evidence** | The real bridge was only exercised on the failure path (`COM99` → `port-not-found`); `state=open`, actual received bytes, real DTR/RTS levels, the 5 s parent watchdog and idle auto-release have no hardware runs (the fake bridge covers the same contract) | plug in a board and run `list` → `open` → `read` → `close`; see development-notes §86 |
|
|
429
|
+
| **The 8 new register families passed independent acceptance** | 0.1.5 grows the register route from 13 to 21 families (+ H5 / H7 / L4+ / L5 / U3 / U5 / WBA / WL): all eight pass create→build with warning 0 / error 0 (per-family FLASH/RAM in development-notes §87.5); H7's per-family `-mcpu` and the missing `cachel1_armv7.h` were fixed in the template | independent acceptance (t8) passed: 21-family inventory, GPIO gates, linkerRam, 296 fact assertions, all eight rebuilt at exit 0 (development-notes §87.6); try the new eight with the parts listed in §87.5 |
|
|
430
|
+
| Register **symbol names and bit-field decoding need the bundled SVD (`full` logical tier)** | `GPIOC.ODR` / `GPIOC->ODR` and peripheral dumps (a bare `GPIOC`) are resolved from `assets/device/f1/svd/<line>.json`, derived from ST's SVDs (ST EULA, 1.71 MiB); 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 a hint to reinstall the plugin (the `full` tier ships in the package) | use `0x…` addresses; or run `stm32_assets verify` to check the install |
|
|
365
431
|
|
|
366
432
|
## Troubleshooting
|
|
367
433
|
|
|
@@ -373,8 +439,8 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
|
|
|
373
439
|
| 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` |
|
|
374
440
|
| 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 |
|
|
375
441
|
| 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 …
|
|
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 `
|
|
442
|
+
| The first project build answers "device facts are not ready …" | The chip table ships inside the package (`assets/device/f1/chips.json`), so a normal install never hits this. It means the plugin install is incomplete: run `stm32_assets verify` to list missing files, then reinstall the plugin (offline is fine); `DSH_STM32_ASSETS` is only a development override |
|
|
443
|
+
| `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_doctor` 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 |
|
|
378
444
|
| `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 |
|
|
379
445
|
| 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` |
|
|
380
446
|
| Generate got faster but the CubeMX GUI no longer lists expansion packs | With `thirdpartyPacks: "auto"` the `thirdparties/pdsc` directory is parked as `pdsc.dsh-parked` when no pack is needed and restored after the run. Pass `thirdpartyPacks: "keep"` while picking packs by hand in the CubeMX GUI |
|
|
@@ -385,25 +451,26 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
|
|
|
385
451
|
|
|
386
452
|
```powershell
|
|
387
453
|
npm run build # tsc -> lib/ (lib/ is committed: rebuild before you commit)
|
|
388
|
-
npm test #
|
|
454
|
+
npm test # 60 offline suites, 947 cases; no board, CubeMX, or toolchain needed
|
|
389
455
|
npm run test:pack # pack a tarball, unpack it, scaffold a real register project from the unpacked lib
|
|
390
|
-
npm run test:size # package guard: tarball <=
|
|
456
|
+
npm run test:size # package guard: tarball <=3.9 MB, runtime assets under templates/ (.ioc/.xml/.ld/.json/.cfg) <=40 KB, no binaries/diagrams inside
|
|
391
457
|
```
|
|
392
458
|
|
|
393
459
|
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).
|
|
394
460
|
|
|
395
|
-
A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that need the real firmware package are skipped: CI
|
|
461
|
+
A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that need the real firmware package are skipped: CI skips those two; a developer machine runs all **947 pass / 0 fail**. 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.
|
|
396
462
|
|
|
397
463
|
### What ships where (decide before you add a file)
|
|
398
464
|
|
|
399
465
|
| Where | What | Size |
|
|
400
466
|
| --- | --- | --- |
|
|
401
|
-
| npm tarball | `lib/**` (including `lib/client.js`), `client/client.js`, `templates/scaffold/**`, `cordis.patch.yml`, both READMEs, `LICENSE`, `docs/*.md` |
|
|
467
|
+
| npm tarball | `lib/**` (including `lib/client.js`), `client/client.js`, `templates/scaffold/**`, `assets/**`, `cordis.patch.yml`, both READMEs, `LICENSE`, `docs/*.md` | 272 files / 1825.2 KB packed, 15181.3 KB unpacked; `assets/**` is 12.5 MB of source (headers compress well) |
|
|
402
468
|
| 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` |
|
|
403
|
-
|
|
|
469
|
+
| Bundled (npm package) | Device-facts layer (21 families of `device/<family>/chips.json`), `.ioc` templates, `.ld`, SVD, startup files and headers — 75 files for `core`, 105 for `full`, shipped offline | inspect and verify with `stm32_assets list/verify`; `prune` only removes historical external versions |
|
|
470
|
+
| 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 cache with `stm32_cache list/verify/purge` |
|
|
404
471
|
| Rendered on the spot | `.ioc` content (`renderIoc`), `.ld` MEMORY (`renderLinkerScript`), the cmake source list | rendered per part, never stored as a template |
|
|
405
472
|
|
|
406
|
-
The guard is `scripts/pack-size.mjs` (`npm run test:size`): tarball ≤
|
|
473
|
+
The guard is `scripts/pack-size.mjs` (`npm run test:size`): tarball ≤ 4 MB (4 000 000 B; 1.82 MB measured with `assets/**` bundled), the runtime assets under `templates/**` (`.ioc/.xml/.ld/.json/.cfg/.svd/.csv`) ≤ 40 KB with a 24 KB per-file cap (Markdown docs and C/CMake sources are not assets), 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` / `assets/manifest.json` / `assets/device/f1/chips.json` all present.
|
|
407
474
|
|
|
408
475
|
Hardware e2e writes to the board and needs a project you point it at:
|
|
409
476
|
|
|
@@ -419,13 +486,13 @@ See the [development notes](docs/development-notes.md) for the suite breakdown a
|
|
|
419
486
|
```text
|
|
420
487
|
src/
|
|
421
488
|
index.ts plugin entry (name / inject / apply)
|
|
422
|
-
tools/ the
|
|
489
|
+
tools/ the 25 registered tools, L3 (24 files: parameter schema + output contract + rendering)
|
|
423
490
|
engine/ pure logic and workflows (generate / build / flash / debug / ioc / scaffold …)
|
|
424
491
|
commands/register.ts the 7 slash commands
|
|
425
492
|
skill/stm32-workflow.ts the SKILL shipped with the plugin
|
|
426
493
|
data/ paths and chip data (paths are data, not logic)
|
|
427
494
|
templates/scaffold/ project template snapshot (CMake / .ld / .vscode / .ioc)
|
|
428
|
-
test/ offline suites (
|
|
495
|
+
test/ offline suites (60, registered in run-units) + fixtures + hardware e2e
|
|
429
496
|
scripts/ guards and generators (pack-size / pack-smoke / gen-xcube-catalog / copy-client)
|
|
430
497
|
docs/ specification + development notes + reading guide + diagrams/ (not packed)
|
|
431
498
|
```
|
|
@@ -435,6 +502,7 @@ docs/ specification + development notes + reading guide + d
|
|
|
435
502
|
- [Specification](docs/dsh-stm32-plugin-规格.md): tool contracts, state machine, acceptance criteria A1–A13
|
|
436
503
|
- [Development notes](docs/development-notes.md): milestones, host-contract pitfalls, implementation details and measured numbers
|
|
437
504
|
- [Source reading guide](docs/reading-guide.md): layered reading order, per-file responsibilities and exports, 14 flow diagrams, 23 invariants
|
|
505
|
+
- [Release notes 0.1.5](docs/release-notes/v0.1.5.md): serial P1, the 21-family register route, installer downloads and P0/P1/P2 hardening (0.1.4 and earlier live in git history)
|
|
438
506
|
- Visuals: [architecture](docs/diagrams/dsh-stm32-architecture.html) / [main journey](docs/diagrams/dsh-stm32-journey.html) — single-file HTML, opens offline, exports PNG/SVG
|
|
439
507
|
|
|
440
508
|
## License
|
package/assets/README.md
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# STM32 内置资源(assets/)
|
|
2
|
+
|
|
3
|
+
这是 [`dsh-stm32`](../) 插件的**内置资源目录**,随 npm 包一起分发。2026-11 起它从独立仓库
|
|
4
|
+
`dsh-stm32-assets` 并入插件仓库:不再有第二个仓库,也不再需要联网 `refresh`,装好插件即离线可用。
|
|
5
|
+
|
|
6
|
+
运行时按 **flat 布局**读:`assets/manifest.json` 与 `device/`、`ioc/` 等同层。
|
|
7
|
+
`lib/engine/assets.js` 从包根解析 `assets/`;`DSH_STM32_ASSETS` 仍可指向外部目录(开发与测试用),
|
|
8
|
+
外部目录既可以也是 flat,也可以保留旧的 `<版本>/install.json` 多版本布局。
|
|
9
|
+
|
|
10
|
+
## 目录
|
|
11
|
+
|
|
12
|
+
| 路径 | 内容 | 数量 |
|
|
13
|
+
| --- | --- | --- |
|
|
14
|
+
| `device/<族>/chips.json` | 设备事实:CPN、启动文件、设备宏、Flash/RAM、引脚数等 | 21 族 |
|
|
15
|
+
| `device/f1/svd/<line>.json` | F1 六条产品线的外设 → 寄存器 → 位域 | 6 |
|
|
16
|
+
| `ioc/family/<FAM>.ioc` | 每族一份 CubeMX 认证过的最小工程模板 | 20 |
|
|
17
|
+
| `ioc/minimal/` | F1 每条产品线各容量档的最小 .ioc | 14 |
|
|
18
|
+
| `ld/f1/` | F1 每个容量档一份 `<DeviceId>_FLASH.ld` | 14 |
|
|
19
|
+
| `startup/f1/` | F1 gcc 启动文件(离线兜底) | 14 |
|
|
20
|
+
| `headers/f1/` | F1 CMSIS 设备头 + `stm32f1xx.h` + `system_stm32f1xx.h` | 16 |
|
|
21
|
+
| `templates/family/` | 生成 `ioc/family/` 的源模板(不在 manifest 里) | 21 |
|
|
22
|
+
| `manifest.json` | 资产清单 v2:版本、profiles、逐文件 sha256 | — |
|
|
23
|
+
| `VERSION` | 资产版本号 `YYYY.MM.DD-N` | — |
|
|
24
|
+
|
|
25
|
+
`manifest.json` 的 profile 是**逻辑分层**,不是安装开关(包内文件始终齐全):
|
|
26
|
+
|
|
27
|
+
- **core = 建工程必需**(75 个文件):`device/**`、`ioc/**`、`ld/**`。
|
|
28
|
+
- **full = core 再加**(105 个文件):`startup/**`、`headers/**`。
|
|
29
|
+
|
|
30
|
+
SVD 只在 `full` 逻辑层里;寄存器符号名/位域解析需要它,纯地址读不需要。
|
|
31
|
+
|
|
32
|
+
## 生成物,不要手改
|
|
33
|
+
|
|
34
|
+
这些文件全部由 `scripts/assets/` 下的脚本生成。手改会在下一次 `--check` 时暴露为哈希不一致。
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
# 校验现有资产与 manifest 是否一致(不写盘)
|
|
38
|
+
node scripts/assets/build-assets.mjs --check
|
|
39
|
+
|
|
40
|
+
# 全量重建(需要本机 CubeMX db 与 STM32Cube 固件包)
|
|
41
|
+
node scripts/assets/build-assets.mjs
|
|
42
|
+
|
|
43
|
+
# 只重建指定族 / 指定 SVD
|
|
44
|
+
node scripts/assets/build-assets.mjs --families C0,F4
|
|
45
|
+
node scripts/assets/build-assets.mjs --svd path/to/STM32F103.svd --svd-dir path/to/svd-dir
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
常用参数:`--plugin <dir>`(插件根,默认自动推断)、`--cube-mx <dir>`、`--firmware <dir>`、
|
|
49
|
+
`--family-templates <dir>`、`--check`、`--help`。生成脚本:
|
|
50
|
+
|
|
51
|
+
- `build-assets.mjs`:总入口,写 `manifest.json` / `VERSION` 与 F1 资产;
|
|
52
|
+
- `family-assets.mjs`:从 CubeMX db 与固件包生成 `device/<族>/chips.json` 与 `ioc/family/<FAM>.ioc`;
|
|
53
|
+
- `svd-f1.mjs`:SVD XML → `device/f1/svd/<line>.json`。
|
|
54
|
+
|
|
55
|
+
数据来源与降级:芯片事实只从本机 CubeMX `db/mcu` 的 XML 与固件包算,**不手写事实表**;
|
|
56
|
+
缺 CubeMX / 固件包 / SVD 时宁可构建失败,也不产出半份资产。SVD 只保留编译后的寄存器与位域事实,
|
|
57
|
+
不复制 ST 的说明文字(原始 SVD 受 ST EULA 约束,不能随插件分发)。
|
|
58
|
+
|
|
59
|
+
## manifest.json(v2)
|
|
60
|
+
|
|
61
|
+
```jsonc
|
|
62
|
+
{
|
|
63
|
+
"name": "dsh-stm32-assets",
|
|
64
|
+
"version": "2026.11.04-2", // = VERSION
|
|
65
|
+
"schema": 2,
|
|
66
|
+
"generatedBy": "scripts/assets/build-assets.mjs",
|
|
67
|
+
"profiles": {
|
|
68
|
+
"core": ["device/**", "ioc/**", "ld/**"],
|
|
69
|
+
"full": ["device/**", "ioc/**", "ld/**", "startup/**", "headers/**"]
|
|
70
|
+
},
|
|
71
|
+
"files": [
|
|
72
|
+
{ "path": "device/f1/chips.json", "bytes": 0, "sha256": "…", "source": "…", "profile": "core" }
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
运行时用 `stm32_assets` 的 `list` / `verify` 查看与逐文件校验;`prune` 只清理
|
|
78
|
+
`DSH_STM32_ASSETS` 下遗留的历史版本目录,**不会删除包内资源**。
|
|
79
|
+
|
|
80
|
+
## 许可与来源
|
|
81
|
+
|
|
82
|
+
- 设备头、启动文件、链接脚本来自 STM32Cube 固件包(ST 许可,随插件作为工程模板的一部分使用)。
|
|
83
|
+
- `device/**/chips.json`、`ioc/**`、`ld/**`、`device/f1/svd/**` 是从 CubeMX db、固件包与 CMSIS-SVD
|
|
84
|
+
推导出的**事实数据**,由本仓库脚本生成;生成脚本与产物一起入库,便于追溯。
|
|
85
|
+
- 架构图在插件 `docs/diagrams/`,不属于本目录。
|
package/assets/VERSION
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
2026.11.04-2
|