dsh-stm32 0.1.6 → 0.1.8

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.
Files changed (125) hide show
  1. package/README.md +410 -517
  2. package/README_EN.md +410 -510
  3. package/client/client.js +4363 -24
  4. package/docs/reading-guide.md +62 -0
  5. package/lib/client.js +4363 -24
  6. package/lib/commands/register.js +5 -5
  7. package/lib/data/chips.js +4 -4
  8. package/lib/data/clock-db.js +24 -24
  9. package/lib/data/clock-f1.js +2 -2
  10. package/lib/data/cmsis-sources.js +6 -6
  11. package/lib/data/db-presets.js +4 -4
  12. package/lib/data/device-facts.js +6 -6
  13. package/lib/data/family.js +16 -16
  14. package/lib/data/firmware-packages.js +10 -10
  15. package/lib/data/install-guides.js +18 -18
  16. package/lib/data/ioc-presets.js +3 -3
  17. package/lib/data/ioc-schema.js +32 -32
  18. package/lib/data/rm-topics.js +6 -6
  19. package/lib/data/search-roots.js +62 -16
  20. package/lib/data/serial-config.js +7 -7
  21. package/lib/data/stm32f1.js +1 -1
  22. package/lib/data/svd.js +7 -7
  23. package/lib/data/toolchain-config.js +3 -3
  24. package/lib/engine/artifacts.js +123 -0
  25. package/lib/engine/assets.js +5 -5
  26. package/lib/engine/breakpoint-hits.js +73 -0
  27. package/lib/engine/breakpoints.js +5 -5
  28. package/lib/engine/build.js +73 -3
  29. package/lib/engine/cache.js +4 -4
  30. package/lib/engine/channel-tap.js +227 -0
  31. package/lib/engine/channels.js +48 -0
  32. package/lib/engine/clock-derived.js +2 -2
  33. package/lib/engine/clock-direct.js +3 -3
  34. package/lib/engine/clock-plan.js +7 -7
  35. package/lib/engine/clock-pllmn.js +6 -6
  36. package/lib/engine/clocks.js +192 -0
  37. package/lib/engine/cmake-sources.js +9 -9
  38. package/lib/engine/code-patch.js +5 -5
  39. package/lib/engine/cube-mx-guard.js +3 -3
  40. package/lib/engine/cube-programmer.js +4 -4
  41. package/lib/engine/cubemx-db.js +7 -7
  42. package/lib/engine/debug-session.js +58 -13
  43. package/lib/engine/debug.js +3 -3
  44. package/lib/engine/doctor.js +12 -12
  45. package/lib/engine/download.js +1 -1
  46. package/lib/engine/event-bus.js +158 -0
  47. package/lib/engine/event-log.js +335 -0
  48. package/lib/engine/facts-acquire.js +3 -3
  49. package/lib/engine/fault-hints.js +146 -0
  50. package/lib/engine/fetch.js +2 -2
  51. package/lib/engine/firmware-install.js +16 -16
  52. package/lib/engine/firmware-official.js +8 -8
  53. package/lib/engine/flash.js +22 -22
  54. package/lib/engine/fs-longpath.js +1 -1
  55. package/lib/engine/gdb-mi.js +7 -7
  56. package/lib/engine/generate-script.js +2 -2
  57. package/lib/engine/generate.js +17 -17
  58. package/lib/engine/hal-chip.js +7 -7
  59. package/lib/engine/interrupts.js +247 -0
  60. package/lib/engine/ioc-diff.js +369 -0
  61. package/lib/engine/ioc-plan.js +52 -52
  62. package/lib/engine/ioc-rules.js +9 -9
  63. package/lib/engine/ioc-sync.js +58 -0
  64. package/lib/engine/ioc-verify.js +34 -34
  65. package/lib/engine/msys2-install.js +81 -56
  66. package/lib/engine/panel-actions.js +103 -0
  67. package/lib/engine/pinout.js +140 -0
  68. package/lib/engine/probe-error.js +8 -8
  69. package/lib/engine/probe-info.js +95 -0
  70. package/lib/engine/probe-session.js +3 -3
  71. package/lib/engine/probe.js +47 -50
  72. package/lib/engine/progress.js +99 -0
  73. package/lib/engine/project-conf.js +199 -0
  74. package/lib/engine/project-export.js +1 -1
  75. package/lib/engine/register-clock.js +5 -5
  76. package/lib/engine/register-gpio.js +3 -3
  77. package/lib/engine/register-linker.js +7 -7
  78. package/lib/engine/register-template.js +22 -22
  79. package/lib/engine/regs.js +3 -3
  80. package/lib/engine/rm-extract.js +2 -2
  81. package/lib/engine/rm-sources.js +1 -1
  82. package/lib/engine/route-plan.js +9 -9
  83. package/lib/engine/rtt.js +18 -18
  84. package/lib/engine/scaffold.js +22 -22
  85. package/lib/engine/serial.js +24 -24
  86. package/lib/engine/session-context.js +19 -0
  87. package/lib/engine/source-slice.js +59 -0
  88. package/lib/engine/tar.js +1 -1
  89. package/lib/engine/text-file.js +1 -1
  90. package/lib/engine/thirdparty.js +3 -3
  91. package/lib/engine/tool-env.js +2 -2
  92. package/lib/engine/tool-events.js +119 -0
  93. package/lib/engine/toolchain-gate.js +8 -8
  94. package/lib/engine/usercode-merge.js +2 -2
  95. package/lib/engine/vscode-config.js +2 -2
  96. package/lib/engine/watch-admin.js +101 -0
  97. package/lib/engine/watch-record.js +39 -0
  98. package/lib/engine/watch-recorder.js +116 -0
  99. package/lib/engine/web-api.js +887 -5
  100. package/lib/engine/web-routes.js +18 -1
  101. package/lib/engine/workspace-memo.js +41 -0
  102. package/lib/engine/xcube-catalog.js +1 -1
  103. package/lib/index.js +72 -29
  104. package/lib/skill/stm32-workflow.js +1 -1
  105. package/lib/tools/assets.js +1 -1
  106. package/lib/tools/cache.js +2 -2
  107. package/lib/tools/debug-session.js +5 -5
  108. package/lib/tools/doctor.js +2 -2
  109. package/lib/tools/download.js +1 -1
  110. package/lib/tools/env-install.js +3 -3
  111. package/lib/tools/firmware-install.js +5 -5
  112. package/lib/tools/flash.js +8 -8
  113. package/lib/tools/generate.js +1 -1
  114. package/lib/tools/ioc-apply.js +10 -1
  115. package/lib/tools/ioc-plan.js +1 -1
  116. package/lib/tools/ioc-verify.js +11 -11
  117. package/lib/tools/project-create.js +32 -4
  118. package/lib/tools/project-dir.js +8 -2
  119. package/lib/tools/regs.js +10 -10
  120. package/lib/tools/route-plan.js +9 -9
  121. package/lib/tools/rtt.js +17 -9
  122. package/lib/tools/serial.js +30 -8
  123. package/lib/tools/watch.js +24 -2
  124. package/package.json +70 -70
  125. package/templates/scaffold/RTT.md +26 -34
