dsh-stm32 0.1.4 → 0.1.6

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 (38) hide show
  1. package/README.md +517 -459
  2. package/README_EN.md +510 -453
  3. package/assets/device/h7/chips.json +831 -140
  4. package/assets/device/u5/chips.json +375 -64
  5. package/assets/manifest.json +4 -4
  6. package/docs/reading-guide.md +114 -16
  7. package/lib/commands/register.js +1 -1
  8. package/lib/data/cmsis-sources.js +136 -4
  9. package/lib/data/device-facts.js +14 -0
  10. package/lib/data/family.js +14 -14
  11. package/lib/data/firmware-packages.js +35 -14
  12. package/lib/data/firmware-pins.js +128 -0
  13. package/lib/data/search-roots.js +17 -3
  14. package/lib/data/serial-config.js +430 -0
  15. package/lib/engine/doctor.js +85 -8
  16. package/lib/engine/download.js +242 -0
  17. package/lib/engine/fetch.js +1 -1
  18. package/lib/engine/firmware-install.js +158 -35
  19. package/lib/engine/firmware-official.js +113 -65
  20. package/lib/engine/ioc-plan.js +28 -6
  21. package/lib/engine/msys2-install.js +237 -88
  22. package/lib/engine/probe.js +4 -2
  23. package/lib/engine/register-gpio.js +18 -1
  24. package/lib/engine/register-linker.js +25 -6
  25. package/lib/engine/register-template.js +25 -1
  26. package/lib/engine/serial.js +1696 -0
  27. package/lib/engine/tar.js +235 -3
  28. package/lib/index.js +12 -0
  29. package/lib/skill/stm32-workflow.js +2 -2
  30. package/lib/tools/assets.js +8 -3
  31. package/lib/tools/build.js +0 -1
  32. package/lib/tools/doctor.js +9 -3
  33. package/lib/tools/download.js +303 -0
  34. package/lib/tools/ioc-plan.js +17 -7
  35. package/lib/tools/project-create.js +1 -1
  36. package/lib/tools/serial.js +737 -0
  37. package/package.json +70 -70
  38. package/templates/serial/bridge.ps1 +477 -0