package/README_EN.md CHANGED
@@ -1,510 +1,410 @@
1
- # dsh-stm32
2
-
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
-
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
-
7
- [![GitHub stars](https://img.shields.io/github/stars/JingYu-er/dsh-stm32?color=4a6cf7)](https://github.com/JingYu-er/dsh-stm32)
8
- [![license](https://img.shields.io/github/license/JingYu-er/dsh-stm32)](LICENSE)
9
- [![platform](https://img.shields.io/badge/platform-Windows%2010%2F11-4a6cf7)](#known-limitations)
10
- [![MCU](https://img.shields.io/badge/MCU-STM32%20family-4a6cf7)](#known-limitations)
11
- [![version](https://img.shields.io/badge/version-0.1.6-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
12
-
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
-
15
- ## Why you need it
16
-
17
- Most "let the model write STM32 code" setups stop at the source file: you get a `main.c`, and whether it compiles, whether the LED actually blinks after flashing, is still your job — open CubeMX, switch to a terminal, press F5. **The model never sees the board, so it cannot be responsible for its own code.**
18
-
19
- This plugin wires the hardware side into DSH as well: the `.ioc` can be read and edited (as a transaction, with rollback), code can only land inside `USER CODE` blocks, generation and builds return real error lines, flashing is an independent path that **never goes through a debugger**, and after flashing the model can read the state back out of the registers. Every step returns structured evidence — `planId`, `file:line:col`, `Verified OK`, bit13 of `GPIOC.ODR` (the report says `ODR13=1` when SVD data is installed) — so the next step is decided from evidence instead of guesswork.
20
-
21
- That is what "hardware programming inside DSH" means here: **the model does not just write code — it puts that code on the board, then reads the board's state back out of the registers and reconciles it with what it expected.**
22
-
23
- | Stage | Before (hand-written + CubeMX GUI) | Now (end-to-end in DSH) |
24
- | --- | --- | --- |
25
- | Create the project | Click through the clock tree, pins and project settings in the GUI, generate CMake, then hand-write `launch.json` | One sentence: `stm32_project_create` produces a templated project in 2 s (byte-identical to the GUI output), both `.vscode` debug configs already in place |
26
- | Change the configuration | Edit in the GUI, regenerate, pray that USER CODE survives | `stm32_ioc_plan` shows the diff first (source untouched) → you approve → `stm32_ioc_apply` writes with SHA verification, backup and rollback on failure |
27
- | Write code | Edit the whole file, accidentally touch a generated region, lose it on the next generate | `stm32_code_patch` writes only inside `USER CODE` blocks; everything outside stays byte-for-byte |
28
- | Build | Build in Keil, or hand-write the CMake files for the VS Code extension | DSH builds automatically via `/stm32-build [dir] [--clean]` |
29
- | Flash | Flash in Keil, or maintain a `tasks.json` that calls openocd | DSH flashes automatically via `/stm32-debug [dir]` |
30
- | Verify | Set a breakpoint and read the register values yourself | After flashing, `stm32_regs_read` reads the state back: `GPIOC.ODR` twice to see the counter grow (with the SVD data it also prints `ODR5=1`), `AFIO.MAPR` to confirm the firmware did not disable SWD |
31
- | Debug | `F5`, set breakpoints by hand, remember to close the session | `stm32_debug_run` halts at `main`, captures one snapshot and releases the probe; use `stm32_debug_session` only for continuous debugging, it closes itself when idle |
32
-
33
-
34
- ## Install
35
-
36
- ### Prerequisites
37
-
38
- | Dependency | Purpose | If missing |
39
- | --- | --- | --- |
40
- | dsh (able to load bundle layers) | Host | The plugin is never loaded |
41
- | Node ≥ 20 | Build / test | `npm run build` fails |
42
- | `arm-none-eabi-gcc`, `arm-none-eabi-gdb` (or `gdb-multiarch`) | Build / debug | `stm32_doctor` tells you which one is missing and where to get it |
43
- | `openocd` | Flash / debug | Flashing and debugging unavailable; read-only tools still work |
44
- | `cmake` + `ninja` | Build | `stm32_build` fails |
45
- | STM32CubeMX (with its bundled JRE) | `stm32_generate`, `stm32_project_create` | Generation tools unavailable, everything else still works |
46
- | STM32Cube firmware package F1 (installed with CubeMX) | Drivers copied when scaffolding | "Firmware package not found" |
47
-
48
- Paths are searched as MSYS2 (`C:/msys64/ucrt64/bin`, `C:/msys64/mingw64/bin`) → ST official packages, with CubeMX at `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` by default; installs elsewhere are found by auto-discovery, and environment variables override everything (see [Configuration](#configuration)).
49
-
50
- ### Install (recommended: one command)
51
-
52
- ```powershell
53
- dsh plugin --profile desktop add dsh-stm32
54
- ```
55
-
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
-
58
- Verify with `dsh plugin --profile desktop why dsh-stm32` (should print `0.1.6`); after a restart `/stm32-doctor` should respond.
59
-
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
-
62
-
63
- **Uninstall**: `dsh plugin --profile desktop remove dsh-stm32`, then restart dsh.
64
-
65
- ### Install from source (when you want to change code)
66
-
67
- ```powershell
68
- git clone https://github.com/JingYu-er/dsh-stm32.git
69
- cd dsh-stm32
70
- npm install --no-audit --no-fund # typescript only
71
- npm run build # tsc -> lib/ (required before committing)
72
- npm test # optional: 947 offline cases in 60 suites, no board needed
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 <=3.9 MB, runtime assets under templates/ (.ioc/.xml/.ld/.json/.cfg) <=40 KB, no binaries/diagrams inside
75
- ```
76
-
77
- Link it into your dsh profile — **while editing code use `link:`, never `file:`**:
78
-
79
- ```powershell
80
- cd "$env:USERPROFILE\.dsh\profiles\desktop"
81
- pnpm add "link:D:\path\to\dsh-stm32"
82
-
83
- # then append "dsh-stm32" to dsh.profile.bundles in that directory's package.json
84
- # finally restart dsh (bundle layers only load at process start)
85
- ```
86
-
87
- > **Why `link:` while editing**: with `nodeLinker: hoisted`, pnpm copies a `file:` dependency into a real directory, so the `lib/` you rebuild with `tsc` is never read by the host — the symptom is "I fixed it, restarted, still the old behaviour". With `link:` the host reads `lib/` live, but you **still have to restart dsh** to reload the plugin. A `github:` or npm install is a copy, so re-build and reinstall after changing code.
88
-
89
- ## Quick start: a minimal end-to-end check (empty directory to a blinking LED)
90
-
91
- This chain ran on a real board (acceptance A1, 2026-10-22), driven entirely by tool calls from the model. Note that it is a **minimal check** — every step uses the same tools a real project uses, and the blinking LED is simply the cheapest sample:
92
-
93
- | Step | What happens | Tool | Measured |
94
- | --- | --- | --- | --- |
95
- | 1 | Health check: toolchain, busy probes, ports, `.elf`, `.ioc` warnings | `stm32_doctor` | ~2 s |
96
- | 2 | Empty directory → CMake project skeleton (14 template files + 629 firmware files + an `.ioc` with SWD configured) | `stm32_project_create` | ~2 s |
97
- | 3 | Headless CubeMX run driven by the `.ioc`, output placed under `Core/` | `stm32_generate` | 130–175 s the first time; later runs are **skipped outright** (<1 s) while the `.ioc` and outputs are unchanged |
98
- | 4 | Build (first run configures with `cmake --preset`) | `stm32_build` | ~5 s configure + 3 s build |
99
- | 5 | **Flash only**: program + verify + reset | `stm32_flash` | 2.1–2.6 s |
100
- | 6 | Read `GPIOC.ODR` (or the address `0x4001100C`) back to confirm the state really toggles | `stm32_regs_read` | 0.4–1.3 s |
101
-
102
- > Step 6 uses the symbol form (`GPIOC.ODR`), which needs the SVD tables 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
-
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
-
106
- ```text
107
- /stm32-doctor # health check before you start
108
- /stm32-env # what each capability is missing (works even when incomplete)
109
- /stm32-build # build, print memory usage and errors
110
- /stm32-flash # flash only, no debug session
111
- /stm32-debug # flash + halt at main
112
- /stm32-stop # close the debug session, hand the probe back to VS Code
113
- /stm32-setup # health check + install plan (the word "install" in the command actually installs)
114
- ```
115
-
116
- ### This is a minimal check, not the ceiling
117
-
118
- The blinking LED is the **smallest smoke test** for this chain: it walks create → generate → build → flash → read the state back once, and every step uses a general-purpose tool — nothing in it is LED-specific. A real project follows the same chain; what changes is that the `.ioc` enables more peripherals, there are more `USER CODE` blocks, and the code is longer:
119
-
120
- | What a real project needs | Which path it takes | Verified on hardware |
121
- | --- | --- | --- |
122
- | Peripheral setup: GPIO / timers / USART / I2C / SPI / ADC / DMA / interrupts | `stm32_ioc_plan` edits the `.ioc` (GPIO validated against the chip pin table, peripherals written as `Mcu.IP*` / `Periph.*` keys) → `stm32_ioc_apply` → `stm32_generate` | GPIO, clocks and SWD verified; other peripherals use the same mechanism but were not tested one by one |
123
- | HAL sources for a newly enabled peripheral | Add `stm32f1xx_hal_<peripheral>.c` to `STM32_Drivers_Src` in `cmake/stm32cubemx/CMakeLists.txt`, or add it in `cmake/user/CMakeLists.txt` | **Manual step**: the plugin only relocates `Src/` and `Inc/`; the `cmake/**` files CubeMX emits are not applied |
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
- | 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
- | 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 bundled SVDs with a fake probe, **hardware re-test pending** (development notes §31.11) |
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
-
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
-
132
- ## Features
133
-
134
- | Capability | How it is provided |
135
- | --- | --- |
136
- | Environment health check | `stm32_doctor` (read-only), `stm32_doctor` (toolchain + busy probes + ports + project warnings) |
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
- | 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 |
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) |
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 |
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) |
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 |
144
- | `.ioc` as a transaction | `stm32_ioc_inspect` (read-only parse) → `stm32_ioc_plan` (diff, no writes) → `stm32_ioc_apply` (SHA check + backup + rollback) |
145
- | USER CODE only | `stm32_code_patch`: writes only between `/* USER CODE BEGIN X */` and `END X`; everything else untouched |
146
- | Code generation | `stm32_generate`: headless CubeMX + ST project layout + USER CODE carried over by label |
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 |
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) |
149
- | Debug | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
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 |
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)) |
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) |
155
-
156
- ## Tool reference
157
-
158
- ### Environment and project
159
-
160
- | Tool | What it does |
161
- | --- | --- |
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 |
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 |
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 |
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` |
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 |
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 |
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) |
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 |
172
-
173
- ### .ioc: read-only and transactions
174
-
175
- | Tool | What it does |
176
- | --- | --- |
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`" |
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` |
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` |
181
-
182
- ### Code and build
183
-
184
- | Tool | What it does |
185
- | --- | --- |
186
- | `stm32_code_patch` | replace/append inside `USER CODE` blocks only; bytes outside (including CRLF) are preserved; backs up first, then writes a temp file and renames it. A wrong label lists every available label in the file |
187
- | `stm32_generate` | Runs `java -jar STM32CubeMX.exe -q` headless, then places output under `Core/Src` and `Core/Inc`, carrying USER CODE from the old files by label. Background job by default. **When the `.ioc`, the CubeMX build and every output hash are unchanged it reuses the previous result** (`skipped: true`, ~1 s; pass `skipIfUnchanged: false` or delete `.dsh-stm32/generate-cache.json` to force a rerun). Projects that use no X-CUBE pack (`Mcu.ThirdPartyNb=0`) have `~/.stm32cubemx/thirdparties/pdsc` parked for the run and restored afterwards, saving ~25 s; pass `thirdpartyPacks: "keep"` to keep the index. **The need for the index is not guessed from keywords**: `Mcu.ThirdParty0=STMicroelectronics.X-CUBE-ALGOBUILD.1.4.0` in the `.ioc` is matched by name against a built-in pack catalog (67 packs, generated by `scripts/gen-xcube-catalog.mjs`), and a pack this machine lacks is reported in the notes up front |
188
- | `stm32_build` | `cmake --build`, with the build directory inferred from `CMakePresets.json` and `build/*/CMakeCache.txt`; configures on first build; rejects the "CMakeCache directory mismatch but ninja exits 0" false success. With `artifacts: ["hex","bin"]` it converts the `.elf` afterwards via `arm-none-eabi-objcopy`; a failed conversion is only a note, not a build failure |
189
-
190
- ### Flash and debug
191
-
192
- | Tool | What it does |
193
- | --- | --- |
194
- | `stm32_flash` | **Flash**: openocd `program verify reset exit`, no debug session, no halt at `main`. Reads the `.ioc` first and refuses when the debug port is disabled (see [Design notes](#design-notes)). Failures carry a structured `probeError`: `kind` (`no-probe` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `timeout` / `unknown`, 8 in total), `cause` (one-line root cause), `hint` (an actionable next step, a dedicated one per kind), `evidence` (the raw log lines) and `retryable` (whether retrying after following the hint makes sense); on success the field is absent entirely. When no device is found the USB shape (no USB on this machine / probe unplugged / driver problem) is added to the notes |
195
- | `stm32_debug_run` | Starts openocd + gdb, `break main` → `continue` → captures pc/sp/lr/bt/locals → `reset run` + `detach`; no Flash write, nothing left running. Hardware breakpoints / watchpoints above the chip limit (F1: 6 / 4) fail **before** openocd is started, so the probe is never touched |
196
- | `stm32_debug_session` | Long-lived openocd session (`.elf` resolved automatically), closed after 90 s idle, hard limit 10 min |
197
- | `stm32_debug_eval` | Runs gdb commands or reads expressions (e.g. `g_led_blink_count`) inside the session, then `resume` + `detach` immediately |
198
- | `stm32_debug_stop` | Releases the probe immediately, idempotent |
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 |
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 |
202
-
203
- ### Adding RTT to the firmware (shortest example)
204
-
205
- A register-level project (`route: "register"`) already ships `Core/Src/rtt.c` and `Core/Inc/rtt.h`, but **they are off by default**: with nobody referencing them, `--gc-sections` drops the code and the 3 KB ring buffers (the default firmware is 1576 B RAM / 1368 B FLASH and `nm` shows no `_SEGGER_RTT`). To turn logging on, add three lines inside a USER CODE block:
206
-
207
- ```c
208
- /* USER CODE BEGIN 2 */ /* must come after clock init: timestamps use SystemCoreClock */
209
- rtt_init();
210
- rtt_printf(RTT_LEVEL_INFO, "boot: sysclk=%lu", (unsigned long)SystemCoreClock);
211
- /* USER CODE END 2 */
212
- ```
213
-
214
- (`rtt.h` already sits in `Core/Inc`; you may also add an explicit `#include "rtt.h"` to `USER CODE BEGIN Includes`.) After building, grab the control block address on the host:
215
-
216
- ```powershell
217
- arm-none-eabi-nm build/Debug/<project>.elf | findstr _SEGGER_RTT
218
- ```
219
-
220
- Then have the model run these three steps (three `stm32_rtt` tool calls, arguments named as in the tool schema):
221
-
222
- ```text
223
- stm32_rtt action=start addr=0x20000DE0 # control block address from the nm line above
224
- stm32_rtt action=dump seconds=3 level=3 # 3 s of info and above
225
- stm32_rtt action=stop # releases the port; also runs at turn end
226
- ```
227
-
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.
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
-
261
- ## Slash commands
262
-
263
- Tools are for the model; when you want to act yourself, use a command — one command, one action, no model decision in between.
264
-
265
- | Command | What it does | Touches the board |
266
- | --- | --- | --- |
267
- | `/stm32-doctor` | Health check: toolchain, busy debug processes, ports, `.elf`, `.ioc` warnings | No |
268
- | `/stm32-setup` | Health check plus an install plan in one go; only actually installs when the command says so (e.g. `/stm32-setup install the missing ones`) | No |
269
- | `/stm32-env` | Shows what each of the four capabilities (build / flash / debug / generate) is missing, what to install and how to self-check; a missing toolchain still renders the card | No |
270
- | `/stm32-build [dir] [--clean]` | Build, printing memory usage / `.elf` / errors | No |
271
- | `/stm32-flash [dir]` | **Flash**: program + verify + reset, no debug session, no breakpoints | Yes |
272
- | `/stm32-debug [dir]` | **Flash + debug**: halt at `main` after flashing, session kept (3 min idle / 10 min limit, also closed when the turn ends) | Yes |
273
- | `/stm32-stop` | Closes the session opened by `/stm32-debug` and hands the probe back to VS Code | No |
274
-
275
- `[dir]` defaults to the current session's working directory.
276
-
277
- ## Design notes
278
-
279
- - **Flashing and debugging are two separate paths.** `stm32_flash` only uses openocd's `program/verify/reset/exit`; success is proven by `** Programming Finished **` and `** Verified OK **` appearing in the log, not by "no errors".
280
- - **USER CODE only.** Change logic with `stm32_code_patch`; `stm32_generate` carries old content back by label, so edits to generated regions (or whole-file rewrites) are lost on the next generate.
281
- - **`.ioc` is a transaction.** `plan` only computes the diff and a `planId`; `apply` writes, verifying the SHA before and re-parsing after, with rollback on failure.
282
- - **Flash guard.** If SYS is not Serial Wire (PA13/PA14 missing or set to `No_Debug`), CubeMX generates `__HAL_AFIO_REMAP_SWJ_DISABLE()` — flash that and SWD is gone, recoverable only via BOOT0. `stm32_flash` refuses such projects; pass `allowNoDebug: true` if you really mean it.
283
- - **One probe at a time.** Flashing, debugging and a background session cannot coexist; `build` / `flash` / `debug_run` / `generate` release any session holding the probe before they start.
284
-
285
- ## Chips, linker scripts and clocks
286
-
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.
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).
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).
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".
292
- ## Configuration
293
-
294
- ### User config file (`~/.dsh-stm32/config.json`)
295
-
296
- The plugin remembers where the toolchain lives. `stm32_env_install` writes this file when it finishes, and every tool reads it — **no DSH restart, no environment variables**. Hand-writing it works too:
297
-
298
- ```json
299
- {
300
- "version": 1,
301
- "msys64": "E:/msys64",
302
- "binDirs": [],
303
- "packages": ["mingw-w64-ucrt-x86_64-arm-none-eabi-gcc", "mingw-w64-ucrt-x86_64-cmake"],
304
- "cubeMxRoot": "",
305
- "updatedAt": "2026-02-01T00:00:00.000Z"
306
- }
307
- ```
308
-
309
- An empty `binDirs` is derived from `msys64` as `<msys64>/ucrt64/bin` — the shape the installer writes. A corrupt file (invalid JSON) never makes a tool fail; it is simply treated as "not configured".
310
-
311
- **Precedence**: tool arguments (`binDirs` / `cubeMxRoots`) > environment variables > this config file > built-in defaults; auto-discovered installs are only appended when no argument was given.
312
-
313
- ### Settings panel (GUI)
314
-
315
- The config file above can also be edited without a terminal: **Settings → STM32 toolchain** in DSH (a browser-side panel shipped with the plugin, same origin, no extra dependency). Three cards:
316
-
317
- - **Where it is installed**: reads the current config; edit `msys64` / `cubeMxRoot` / extra `binDirs` and save — it writes the same file, and the next tool call picks it up without restarting DSH;
318
- - **What is missing**: one probe run (it executes each tool's version command, installs nothing) showing the resolved path and version per tool, the `hint` for missing ones, plus four capability badges (build / flash / debug / generate);
319
- - **Install the toolchain**: first a plan (steps, download size, how PATH and the config file would change), then **a second click to confirm** before anything is installed; progress and the log tail stream into the card. It drives the very same installer as `stm32_env_install`. When the toolchain is already complete, the plan is a single line — "toolchain complete, nothing to install" — instead of seven skipped steps.
320
-
321
- The panel talks to six `/dsh-stm32/api/*` routes the plugin registers on the host (read config, save config, probe, install plan, install start, install state). The bundle is `lib/client.js`, source in `client/client.js`, copied verbatim by `npm run build` — hand-written plain JS requiring only `react`, no bundler and no runtime dependency. When the host has no `webServer` service (a pure CLI composition) this layer is skipped silently; tools and slash commands are unaffected.
322
-
323
- ### Download cache (register-route template)
324
-
325
- What the register route needs — CMSIS device headers, the startup file, core headers — is **not vendored into the plugin** (covering any STM32 part would make the package unusable), so it is downloaded on first use into a searchable cache directory and reused from then on:
326
-
327
- - Location: `DSH_STM32_CACHE` (supports `~`) > `%LOCALAPPDATA%\dsh-stm32\cache`;
328
- - Index: `index.json` under the cache root records each entry's source URLs, byte counts and license (`THIRD_PARTY_NOTICES.md` is written alongside);
329
- - Sources: tried in the order `fastly.jsdelivr` → `cdn.jsdelivr` → `raw.githubusercontent` → `ghproxy`; an HTTP error, HTML-looking body or an implausible byte count counts as a failed source;
330
- - A partial download is deleted outright (a half cache is worse than none); missing or size-mismatched files trigger a re-download on the next run;
331
- - Visible and removable: `stm32_cache` with `list` / `verify` / `fetch` / `purge`.
332
-
333
- ### Firmware packages (HAL route)
334
-
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):
341
-
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.
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);
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;
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`;
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;
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.
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
-
361
- ### Environment variables (optional)
362
-
363
- | Variable | Purpose | Default |
364
- | --- | --- | --- |
365
- | `STM32_BIN_DIRS` | Toolchain directory candidates, `;`-separated; **replaces** the built-in list (auto-discovered dirs are still appended after it) | `C:/msys64/ucrt64/bin`, `C:/msys64/mingw64/bin` |
366
- | `STM32_CUBEMX_ROOT` | STM32CubeMX installation root; **replaces** the built-in list | `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` |
367
- | `STM32_NO_DISCOVER` | Set to `1` / `true` to turn auto-discovery off (CI, or when you only want the built-in list) | unset = on |
368
- | `DSH_STM32_CONFIG` | Point the config file elsewhere (several toolchains / project isolation) | `%USERPROFILE%\.dsh-stm32\config.json` |
369
- | `DSH_STM32_NO_CONFIG` | Set to `1` / `true` to ignore the config file entirely (environment variables only) | unset = read |
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 |
377
- | `DSH_STM32_E2E_PROJECT` | Project used by hardware e2e runs (with `openocd.cfg` and `build/Debug/*.elf`) | none |
378
- | `DSH_STM32_E2E_ROOT` | Scratch directory for e2e copies | system temp |
379
-
380
- Per-call arguments work too: flash/debug tools accept `binDirs`, `elfPath`, `buildDir`, `configFile`, `adapterSpeed`; generate/create accept `cubeMxRoots`, `firmwarePackage`.
381
-
382
- **Auto-discovery (a different machine usually needs no variables at all).** When `binDirs` / `STM32_BIN_DIRS` is not given, the plugin scans common locations once and **appends** what it finds to the end of the candidate list:
383
-
384
- - Toolchain: `ucrt64/bin`, `mingw64/bin`, `clang64/bin` under `<drive>/msys64`, `<drive>/msys2`, `<drive>/app/msys64`, `<drive>/tools/msys64`, `%LOCALAPPDATA%/Programs/msys64` (the directory must actually contain `arm-none-eabi-gcc.exe` / `openocd.exe` / `cmake.exe`).
385
- - CubeMX: registry `HKLM|HKCU\SOFTWARE\STMicroelectronics\STM32CubeMX` → `InstallDir`, `...\Uninstall\STM32CubeMX` → `InstallLocation`, plus `STM32CubeMX` under `<drive>/`, `<drive>/app`, `<drive>/tools`, `Program Files\STMicroelectronics\STM32Cube`, `%LOCALAPPDATA%/Programs` (both `STM32CubeMX.exe` and `jre/bin/java.exe` must exist).
386
-
387
- One scan takes about a second and is cached per process. **Explicit `binDirs` / `cubeMxRoots` arguments are used as-is, with nothing appended** — what you point at is what runs, so "I specified it" never turns out to be a lie. Paths from environment variables are normalized first (quotes stripped, backslashes to slashes, duplicate slashes collapsed), so a quoted `setx "D:\app\msys64\ucrt64\bin"` is fine. When a tool is missing, both the error message and `stm32_doctor`'s notes list every directory that was searched.
388
-
389
- ### openocd.cfg (in the project, takes precedence over built-in fallbacks)
390
-
391
- CMSIS-DAP (default):
392
-
393
- ```text
394
- source [find interface/cmsis-dap.cfg]
395
- source [find target/stm32f1x.cfg]
396
- adapter speed 4000
397
- ```
398
-
399
- ST-Link (swap in your probe):
400
-
401
- ```text
402
- source [find interface/stlink.cfg]
403
- transport select hla_swd
404
- source [find target/stm32f1x.cfg]
405
- ```
406
-
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`.
409
-
410
- ### Two hard requirements on the .ioc
411
-
412
- 1. **SYS must be Serial Wire** (PA13 = `SYS_JTMS-SWDIO`, PA14 = `SYS_JTCK-SWCLK`); if not, add it with `serialWire: true` in `stm32_ioc_plan`.
413
- 2. **`ProjectManager.KeepUserCode=true`**; otherwise USER CODE is not preserved when regenerating.
414
-
415
- ## Known limitations
416
-
417
- | Limitation | Detail | Workaround |
418
- | --- | --- | --- |
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 |
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` |
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` |
424
- | Generation/scaffolding needs **CubeMX + the F1 firmware package** | Package version defaults to `STM32Cube_FW_F1_V1.8.7` | Pass another version via `firmwarePackage` |
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 |
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 |
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 |
431
-
432
- ## Troubleshooting
433
-
434
- | Symptom | Cause and fix |
435
- | --- | --- |
436
- | `ERR_PNPM_GIT_UNKNOWN_ERROR … connect ETIMEDOUT …:443` while installing | The **package fetch hop** cannot reach GitHub (`dsh plugin add github:…` clones over git). It is unrelated to the pnpm 11 `allowBuilds` allow-list, package signatures, or a broken tarball — the same command works from another network. Three options, easiest first: (1) install the published package: `dsh plugin --profile desktop add dsh-stm32` (npm registry, no GitHub); (2) if you must install from GitHub, proxy **only that one command** with process-scoped `GIT_CONFIG_*` (your global git config stays untouched): `$env:GIT_CONFIG_COUNT="1"; $env:GIT_CONFIG_KEY_0="http.https://github.com.proxy"; $env:GIT_CONFIG_VALUE_0="http://127.0.0.1:7890"; dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main` (use your own port); (3) skip git entirely and take the HTTPS tarball: `dsh plugin --profile desktop add https://codeload.github.com/JingYu-er/dsh-stm32/tar.gz/refs/heads/main`. For the newest code use `github:JingYu-er/dsh-stm32#main`; for a published release use `dsh-stm32@latest` — same content, no GitHub dependency |
437
- | SWD lost after flashing | The firmware generated `__HAL_AFIO_REMAP_SWJ_DISABLE()`. Hold BOOT0 while powering up to enter the system bootloader and reflash, then set SYS back to Serial Wire — `stm32_flash` now blocks this case first |
438
- | `Error: No device found` / `transfer count mismatch` | Another process holds the probe. Run `/stm32-stop`, then use `stm32_doctor` to inspect openocd / gdb processes and port 3333. Reading registers while a debug session is open no longer hits this: `stm32_regs_read` reuses the session's openocd instead of starting a second one |
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` |
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 |
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) |
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 |
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 |
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` |
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 |
447
- | The notes say the local pack index has no such pack | An X-CUBE pack the project needs is not installed here (the decision matches `Mcu.ThirdParty<k>` in the `.ioc` against the built-in catalog by name). Install it in the CubeMX *Manage embedded software packages* dialog, then generate again. This note also shows up in **failed** generate reports (a timeout or a CubeMX error still carries the notes — read them before guessing). The catalog is a snapshot: after installing new packs, rerun `node scripts/gen-xcube-catalog.mjs` (an older catalog only fails to recognise new packs, it never wrongly decides the index is unnecessary) |
448
- | `stm32_code_patch` says the block does not exist | `main.c` uses short labels (`PV` = private variables, `PFP` = prototypes, `2` = init before while, `3` = loop body); the error lists every available label — copy one from there |
449
-
450
- ## Development and testing
451
-
452
- ```powershell
453
- npm run build # tsc -> lib/ (lib/ is committed: rebuild before you commit)
454
- npm test # 60 offline suites, 947 cases; no board, CubeMX, or toolchain needed
455
- npm run test:pack # pack a tarball, unpack it, scaffold a real register project from the unpacked lib
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
457
- ```
458
-
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).
460
-
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.
462
-
463
- ### What ships where (decide before you add a file)
464
-
465
- | Where | What | Size |
466
- | --- | --- | --- |
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) |
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` |
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` |
471
- | Rendered on the spot | `.ioc` content (`renderIoc`), `.ld` MEMORY (`renderLinkerScript`), the cmake source list | rendered per part, never stored as a template |
472
-
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.
474
-
475
- Hardware e2e writes to the board and needs a project you point it at:
476
-
477
- ```powershell
478
- $env:DSH_STM32_E2E_PROJECT = 'D:\work\my-stm32'
479
- node test\e2e-flash.mjs
480
- ```
481
-
482
- See the [development notes](docs/development-notes.md) for the suite breakdown and what each script covers.
483
-
484
- ## Repository layout
485
-
486
- ```text
487
- src/
488
- index.ts plugin entry (name / inject / apply)
489
- tools/ the 25 registered tools, L3 (24 files: parameter schema + output contract + rendering)
490
- engine/ pure logic and workflows (generate / build / flash / debug / ioc / scaffold …)
491
- commands/register.ts the 7 slash commands
492
- skill/stm32-workflow.ts the SKILL shipped with the plugin
493
- data/ paths and chip data (paths are data, not logic)
494
- templates/scaffold/ project template snapshot (CMake / .ld / .vscode / .ioc)
495
- test/ offline suites (60, registered in run-units) + fixtures + hardware e2e
496
- scripts/ guards and generators (pack-size / pack-smoke / gen-xcube-catalog / copy-client)
497
- docs/ specification + development notes + reading guide + diagrams/ (not packed)
498
- ```
499
-
500
- ## Documentation
501
-
502
- - [Specification](docs/dsh-stm32-plugin-规格.md): tool contracts, state machine, acceptance criteria A1–A13
503
- - [Development notes](docs/development-notes.md): milestones, host-contract pitfalls, implementation details and measured numbers
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)
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
507
-
508
- ## License
509
-
510
- [MIT](LICENSE)
1
+ # dsh-stm32
2
+
3
+ [![GitHub stars](https://img.shields.io/github/stars/JingYu-er/dsh-stm32?color=4a6cf7)](https://github.com/JingYu-er/dsh-stm32)
4
+ [![license](https://img.shields.io/github/license/JingYu-er/dsh-stm32)](LICENSE)
5
+ [![platform](https://img.shields.io/badge/platform-Windows%2010%2F11-4a6cf7)](#known-limitations)
6
+ [![MCU](https://img.shields.io/badge/MCU-STM32%20family-4a6cf7)](#known-limitations)
7
+ [![version](https://img.shields.io/badge/version-0.1.8-orange)](https://github.com/JingYu-er/dsh-stm32/releases)
8
+
9
+ Full-chain STM32 tooling distributed as a [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) plugin: 25 tools, 7 slash commands and one bundled SKILL that hand the chain "probe toolchain → scaffold a project → edit `.ioc` (clocks included) → generate code → build → flash → debug → read registers back" to the model, plus serial interaction (Windows) and an in-session debug console panel.
10
+
11
+ Within the supported range the same tools behave the same way from F1 to H7; for an unsupported family or capability the call states what is missing instead of returning a guessed result.
12
+
13
+ | Capability | Coverage |
14
+ | --- | --- |
15
+ | Chip families | 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 |
16
+ | HAL scaffolding | 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 |
17
+ | Register scaffolding | 21 families, all passing the create→build matrix |
18
+ | Clock planning | 18 families; PLL1 on H5 / U5 / WBA / L4+ |
19
+ | `.ioc` peripheral presets | Derived from official CubeMX data: USART / TIM PWM / ADC |
20
+ | Register names and bitfields | F1 |
21
+
22
+ **中文:** [README.md](./README.md)
23
+
24
+ [Quick start](#quick-start-minimal-end-to-end-check) · [Tool reference](#tool-reference) · [Slash commands](#slash-commands) · [Debug console](#debug-console-panel) · [Configuration](#configuration) · [Known limitations](#known-limitations) · [Troubleshooting](#troubleshooting)
25
+
26
+ ## What it does
27
+
28
+ Most "AI writes STM32 code" setups stop at the source level: a `main.c` is produced, and whether it compiles and blinks is still confirmed by hand across CubeMX, a terminal and a debugger. The model cannot see the board, so it cannot be accountable for the result.
29
+
30
+ This plugin puts the hardware side inside DSH: the `.ioc` is readable and writable (transaction with rollback), code goes only into `USER CODE` blocks, generation and builds return real error lines, flashing never holds the probe a debugger needs, and register state is read back after flashing. Every step returns something checkable (a plan id, `file:line:col`, `Verified OK`, bit13 of `GPIOC.ODR`, reported as `ODR13=1` when register tables are present), which the model uses to decide the next step.
31
+
32
+ | Step | Manual flow | This plugin |
33
+ | --- | --- | --- |
34
+ | Scaffold | Configure clocks, pins and project settings in the GUI, generate CMake, hand-write `launch.json` | `stm32_project_create` produces a template project in about 2 s, matching CubeMX GUI output, with both `.vscode` configs in place |
35
+ | Reconfigure | Edit in the GUI, regenerate, hope `USER CODE` survives | `stm32_ioc_plan` shows the diff without writing → confirm → `stm32_ioc_apply` with checks, backup and rollback |
36
+ | Write code | Whole-file edits that can land in generated regions and vanish on regeneration | `stm32_code_patch` writes only inside `USER CODE` blocks; bytes outside are preserved |
37
+ | Build | Keil, or hand-maintained CMake and VS Code tasks | `/stm32-build [dir] [--clean]` |
38
+ | Flash | Keil, or a hand-written `tasks.json` calling openocd | `/stm32-flash [dir]` |
39
+ | Verify | Breakpoints and manual register inspection | `stm32_regs_read` reads state back: two `GPIOC.ODR` samples confirm the counter advances, `AFIO.MAPR` confirms firmware did not disable SWD |
40
+ | Debug | F5, manual breakpoints, close the session afterwards | `stm32_debug_run` halts at `main`, captures one snapshot and releases the probe; continuous work uses `stm32_debug_session`, which closes when idle |
41
+
42
+ ## Install
43
+
44
+ ### Install the plugin
45
+
46
+ Only DSH itself is required at this point; the toolchain can be added later.
47
+
48
+ ```powershell
49
+ dsh plugin --profile desktop add dsh-stm32
50
+ ```
51
+
52
+ `dsh plugin` runs `pnpm add` inside the profile directory and appends `dsh-stm32` to that profile's `dsh.profile.bundles`. Exit DSH completely and start it again afterwards; bundle layers load at process start only.
53
+
54
+ - Verify: `dsh plugin --profile desktop why dsh-stm32` prints `0.1.8`
55
+ - Uninstall: `dsh plugin --profile desktop remove dsh-stm32`, then restart DSH
56
+ - Web profile: replace `desktop` with `web`
57
+
58
+ ### Add the toolchain
59
+
60
+ With the plugin installed, parsing `.ioc` files, inspecting pins / clocks / interrupts and previewing plans all work already. Compilers and probe tools are needed only when building, flashing or debugging.
61
+
62
+ | Task | Requires | How to add |
63
+ | --- | --- | --- |
64
+ | Build | `arm-none-eabi-gcc`, `cmake`, `ninja` | `/stm32-setup` installs everything (MSYS2 plus toolchain, about 300 MB); a manual installation is discovered automatically |
65
+ | Flash, debug | `openocd`, `arm-none-eabi-gdb` (or `gdb-multiarch`), a CMSIS-DAP / ST-Link probe | Same command; probe drivers are supplied by the OS |
66
+ | Generate code, scaffold HAL projects | STM32CubeMX (with bundled JRE) and its firmware package | Install CubeMX from the ST website (ST account required); the plugin locates it automatically; install firmware packages in the CubeMX package manager |
67
+
68
+ When the missing piece is unclear, check the diagnosis first:
69
+
70
+ ```text
71
+ /stm32-env # what build / flash / debug / generate are missing, where things install, how to install
72
+ /stm32-setup # plan first, install after confirmation, self-check when done
73
+ ```
74
+
75
+ `/stm32-env` works with no toolchain at all: it only runs version queries and writes nothing.
76
+
77
+ ### Pre-flight check
78
+
79
+ ```text
80
+ /stm32-doctor
81
+ ```
82
+
83
+ Read-only checks: toolchain completeness, leftover openocd / gdb processes holding the probe, gdb port usage, whether `.elf` and `.ioc` exist in the project, and whether the `.ioc` has a configuration that would lose SWD after flashing.
84
+
85
+ ### Bundled assets
86
+
87
+ The mapping from part number to startup file, device macro and Flash / RAM size ships with the plugin, together with `.ioc` templates, linker scripts and register tables. Everything works offline after installation; no resource download is involved. `stm32_assets verify` checks integrity and points to a reinstall when files are missing.
88
+
89
+ ### Install from source
90
+
91
+ Only for development or when the code itself must change. Build and test commands are listed under [Development and testing](#development-and-testing).
92
+
93
+ ```powershell
94
+ git clone https://github.com/JingYu-er/dsh-stm32.git
95
+ cd dsh-stm32
96
+ npm install --no-audit --no-fund # typescript only
97
+ npm run build # tsc -> lib/, required before committing
98
+ ```
99
+
100
+ Mount a working copy with `link:`, not `file:`:
101
+
102
+ ```powershell
103
+ cd "$env:USERPROFILE\.dsh\profiles\desktop"
104
+ pnpm add "link:D:\path\to\dsh-stm32"
105
+
106
+ # append "dsh-stm32" to dsh.profile.bundles in that directory's package.json
107
+ # restart dsh afterwards (bundle layers load at process start only)
108
+ ```
109
+
110
+ Reason: under `nodeLinker: hoisted`, `file:` copies the package into a real directory, so a freshly built `lib/` is never read by the host, which shows up as "code changed, behaviour unchanged". `link:` reads `lib/` from the working copy; DSH still has to restart to reload the plugin.
111
+
112
+ ## Quick start: minimal end-to-end check
113
+
114
+ This chain was verified on real hardware, driven entirely by tool calls. Every step uses the same tools; blinking an LED is simply the cheapest sample.
115
+
116
+ | Step | Action | Tool | Measured |
117
+ | --- | --- | --- | --- |
118
+ | 1 | Probe: toolchain, occupied probes, ports, `.elf`, `.ioc` warnings | `stm32_doctor` | about 2 s |
119
+ | 2 | Scaffold a CMake project in an empty directory (`.ioc` with SWD configured) | `stm32_project_create` | about 2 s |
120
+ | 3 | Run CubeMX headless; output lands in `Core/` | `stm32_generate` | 130–175 s first run; skipped (< 1 s) when nothing changed |
121
+ | 4 | Build (first run configures with `cmake --preset`) | `stm32_build` | about 5 s configure + 3 s compile |
122
+ | 5 | Flash only: program + verify + reset | `stm32_flash` | 2.1–2.6 s |
123
+ | 6 | Read `GPIOC.ODR` (or address `0x4001100C`) and confirm the state toggles | `stm32_regs_read` | 0.4–1.3 s |
124
+
125
+ Step 6 uses symbolic names, which rely on the bundled register tables. With an incomplete installation the address form `0x4001100C` still works, but the report carries no register names or bitfields.
126
+
127
+ On the model side a single sentence suffices: "Create an STM32F103C8T6 blink project in `D:\work\blink`, build it and flash it".
128
+
129
+ The minimal check covers scaffold → generate → build → flash → read-back; no step is blink-specific. Real projects follow the same chain, differing only in the number of peripherals in the `.ioc`, the number of `USER CODE` blocks and the code size.
130
+
131
+ | Real-project task | Path | Verification status |
132
+ | --- | --- | --- |
133
+ | Peripheral setup: GPIO / timers / USART / I2C / SPI / ADC / DMA / interrupts | `stm32_ioc_plan` (GPIO checked against the pin table) → `stm32_ioc_apply` → `stm32_generate` | GPIO, clocks and SWD measured on hardware; other peripherals use the same mechanism, not measured individually |
134
+ | Add HAL sources for new peripherals | Add `stm32f1xx_hal_<peripheral>.c` to `STM32_Drivers_Src` in `cmake/stm32cubemx/CMakeLists.txt`, or write into `cmake/user/CMakeLists.txt` | Manual step: the plugin places only `Src/` and `Inc/`, never CubeMX-generated `cmake/**` |
135
+ | Multiple sources and custom modules | Write into `cmake/user/CMakeLists.txt` (placeholder provided) | Placeholder in place; not measured separately |
136
+ | Application code | `stm32_code_patch` writes per block and carries blocks back on regeneration | Measured (append / replace; an unknown tag lists all available tags) |
137
+ | Tuning, clock changes | `.ioc` transaction: diff → checks → backup → rollback on failure | Measured |
138
+ | Confirm peripherals run | `stm32_regs_read` reads any peripheral register by symbol (`TIM2.CNT`, `USART1.SR`, `ADC1.DR`) or address (`0x40000024`); naming only `GPIOC` dumps all its registers | Address form measured on hardware; symbolic names and bitfields being retested |
139
+ | Inspect a failure | `stm32_debug_run` halts at `main` once; continuous work uses `stm32_debug_session` + `stm32_debug_eval` | Measured (halted at `main () at main.c:67`) |
140
+
141
+ Boundaries are listed under [Known limitations](#known-limitations): HAL scaffolding covers 21 single-core families, register scaffolding 21 (validation board is C8T6), the host is verified on Windows only, the default probe is CMSIS-DAP, and new peripherals need manual HAL sources. Peripheral variety is not a tool limitation: whatever the `.ioc` can express follows the same chain; peripherals other than the blink sample have not been measured individually on hardware, so running `/stm32-doctor` before starting a project is recommended.
142
+
143
+ ## Tool reference
144
+
145
+ ### Environment and projects
146
+
147
+ | Tool | Purpose |
148
+ | --- | --- |
149
+ | `stm32_doctor` | Read-only health check: toolchain completeness, leftover openocd / gdb processes, gdb port usage, `.elf` and `.ioc` status; per-chip capabilities and known issues |
150
+ | `stm32_route_plan` | Estimates HAL versus register cost for a specific project and requirement; separates auto-installable gaps from manual ones |
151
+ | `stm32_env_install` | Installs MSYS2 and toolchain components (gcc / gdb / openocd / cmake / ninja); plan only by default, executes with `dryRun:false` + `confirm:true`; writes user-level PATH only, no administrator rights |
152
+ | `stm32_download` | Download without installing: J-Link direct link with checksum; CubeMX / CubeProgrammer open the official page or validate a local file |
153
+ | `stm32_firmware_install` | Downloads and assembles STM32Cube firmware packages, official archive first, GitHub assembly as fallback; plan only by default |
154
+ | `stm32_assets` | Lists, verifies and prunes bundled assets (chip data, `.ioc` templates, linker scripts, startup files, register tables) |
155
+ | `stm32_cache` | Lists, verifies, fetches and prunes the download cache (register-route CMSIS templates) |
156
+ | `stm32_project_create` | Scaffolds a project: `route:"hal"` from templates plus firmware package, `route:"register"` without CubeMX; both emit `openocd.cfg` |
157
+ | `stm32_project_export` | Packs a project as a zip, excluding `build/`, `.dsh-stm32/`, `node_modules/`, `.git/` by default, optionally with prebuilt artifacts |
158
+
159
+ ### `.ioc`: inspect and edit
160
+
161
+ | Tool | Purpose |
162
+ | --- | --- |
163
+ | `stm32_ioc_inspect` | Read-only parse: part number, pins, signals, enabled peripherals, interrupts, clock tree, project settings, risk notes |
164
+ | `stm32_ioc_plan` | Computes a per-key diff without writing: peripheral presets, pins, interrupts, debug port, clock planning, bulk entries |
165
+ | `stm32_ioc_apply` | Applies a plan: source checks → backup → atomic replace; rollback from backup |
166
+ | `stm32_ioc_verify` | Has CubeMX re-read the `.ioc` and points out silently dropped peripherals and missing init calls |
167
+
168
+ ### Code and build
169
+
170
+ | Tool | Purpose |
171
+ | --- | --- |
172
+ | `stm32_code_patch` | Writes only inside `USER CODE BEGIN/END` blocks, preserving all other bytes; backs up first |
173
+ | `stm32_generate` | Runs CubeMX headless, places output in `Core/`, carries `USER CODE` back by tag; skips when `.ioc` is unchanged |
174
+ | `stm32_build` | Builds: infers build directory and `.elf`, returns error lines, warning count, FLASH / RAM usage; optional hex / bin |
175
+
176
+ ### Flash, debug and runtime
177
+
178
+ | Tool | Purpose |
179
+ | --- | --- |
180
+ | `stm32_flash` | Flash only: program + verify + reset, then releases the probe; checks Serial Wire first; failures return the probe error class and a suggested action |
181
+ | `stm32_debug_run` | Flashes, halts at `main`, captures registers, stack and locals, then resets, runs and releases the probe |
182
+ | `stm32_debug_session` | Opens a long-lived debug session (idle and total limits) for repeated `stm32_debug_eval` calls |
183
+ | `stm32_debug_eval` | Executes gdb commands in the session: variables, registers, backtrace, memory |
184
+ | `stm32_debug_stop` | Closes the session and releases the probe |
185
+ | `stm32_regs_read` | Reads registers by address or symbol, resolving bitfields when register tables are present; pauses briefly to read, then resumes without resetting |
186
+ | `stm32_watch` | Registers and samples expressions (with deltas); `kind=write/read/access` installs hardware watchpoints, limited by the chip's watchpoint count |
187
+ | `stm32_rtt` | RTT channel: firmware keeps the control block in RAM, the host reads it through openocd, output carries level and timestamp |
188
+ | `stm32_serial` | Serial interaction (Windows): `list` / `open` / `read` / `send` / `transact` / `status` / `close` |
189
+
190
+ ### RTT on the firmware side (shortest example)
191
+
192
+ ```c
193
+ /* USER CODE BEGIN 0 */
194
+ static char rtt_buf[3][1024];
195
+ static void rtt_init(void) {
196
+ /* Control block follows the SEGGER convention in RAM: acId / acName / three rings, see rtt.h in templates/ */
197
+ }
198
+ /* USER CODE END 0 */
199
+ ```
200
+
201
+ The full implementation ships in `templates/`; channel count and ring size are controlled by `RTT_UP_CHANNELS` / `RTT_BUF_SIZE` (default 3×1 KB = 3 KB `.bss`; C8T6 has 20 KB RAM).
202
+
203
+ ## Slash commands
204
+
205
+ | Command | Description |
206
+ | --- | --- |
207
+ | `/stm32-doctor` | Health check: toolchain, leftover processes, ports, `.elf` and `.ioc` warnings |
208
+ | `/stm32-env` | Toolchain check: what build / flash / debug / generate are missing, where things install, how to install |
209
+ | `/stm32-setup` | Probe → install plan → install after confirmation → self-check |
210
+ | `/stm32-build [dir] [--clean]` | Build (CMake + Ninja, `build/Debug` by default); `--clean` wipes first |
211
+ | `/stm32-flash [dir]` | Flash only: program + verify + reset, then release the probe |
212
+ | `/stm32-debug [dir]` | Flash and enter debugging, halted at `main`; then use `stm32_debug_eval` |
213
+ | `/stm32-stop` | Close the debug session and release the probe for VS Code F5 |
214
+
215
+ ## Debug console (panel)
216
+
217
+ The in-session debug console shows one timeline for both sides: the start, success, failure and duration of `stm32_*` calls, plus serial, RTT, watch, pin, clock, interrupt and `.ioc` state.
218
+
219
+ | Tab | Content | Actions |
220
+ | --- | --- | --- |
221
+ | Overview | Project, part number, SYSCLK, capacity, debug session, toolchain, build and flash, evidence usage, alert summary | Jump to failed events or the live channel, export an operation log as Markdown |
222
+ | Events | Call start and end, duration, slow-call marker, argument summary | Failures only, filter by tool, sort by duration, bulk quoting, JSONL export, event deep links |
223
+ | Live channels | Serial / RTT / watch output | Pause, clear, keyword filter, RTT level filter, send a serial line, persistent capture, export |
224
+ | Pins | Grouped by peripheral, by port, or as a package outline | Filter, copy references, inspect `.ioc` keys, CSV export |
225
+ | Clocks | Tree and flow views, per-node frequency and divider | Over-limit markers and "change to ÷N" advice computed from the parent clock |
226
+ | Interrupts | NVIC enablement, preemption and sub-priority | Filter, sort, edit in place, bulk edit |
227
+ | Faults | Raw failure events, rule decoding, grouping by rule | Category filter, copy group hint, CSV export |
228
+ | Artifacts | elf / hex / bin, size, checksum, capacity, build-to-build comparison | Copy checksums |
229
+ | Changes | `.ioc` differences against a baseline | Record a baseline, restore one key, restore all |
230
+
231
+ Opening the panel first loads the most recent records for the session, then appends live. Events are written every 30 seconds to `~/.dsh-stm32/evidence/<date>/<session>/` for replay and export, retained for 7 days and the last 20 sessions by default, all configurable. The panel shows only this plugin's own tool calls.
232
+
233
+ ## Serial (Windows)
234
+
235
+ `stm32_serial` exposes seven actions: `list` / `open` / `read` / `send` / `transact` / `status` / `close`. Once opened, the port is held by the plugin, one port at a time; 115200 8N1 by default, no flow control, DTR / RTS not asserted, closed at the end of a turn.
236
+
237
+ - Platform: Windows only. Linux and macOS return `unsupported-platform`.
238
+ - Ports: `list` enumerates available ports; parameters are remembered per device, so a different COM number still reuses them.
239
+ - Read: `read` accepts a cursor and returns only newer lines.
240
+ - Write: `send` writes one line; `transact` writes and waits for a matching reply (regular expression).
241
+ - Retention: `persist=true` keeps the port open across turns.
242
+
243
+ The reference validation board uses a CH340 (`1A86:7523`, COM5, 115200). The DAPLink virtual serial port on the same board (`c251:f001`, COM4) does not carry application data.
244
+
245
+ ## Design notes
246
+
247
+ - **Own files only**: the `.ioc` goes through a transaction (plan → checks → backup → replace); generated regions receive only `USER CODE` content; no other generated file is modified.
248
+ - **Flash and debug are separate**: `stm32_flash` never opens a debug session and releases the probe immediately; debugging opens `stm32_debug_session` on demand and closes it when idle, so VS Code is not locked out.
249
+ - **Conclusions carry evidence**: failures return compiler `file:line:col`, probe error class and register values rather than vague prose.
250
+ - **Say what is missing**: when a chip, a clock plan or a debug script is unsupported, the error names the missing piece instead of guessing or silently skipping.
251
+ - **No host takeover**: the panel displays state and performs explicit project actions; it does not edit code or run Git operations.
252
+
253
+ ## Configuration
254
+
255
+ ### Config file (`~/.dsh-stm32/config.json`)
256
+
257
+ Toolchain locations are maintained by the plugin: `stm32_env_install` writes this file and later tools read it, with no DSH restart and no environment variables required. Manual editing is supported:
258
+
259
+ ```json
260
+ {
261
+ "version": 1,
262
+ "msys64": "E:/msys64",
263
+ "binDirs": [],
264
+ "packages": ["mingw-w64-ucrt-x86_64-arm-none-eabi-gcc", "mingw-w64-ucrt-x86_64-cmake"],
265
+ "cubeMxRoot": "",
266
+ "updatedAt": "2026-02-01T00:00:00.000Z"
267
+ }
268
+ ```
269
+
270
+ An empty `binDirs` derives `<msys64>/ucrt64/bin` from `msys64`. A corrupt file (invalid JSON) is treated as absent and does not break other features.
271
+
272
+ Precedence: tool arguments (`binDirs` / `cubeMxRoots`) > environment variables > config file > built-in defaults. Built-in defaults contain only common Windows locations, never machine-specific paths.
273
+
274
+ ### Settings panel
275
+
276
+ The "STM32 toolchain" page under DSH settings offers three cards:
277
+
278
+ - **Locations**: reads and saves `msys64` / `cubeMxRoot` / extra `binDirs`; the next tool call sees the change.
279
+ - **Missing pieces**: runs a probe (version queries only) and lists path, version and reason per item, plus badges for build / flash / debug / generate.
280
+ - **Install toolchain**: emits a plan first (steps, download size, PATH and config changes), executes after confirmation, and streams steps with a log tail.
281
+
282
+ ### Download cache and firmware packages
283
+
284
+ - Register-route CMSIS templates are downloaded on first use into the cache (default `%LOCALAPPDATA%\dsh-stm32\cache`) and reused afterwards; files are verified and mismatches rejected. `stm32_cache` lists, verifies, fetches and prunes entries.
285
+ - The HAL route uses locally installed CubeMX firmware packages: F1 defaults to `STM32Cube_FW_F1_V1.8.7`, other families use the highest installed version; `firmwarePackage` overrides. When missing, install it through the CubeMX package manager or use `stm32_firmware_install`.
286
+ - `stm32_download` only downloads or verifies installers (default directory `%LOCALAPPDATA%\dsh-stm32\downloads`); it never executes them and never requests administrator rights.
287
+
288
+ ### Environment variables (optional)
289
+
290
+ | Variable | Purpose | Default |
291
+ | --- | --- | --- |
292
+ | `STM32_BIN_DIRS` | Toolchain directory candidates, `;`-separated, replaces the built-in list entirely (auto-discovery still appends) | `C:/msys64/ucrt64/bin`, `C:/msys64/mingw64/bin` |
293
+ | `STM32_CUBEMX_ROOT` | CubeMX root, replaces the built-in list | `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` |
294
+ | `STM32_NO_DISCOVER` | Set to `1` to disable auto-discovery (built-in list only) | unset |
295
+ | `DSH_STM32_CONFIG` | Alternate config file path | `%USERPROFILE%\.dsh-stm32\config.json` |
296
+ | `DSH_STM32_NO_CONFIG` | Set to `1` to ignore the config file entirely | unset |
297
+ | `DSH_STM32_CACHE` | Download cache root, supports `~` | `%LOCALAPPDATA%\dsh-stm32\cache` |
298
+ | `DSH_STM32_DOWNLOADS` | Installer download directory, supports `~` | `%LOCALAPPDATA%\dsh-stm32\downloads` |
299
+ | `DSH_STM32_HOME` | Plugin data root (config, evidence, snapshots, memo) | `%USERPROFILE%\.dsh-stm32` |
300
+ | `DSH_STM32_EVIDENCE` | Evidence directory | `~/.dsh-stm32/evidence` |
301
+ | `DSH_STM32_EVIDENCE_FLUSH_SECONDS` | Flush interval (5–3600 s) | 30 |
302
+ | `DSH_STM32_EVIDENCE_KEEP_DAYS` | Evidence retention in days (0–365, 0 = keep) | 7 |
303
+ | `DSH_STM32_EVIDENCE_KEEP_SESSIONS` | Evidence retention in sessions (1–200) | 20 |
304
+ | `DSH_STM32_SNAPSHOTS` | `.ioc` baseline directory | `~/.dsh-stm32/ioc-snapshots` |
305
+ | `DSH_STM32_OFFLINE` | Set to `1` to forbid network downloads (cache only) | unset |
306
+ | `MSYS2_MIRROR` | Installer mirror; must be set together with `MSYS2_INSTALLER_SHA256` | official → TUNA → NJU → Aliyun |
307
+ | `MSYS2_INSTALLER_URL` / `MSYS2_INSTALLER_SHA256` | Installer URL and checksum overrides; must be set together | official pinned release |
308
+ | `DSH_STM32_JLINK_URL` / `DSH_STM32_JLINK_SHA256` | J-Link direct link and checksum overrides; must be set together | SEGGER official |
309
+
310
+ Tool arguments mirror these variables: flash and debug tools accept `binDirs`, `elfPath`, `buildDir`, `configFile`, `adapterSpeed`; generation and scaffolding accept `cubeMxRoots`, `firmwarePackage`.
311
+
312
+ Toolchain locations usually need no configuration: when `binDirs` / `STM32_BIN_DIRS` are absent, the plugin searches common locations and appends candidates — `ucrt64/bin`, `mingw64/bin` and `clang64/bin` under `<drive>/msys64`, `<drive>/msys2`, `<drive>/app/msys64`, `<drive>/tools/msys64`, `%LOCALAPPDATA%/Programs/msys64`; and CubeMX under the `STM32CubeMX_PATH` environment variable, its uninstall registration, and `Program Files\STMicroelectronics\STM32Cube`. When nothing is found, errors and `stm32_doctor` list the directories that were checked.
313
+
314
+ ### openocd.cfg (project-level, takes precedence)
315
+
316
+ CMSIS-DAP (default):
317
+
318
+ ```text
319
+ source [find interface/cmsis-dap.cfg]
320
+ source [find target/stm32f1x.cfg]
321
+ adapter speed 4000
322
+ ```
323
+
324
+ ST-Link:
325
+
326
+ ```text
327
+ source [find interface/stlink.cfg]
328
+ transport select hla_swd
329
+ source [find target/stm32f1x.cfg]
330
+ ```
331
+
332
+ Without `openocd.cfg`, the debug script follows the chip family in the `.ioc` (F1 → `stm32f1x`, F4 → `stm32f4x`, G4 → `stm32g4x`; L4 and L4+ share `stm32l4x`). C0 / U0 scripts ship with the plugin and are copied into the project's `openocd/` directory during scaffolding; H5 / N6 / U3 / WBA / WB0 / WL3 / MP2 have no scripts and flashing is refused explicitly.
333
+
334
+ ### Two hard requirements on the `.ioc`
335
+
336
+ 1. **SYS debug port set to Serial Wire** (PA13 = `SYS_JTMS-SWDIO`, PA14 = `SYS_JTCK-SWCLK`); use `stm32_ioc_plan` with `serialWire: true` when missing.
337
+ 2. **`ProjectManager.KeepUserCode=true`**; otherwise `USER CODE` content is lost on regeneration.
338
+
339
+ ## Known limitations
340
+
341
+ | Limitation | Detail | Handling |
342
+ | --- | --- | --- |
343
+ | Verified on Windows only | Code generation depends on the Windows installation of CubeMX | No alternative yet; flash, debug and register reads may work elsewhere with a complete toolchain, unverified |
344
+ | Some chips have no official debug script | C0 / U0 use plugin-supplied scripts (not verified on hardware); H5 / N6 / U3 / WBA / WB0 / WL3 / MP2 have none | Flashing states this explicitly instead of failing silently |
345
+ | HAL scaffolding excludes dual-core and MPU families | Dual-core WB, MP1 / MP2 / N6, WB0 / WL3 are out of scope | Scaffolding reports the chip as unsupported |
346
+ | Depth is graded per family | HAL 21 families, register 21, clocks 18; register names and bitfields currently F1 only | The missing capability is named at call time |
347
+ | Probes selected from what USB reports | ST-Link, DAPLink / CMSIS-DAP and J-Link are distinguished automatically; a project `openocd.cfg` wins | Write `openocd.cfg` to pin a choice |
348
+ | New peripherals need manual HAL sources | The plugin places only `Src/` and `Inc/`; CubeMX-generated `cmake/**` is not carried over | Edit `STM32_Drivers_Src` or write into `cmake/user/CMakeLists.txt` |
349
+ | Generation and scaffolding need CubeMX plus the family firmware package | F1 defaults to `STM32Cube_FW_F1_V1.8.7` | Pass `firmwarePackage`, or install the package in CubeMX first |
350
+ | RTT is channel 0 only with a custom frame | 13-byte header (length, level, timestamp, UTF-8 text) | Filter by level; put structured data in the text; channels and ring size in `rtt.h` |
351
+ | Serial is Windows-only | No streaming UI, no auto-reconnect, one port at a time | Use a system serial tool, or a later release |
352
+ | Register names and bitfields need the bundled register tables | Covers F1 lines 100 / 101 / 102 / 103 / 105 / 107 | Use `0x` addresses; `stm32_assets verify` checks the installation |
353
+
354
+ ## Troubleshooting
355
+
356
+ | Symptom | Cause | Action |
357
+ | --- | --- | --- |
358
+ | Plugin not loaded | `dsh.profile.bundles` lacks `dsh-stm32`, or DSH was not restarted | Reinstall and restart; verify with `dsh plugin --profile desktop why dsh-stm32` |
359
+ | Code changes have no effect | Installed via `file:`, so the host reads a copy | Switch to `link:`, rebuild with `npm run build`, restart DSH |
360
+ | Missing toolchain reported | Not installed, or path not discovered | Run `/stm32-env` to see what is missing, then `/stm32-setup`; or set `binDirs` manually |
361
+ | Flash reports the probe is busy | Another debugger (VS Code, leftover openocd) holds the probe | `/stm32-stop`, close other debuggers, retry; `stm32_doctor` lists leftover processes |
362
+ | SWD is lost after flashing | `.ioc` did not enable Serial Wire | Add `serialWire: true` via `stm32_ioc_plan`, regenerate, flash again |
363
+ | Peripherals dropped after generation | `.ioc` keys inconsistent with peripheral derivation | Run `stm32_ioc_verify` for a CubeMX-side diagnosis |
364
+ | Panel is blank or stale | Server-side change without restart, or `lib` newer than the process | Fully exit DSH and start again; the status bar flags "new build available" |
365
+ | No serial data | Wrong port (for example the DAPLink virtual port) | Confirm with `stm32_serial list`; application serial usually lives on a CH340-class adapter |
366
+
367
+ ## Development and testing
368
+
369
+ | Command | Purpose |
370
+ | --- | --- |
371
+ | `npm run build` | `tsc` into `lib/`, copying client and data assets |
372
+ | `node test/run-units.mjs` | Offline unit tests: 80 suites / 1088 cases, no board required |
373
+ | `node .dsh-stm32/acceptance.mjs` | Local acceptance script: panel API, event stream, evidence, artifacts, faults, interrupts, serial, probe |
374
+ | `npm run test:pack` | Pack, unpack and scaffold a register project with the unpacked build |
375
+ | `npm run test:size` | Package and asset guards |
376
+
377
+ Release shape: published content is limited to `files` in `package.json` (`lib`, `client`, `templates`, `assets`, `docs/reading-guide.md`, `cordis.patch.yml`, both READMEs, `LICENSE`). `docs/`, `test/` and `scripts/` stay out of the package.
378
+
379
+ Development-only environment variables (not needed in daily use): `DSH_STM32_ASSETS` and `DSH_STM32_FACTS` override asset directories, `DSH_STM32_SERIAL_BRIDGE` and `DSH_STM32_SERIAL_POWERSHELL` override the serial bridge path, `DSH_STM32_PYTHON` selects the Python interpreter used for parsing.
380
+
381
+ ## Repository layout
382
+
383
+ ```text
384
+ src/
385
+ index.ts plugin entry: tools, slash commands, panel API, SKILL
386
+ tools/ registration and argument validation for 25 tools
387
+ engine/ engines: project, .ioc, generation, build, flash, debug, events, panel API
388
+ data/ chip data, CubeMX data, clocks, search roots, toolchain config
389
+ commands/ 7 slash commands
390
+ skill/ bundled stm32-workflow SKILL
391
+ client/client.js panel source (plain JS + react, no bundler)
392
+ lib/ tsc output and copied assets (published)
393
+ assets/ chip data, .ioc templates, linker scripts, startup files, register tables
394
+ templates/ scaffolding templates, register route, serial bridge, RTT
395
+ test/ 80 offline suites and e2e scripts
396
+ scripts/ build, pack, size and smoke scripts
397
+ docs/ development notes, reading guide, spec, diagrams
398
+ ```
399
+
400
+ ## Documentation
401
+
402
+ - [Specification](docs/dsh-stm32-plugin-规格.md): tool contracts, state machine, acceptance criteria
403
+ - [Development notes](docs/development-notes.md): milestones, host-contract issues, per-tool implementation details and measurements
404
+ - [Source reading guide](docs/reading-guide.md): layered reading order, per-file responsibilities and exports, diagrams and invariants
405
+ - Release notes: provided per release on the release page; history lives in git and the development notes
406
+ - Visuals: [architecture](docs/diagrams/dsh-stm32-architecture.html) / [main journey](docs/diagrams/dsh-stm32-journey.html) — single-file HTML, opens offline
407
+
408
+ ## License
409
+
410
+ [MIT](LICENSE)