package/README_EN.md CHANGED
@@ -1,453 +1,510 @@
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. 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 13 families; 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.4-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 23 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.4`); 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: 736 offline cases in 43 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 <=1.2 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) — the STM32F1 family only (F100/101/102/103/105/107; the verified board is a C8T6), verified on Windows only, CMSIS-DAP by default, plus the manual HAL-source step above. Peripheral types themselves are not limited by the tools: whatever the `.ioc` can configure goes through the same generate → build → flash → read-back chain; it just has not been tested peripheral by peripheral yet, so run `stm32_doctor` before starting a real project.
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
- | Choose the technical route | `stm32_route_plan`: for **this project's** requirements, lays out the HAL and register cost per peripheral (effort / readability / debugging), then says whether what is missing is installable-by-the-plugin or human-only (CubeMX is a GUI wizard needing an ST account; firmware packages are only maintained by the CubeMX package manager) |
140
- | Chip facts (part → startup file / device define / sizes) | The plugin **ships the chip table inside the npm package**: part, startup file, device define and Flash/RAM come from `assets/device/f1/chips.json` (`lib/engine/assets.js` resolves `assets/` from the package root; `DSH_STM32_ASSETS` can still point elsewhere for development). A missing file only means an incomplete install: locate it with `stm32_assets verify`, then reinstall the plugin — no network needed |
141
- | Project from scratch | `stm32_project_create`: `route: "hal"` uses the template snapshot + firmware Drivers (byte-identical to a CubeMX GUI project); `route: "register"` builds a register-level project with no CubeMX at all, pulling the CMSIS template into the cache on first use (every file is pinned by upstream sha256 and refused if it changed); `mcu` names the part (both routes accept it; the HAL route renders its startup file / device define / `<DeviceId>_FLASH.ld` from it); both routes also ship an `openocd.cfg` (CMSIS-DAP + `hla_swd` + 2 MHz) |
142
- | Export a project | `stm32_project_export`: packs the sources into one zip (without `build/`, `.dsh-stm32/`, `node_modules/`, `.git/`), optionally including the `.elf`, plus a hand-off README |
143
- | `.ioc` as a transaction | `stm32_ioc_inspect` (read-only parse) → `stm32_ioc_plan` (diff, no writes) → `stm32_ioc_apply` (SHA check + backup + rollback) |
144
- | USER CODE only | `stm32_code_patch`: writes only between `/* USER CODE BEGIN X */` and `END X`; everything else untouched |
145
- | Code generation | `stm32_generate`: headless CubeMX + ST project layout + USER CODE carried over by label |
146
- | Build | `stm32_build`: build directory and `.elf` inferred, deduplicated errors, RAM/FLASH usage parsed after linking; ask for `artifacts: ["hex","bin"]` and the same toolchain's `arm-none-eabi-objcopy` produces them |
147
- | Flash | `stm32_flash`: openocd `program verify reset exit`, probe released afterwards; checks that the `.ioc` has Serial Wire enabled; failures carry a structured `probeError` (`kind` / `cause` / `hint` / `evidence` / `retryable`, `kind` is one of 9) |
148
- | Debug | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
149
- | Prove it is running | `stm32_regs_read`: reads any peripheral register back by address or symbol name (`GPIOC.ODR`), decoding bit fields when SVD data is installed (`→ ODR5=1`); halts, reads, then `resume` — no chip reset |
150
- | 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 |
151
- | 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 |
152
- | 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) |
153
-
154
- ## Tool reference
155
-
156
- ### Environment and project
157
-
158
- | Tool | What it does |
159
- | --- | --- |
160
- | `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) and `recommendations` (install order and an offer to install for you). Read-only, repeatable |
161
- | `stm32_env_install` | One-stop install when the toolchain is missing: `dryRun` (default) only returns a plan — size of the official MSYS2 installer, the five packages, the PATH entry it would add; only `dryRun: false` + `confirm: true` actually work (download → install MSYS2 → `pacman -S` → user-level PATH → self-check → write `~/.dsh-stm32/config.json`). With an existing msys64 it only adds the packages. No uninstall |
162
- | `stm32_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 |
163
- | `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 |
164
- | `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` |
165
- | `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 |
166
- | `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 |
167
- | `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) |
168
- | `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`). `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 |
169
-
170
- ### .ioc: read-only and transactions
171
-
172
- | Tool | What it does |
173
- | --- | --- |
174
- | `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`" |
175
- | `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 |
176
- | `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` |
177
- | `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` |
178
-
179
- ### Code and build
180
-
181
- | Tool | What it does |
182
- | --- | --- |
183
- | `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 |
184
- | `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 |
185
- | `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 |
186
-
187
- ### Flash and debug
188
-
189
- | Tool | What it does |
190
- | --- | --- |
191
- | `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 |
192
- | `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 |
193
- | `stm32_debug_session` | Long-lived openocd session (`.elf` resolved automatically), closed after 90 s idle, hard limit 10 min |
194
- | `stm32_debug_eval` | Runs gdb commands or reads expressions (e.g. `g_led_blink_count`) inside the session, then `resume` + `detach` immediately |
195
- | `stm32_debug_stop` | Releases the probe immediately, idempotent |
196
- | `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 |
197
- | `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 |
198
- | `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 |
199
-
200
- ### Adding RTT to the firmware (shortest example)
201
-
202
- 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:
203
-
204
- ```c
205
- /* USER CODE BEGIN 2 */ /* must come after clock init: timestamps use SystemCoreClock */
206
- rtt_init();
207
- rtt_printf(RTT_LEVEL_INFO, "boot: sysclk=%lu", (unsigned long)SystemCoreClock);
208
- /* USER CODE END 2 */
209
- ```
210
-
211
- (`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:
212
-
213
- ```powershell
214
- arm-none-eabi-nm build/Debug/<project>.elf | findstr _SEGGER_RTT
215
- ```
216
-
217
- Then have the model run these three steps (three `stm32_rtt` tool calls, arguments named as in the tool schema):
218
-
219
- ```text
220
- stm32_rtt action=start addr=0x20000DE0 # control block address from the nm line above
221
- stm32_rtt action=dump seconds=3 level=3 # 3 s of info and above
222
- stm32_rtt action=stop # releases the port; also runs at turn end
223
- ```
224
-
225
- 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.
226
-
227
- ## Slash commands
228
-
229
- Tools are for the model; when you want to act yourself, use a command — one command, one action, no model decision in between.
230
-
231
- | Command | What it does | Touches the board |
232
- | --- | --- | --- |
233
- | `/stm32-doctor` | Health check: toolchain, busy debug processes, ports, `.elf`, `.ioc` warnings | No |
234
- | `/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 |
235
- | `/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 |
236
- | `/stm32-build [dir] [--clean]` | Build, printing memory usage / `.elf` / errors | No |
237
- | `/stm32-flash [dir]` | **Flash**: program + verify + reset, no debug session, no breakpoints | Yes |
238
- | `/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 |
239
- | `/stm32-stop` | Closes the session opened by `/stm32-debug` and hands the probe back to VS Code | No |
240
-
241
- `[dir]` defaults to the current session's working directory.
242
-
243
- ## Design notes
244
-
245
- - **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".
246
- - **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.
247
- - **`.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.
248
- - **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.
249
- - **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.
250
-
251
- ## Chips, linker scripts and clocks
252
-
253
- - **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 goes through `src/data/stm32f1.ts` (`resolveF1Chip()`, 14 density grades, every startup file pinned by upstream sha256). An unknown part returns a reason instead of inventing a startup file that does not exist upstream.
254
- - **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).
255
- - **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**.
256
- - **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".
257
- ## Configuration
258
-
259
- ### User config file (`~/.dsh-stm32/config.json`)
260
-
261
- 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:
262
-
263
- ```json
264
- {
265
- "version": 1,
266
- "msys64": "E:/msys64",
267
- "binDirs": [],
268
- "packages": ["mingw-w64-ucrt-x86_64-arm-none-eabi-gcc", "mingw-w64-ucrt-x86_64-cmake"],
269
- "cubeMxRoot": "",
270
- "updatedAt": "2026-02-01T00:00:00.000Z"
271
- }
272
- ```
273
-
274
- 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".
275
-
276
- **Precedence**: tool arguments (`binDirs` / `cubeMxRoots`) > environment variables > this config file > built-in defaults; auto-discovered installs are only appended when no argument was given.
277
-
278
- ### Settings panel (GUI)
279
-
280
- 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:
281
-
282
- - **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;
283
- - **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);
284
- - **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.
285
-
286
- 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.
287
-
288
- ### Download cache (register-route template)
289
-
290
- 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:
291
-
292
- - Location: `DSH_STM32_CACHE` (supports `~`) > `%LOCALAPPDATA%\dsh-stm32\cache`;
293
- - Index: `index.json` under the cache root records each entry's source URLs, byte counts and license (`THIRD_PARTY_NOTICES.md` is written alongside);
294
- - 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;
295
- - 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;
296
- - Visible and removable: `stm32_cache` with `list` / `verify` / `fetch` / `purge`.
297
-
298
- ### Firmware packages (HAL route)
299
-
300
- 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:
301
-
302
- - 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;
303
- - 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;
304
-
305
- Fallback channel (GitHub assembly):
306
-
307
- - 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;
308
- - 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);
309
- - 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;
310
- - 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`;
311
- - The assembled package matches the official layout: a six-line `package.xml` (version tags `FW.<family>.<x.y.z>`) and `THIRD_PARTY_NOTICES.md`, with **no manifest or hashes** — CubeMX does not verify provenance either (measured: generating with `setCustomFWPath` copies HAL sources byte-for-byte out of our directory);
312
- - 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.
313
-
314
- ### Environment variables (optional)
315
-
316
- | Variable | Purpose | Default |
317
- | --- | --- | --- |
318
- | `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` |
319
- | `STM32_CUBEMX_ROOT` | STM32CubeMX installation root; **replaces** the built-in list | `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` |
320
- | `STM32_NO_DISCOVER` | Set to `1` / `true` to turn auto-discovery off (CI, or when you only want the built-in list) | unset = on |
321
- | `DSH_STM32_CONFIG` | Point the config file elsewhere (several toolchains / project isolation) | `%USERPROFILE%\.dsh-stm32\config.json` |
322
- | `DSH_STM32_NO_CONFIG` | Set to `1` / `true` to ignore the config file entirely (environment variables only) | unset = read |
323
- | `DSH_STM32_CACHE` | Download cache root (register-route template etc.), supports `~` | `%LOCALAPPDATA%\dsh-stm32\cache` |
324
- | `DSH_STM32_E2E_PROJECT` | Project used by hardware e2e runs (with `openocd.cfg` and `build/Debug/*.elf`) | none |
325
- | `DSH_STM32_E2E_ROOT` | Scratch directory for e2e copies | system temp |
326
-
327
- Per-call arguments work too: flash/debug tools accept `binDirs`, `elfPath`, `buildDir`, `configFile`, `adapterSpeed`; generate/create accept `cubeMxRoots`, `firmwarePackage`.
328
-
329
- **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:
330
-
331
- - 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`).
332
- - 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).
333
-
334
- 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.
335
-
336
- ### openocd.cfg (in the project, takes precedence over built-in fallbacks)
337
-
338
- CMSIS-DAP (default):
339
-
340
- ```text
341
- source [find interface/cmsis-dap.cfg]
342
- source [find target/stm32f1x.cfg]
343
- adapter speed 4000
344
- ```
345
-
346
- ST-Link (swap in your probe):
347
-
348
- ```text
349
- source [find interface/stlink.cfg]
350
- transport select hla_swd
351
- source [find target/stm32f1x.cfg]
352
- ```
353
-
354
- 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`).
355
- 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`.
356
-
357
- ### Two hard requirements on the .ioc
358
-
359
- 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`.
360
- 2. **`ProjectManager.KeepUserCode=true`**; otherwise USER CODE is not preserved when regenerating.
361
-
362
- ## Known limitations
363
-
364
- | Limitation | Detail | Workaround |
365
- | --- | --- | --- |
366
- | 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 |
367
- | **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** |
368
- | 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 13 families. **.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 |
369
- | 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` |
370
- | 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` |
371
- | Generation/scaffolding needs **CubeMX + the F1 firmware package** | Package version defaults to `STM32Cube_FW_F1_V1.8.7` | Pass another version via `firmwarePackage` |
372
- | 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 |
373
- | **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 |
374
- | 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 |
375
-
376
- ## Troubleshooting
377
-
378
- | Symptom | Cause and fix |
379
- | --- | --- |
380
- | `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 |
381
- | 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 |
382
- | `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 |
383
- | 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` |
384
- | 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 |
385
- | 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) |
386
- | 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 |
387
- | `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 |
388
- | `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 |
389
- | 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` |
390
- | 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 |
391
- | 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) |
392
- | `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 |
393
-
394
- ## Development and testing
395
-
396
- ```powershell
397
- npm run build # tsc -> lib/ (lib/ is committed: rebuild before you commit)
398
- npm test # 43 offline suites, 736 cases; no board, CubeMX, or toolchain needed
399
- npm run test:pack # pack a tarball, unpack it, scaffold a real register project from the unpacked lib
400
- npm run test:size # package guard: tarball <=1.2 MB, runtime assets under templates/ (.ioc/.xml/.ld/.json/.cfg) <=40 KB, no binaries/diagrams inside
401
- ```
402
-
403
- 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).
404
-
405
- 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 **736 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.
406
-
407
- ### What ships where (decide before you add a file)
408
-
409
- | Where | What | Size |
410
- | --- | --- | --- |
411
- | npm tarball | `lib/**` (including `lib/client.js`), `client/client.js`, `templates/scaffold/**`, `assets/**`, `cordis.patch.yml`, both READMEs, `LICENSE`, `docs/*.md` | 265 files / 1750.3 KB packed, 14901.3 KB unpacked; `assets/**` is 12.5 MB of source (headers compress well) |
412
- | 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` |
413
- | Bundled (npm package) | Device-facts layer (13 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 |
414
- | 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` |
415
- | Rendered on the spot | `.ioc` content (`renderIoc`), `.ld` MEMORY (`renderLinkerScript`), the cmake source list | rendered per part, never stored as a template |
416
-
417
- The guard is `scripts/pack-size.mjs` (`npm run test:size`): tarball ≤ 4 MB (4 000 000 B; 1.76 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.
418
-
419
- Hardware e2e writes to the board and needs a project you point it at:
420
-
421
- ```powershell
422
- $env:DSH_STM32_E2E_PROJECT = 'D:\work\my-stm32'
423
- node test\e2e-flash.mjs
424
- ```
425
-
426
- See the [development notes](docs/development-notes.md) for the suite breakdown and what each script covers.
427
-
428
- ## Repository layout
429
-
430
- ```text
431
- src/
432
- index.ts plugin entry (name / inject / apply)
433
- tools/ the 23 tools, L3 (parameter schema + output contract + rendering)
434
- engine/ pure logic and workflows (generate / build / flash / debug / ioc / scaffold …)
435
- commands/register.ts the 7 slash commands
436
- skill/stm32-workflow.ts the SKILL shipped with the plugin
437
- data/ paths and chip data (paths are data, not logic)
438
- templates/scaffold/ project template snapshot (CMake / .ld / .vscode / .ioc)
439
- test/ offline suites (36, registered in run-units) + fixtures + hardware e2e
440
- scripts/ guards and generators (pack-size / pack-smoke / gen-xcube-catalog / copy-client)
441
- docs/ specification + development notes + reading guide + diagrams/ (not packed)
442
- ```
443
-
444
- ## Documentation
445
-
446
- - [Specification](docs/dsh-stm32-plugin-规格.md): tool contracts, state machine, acceptance criteria A1–A13
447
- - [Development notes](docs/development-notes.md): milestones, host-contract pitfalls, implementation details and measured numbers
448
- - [Source reading guide](docs/reading-guide.md): layered reading order, per-file responsibilities and exports, 14 flow diagrams, 23 invariants
449
- - Visuals: [architecture](docs/diagrams/dsh-stm32-architecture.html) / [main journey](docs/diagrams/dsh-stm32-journey.html) — single-file HTML, opens offline, exports PNG/SVG
450
-
451
- ## License
452
-
453
- [MIT](LICENSE)
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)