dsh-stm32 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +127 -29
- package/README_EN.md +125 -29
- package/client/client.js +682 -0
- package/docs/development-notes.md +1385 -5
- package/docs/logic-audit.md +607 -0
- package/docs/reading-guide.md +738 -0
- package/lib/client.js +682 -0
- package/lib/commands/register.js +214 -12
- package/lib/data/chips.js +134 -4
- package/lib/data/clock-f1.js +158 -0
- package/lib/data/cmsis-sources.js +316 -0
- package/lib/data/f1-ram.generated.js +34 -0
- package/lib/data/firmware-packages.js +352 -0
- package/lib/data/install-guides.js +190 -0
- package/lib/data/search-roots.js +135 -15
- package/lib/data/stm32f1.js +186 -0
- package/lib/data/toolchain-config.js +310 -0
- package/lib/engine/build.js +121 -16
- package/lib/engine/cache.js +336 -0
- package/lib/engine/clock-plan.js +608 -0
- package/lib/engine/cmake-sources.js +428 -0
- package/lib/engine/code-patch.js +18 -6
- package/lib/engine/debug-session.js +163 -4
- package/lib/engine/debug.js +84 -19
- package/lib/engine/doctor.js +395 -4
- package/lib/engine/fetch.js +287 -0
- package/lib/engine/firmware-install.js +668 -0
- package/lib/engine/flash.js +145 -15
- package/lib/engine/fs-longpath.js +107 -0
- package/lib/engine/generate-cache.js +118 -0
- package/lib/engine/generate-script.js +30 -8
- package/lib/engine/generate.js +296 -14
- package/lib/engine/hal-chip.js +230 -0
- package/lib/engine/ioc-plan.js +47 -8
- package/lib/engine/msys2-install.js +1870 -0
- package/lib/engine/probe.js +57 -6
- package/lib/engine/project-export.js +129 -0
- package/lib/engine/register-clock.js +132 -0
- package/lib/engine/register-linker.js +129 -0
- package/lib/engine/register-template.js +449 -0
- package/lib/engine/regs.js +18 -4
- package/lib/engine/route-plan.js +553 -0
- package/lib/engine/scaffold.js +303 -72
- package/lib/engine/subprocess-runner.js +2 -0
- package/lib/engine/tar.js +250 -0
- package/lib/engine/text-file.js +150 -0
- package/lib/engine/thirdparty.js +243 -0
- package/lib/engine/tool-env.js +51 -0
- package/lib/engine/toolchain-gate.js +386 -0
- package/lib/engine/vscode-config.js +99 -0
- package/lib/engine/web-api.js +375 -0
- package/lib/engine/web-routes.js +100 -0
- package/lib/engine/xcube-catalog.js +102 -0
- package/lib/engine/xcube.js +254 -0
- package/lib/engine/zip.js +142 -0
- package/lib/index.js +44 -2
- package/lib/skill/stm32-workflow.js +3 -3
- package/lib/tools/build.js +55 -3
- package/lib/tools/cache.js +250 -0
- package/lib/tools/code-patch.js +29 -2
- package/lib/tools/debug-session.js +56 -14
- package/lib/tools/debug.js +43 -2
- package/lib/tools/doctor.js +16 -3
- package/lib/tools/env-install.js +472 -0
- package/lib/tools/env-probe.js +6 -2
- package/lib/tools/firmware-install.js +255 -0
- package/lib/tools/flash.js +41 -2
- package/lib/tools/generate.js +96 -10
- package/lib/tools/ioc-apply.js +27 -11
- package/lib/tools/ioc-inspect.js +4 -2
- package/lib/tools/ioc-plan.js +209 -11
- package/lib/tools/project-create.js +229 -21
- package/lib/tools/project-dir.js +95 -0
- package/lib/tools/project-export.js +100 -0
- package/lib/tools/regs.js +82 -7
- package/lib/tools/route-plan.js +467 -0
- package/package.json +11 -4
- package/templates/register/CMakeLists.txt +52 -0
- package/templates/register/Core/Src/main.c +72 -0
- package/templates/scaffold/openocd.cfg +8 -0
- package/templates/scaffold/vscode/launch.json +8 -6
- package/templates/scaffold/vscode/settings.json +5 -11
package/README_EN.md
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
# dsh-stm32
|
|
2
2
|
|
|
3
|
-
> Hand the whole
|
|
3
|
+
> Hand the whole **STM32F1 family** (F100/101/102/103/105/107) development chain to DSH: probe the toolchain → scaffold a project → edit the .ioc (clocks included) → generate code → build → debug → flash.
|
|
4
4
|
|
|
5
5
|
[中文](./README.md) · [Quick start](#quick-start-a-minimal-end-to-end-check-empty-directory-to-a-blinking-led) · [Features](#features) · [Tool reference](#tool-reference) · [Slash commands](#slash-commands) · [Design notes](#design-notes) · [Known limitations](#known-limitations) · [Troubleshooting](#troubleshooting) · [Specification](docs/dsh-stm32-plugin-规格.md)
|
|
6
6
|
|
|
7
7
|
[](https://github.com/JingYu-er/dsh-stm32)
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
[](#known-limitations)
|
|
10
|
-
[](#known-limitations)
|
|
11
|
+
[](https://github.com/JingYu-er/dsh-stm32/releases)
|
|
12
12
|
|
|
13
|
-
A [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **plugin** (host-side, no UI): it registers
|
|
13
|
+
A [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) **plugin** (host-side, no UI): it registers 20 tools, 7 slash commands and 1 SKILL shipped with the plugin, so the model can probe the toolchain, scaffold a CubeMX CMake project, edit the `.ioc`, run CubeMX, build, flash and debug on its own, then read the state back out of the registers — hardware programming that actually stays inside DSH.
|
|
14
14
|
|
|
15
15
|
## Why you need it
|
|
16
16
|
|
|
@@ -45,7 +45,7 @@ That is what "hardware programming inside DSH" means here: **the model does not
|
|
|
45
45
|
| STM32CubeMX (with its bundled JRE) | `stm32_generate`, `stm32_project_create` | Generation tools unavailable, everything else still works |
|
|
46
46
|
| STM32Cube firmware package F1 (installed with CubeMX) | Drivers copied when scaffolding | "Firmware package not found" |
|
|
47
47
|
|
|
48
|
-
Paths are searched as MSYS2 (`
|
|
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
49
|
|
|
50
50
|
### Install (recommended: one command)
|
|
51
51
|
|
|
@@ -55,7 +55,7 @@ dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main
|
|
|
55
55
|
|
|
56
56
|
All `dsh plugin` does is run `pnpm add` inside the profile directory. On success it also appends `dsh-stm32` to that profile's `dsh.profile.bundles`, so a restart of dsh is all that is left (use `web` instead of `desktop` to target the web profile).
|
|
57
57
|
|
|
58
|
-
Verify with `dsh plugin --profile desktop why dsh-stm32` (should print `0.1.
|
|
58
|
+
Verify with `dsh plugin --profile desktop why dsh-stm32` (should print `0.1.2`); after a restart `/stm32-doctor` should respond.
|
|
59
59
|
|
|
60
60
|
|
|
61
61
|
**Uninstall**: `dsh plugin --profile desktop remove dsh-stm32`, then restart dsh.
|
|
@@ -67,7 +67,9 @@ git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
|
67
67
|
cd dsh-stm32
|
|
68
68
|
npm install --no-audit --no-fund # typescript only
|
|
69
69
|
npm run build # tsc -> lib/ (required before committing)
|
|
70
|
-
npm test # optional:
|
|
70
|
+
npm test # optional: 418 offline cases in 29 suites, no board needed
|
|
71
|
+
npm run test:pack # pack a tarball, unpack it, scaffold a real register project from it
|
|
72
|
+
npm run test:size # package guard: tarball <=1.2 MB, templates <=60 KB, no binaries/diagrams inside
|
|
71
73
|
```
|
|
72
74
|
|
|
73
75
|
Link it into your dsh profile — **while editing code use `link:`, never `file:`**:
|
|
@@ -90,7 +92,7 @@ This chain ran on a real board (acceptance A1, 2026-10-22), driven entirely by t
|
|
|
90
92
|
| --- | --- | --- | --- |
|
|
91
93
|
| 1 | Health check: toolchain, busy probes, ports, `.elf`, `.ioc` warnings | `stm32_doctor` | ~2 s |
|
|
92
94
|
| 2 | Empty directory → CMake project skeleton (14 template files + 629 firmware files + an `.ioc` with SWD configured) | `stm32_project_create` | ~2 s |
|
|
93
|
-
| 3 | Headless CubeMX run driven by the `.ioc`, output placed under `Core/` | `stm32_generate` |
|
|
95
|
+
| 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 |
|
|
94
96
|
| 4 | Build (first run configures with `cmake --preset`) | `stm32_build` | ~5 s configure + 3 s build |
|
|
95
97
|
| 5 | **Flash only**: program + verify + reset | `stm32_flash` | 2.1–2.6 s |
|
|
96
98
|
| 6 | Read `GPIOC_ODR` back to confirm the state really toggles | `stm32_regs_read` | 0.4–1.3 s |
|
|
@@ -99,10 +101,12 @@ On the model side it is one sentence: "create a blinking-LED project for STM32F1
|
|
|
99
101
|
|
|
100
102
|
```text
|
|
101
103
|
/stm32-doctor # health check before you start
|
|
104
|
+
/stm32-env # what each capability is missing (works even when incomplete)
|
|
102
105
|
/stm32-build # build, print memory usage and errors
|
|
103
106
|
/stm32-flash # flash only, no debug session
|
|
104
107
|
/stm32-debug # flash + halt at main
|
|
105
108
|
/stm32-stop # close the debug session, hand the probe back to VS Code
|
|
109
|
+
/stm32-setup # health check + install plan (the word "install" in the command actually installs)
|
|
106
110
|
```
|
|
107
111
|
|
|
108
112
|
### This is a minimal check, not the ceiling
|
|
@@ -119,19 +123,23 @@ The blinking LED is the **smallest smoke test** for this chain: it walks create
|
|
|
119
123
|
| Confirm a peripheral is really running after flashing | `stm32_regs_read` reads any peripheral register (`TIM2_CNT`, `USART1_SR`, `ADC1_DR` …), or `stm32_debug_eval` reads a variable | Reading registers by physical address verified (`GPIOC_ODR` / `AFIO_MAPR`) |
|
|
120
124
|
| 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`) |
|
|
121
125
|
|
|
122
|
-
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) —
|
|
126
|
+
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.
|
|
123
127
|
|
|
124
128
|
## Features
|
|
125
129
|
|
|
126
130
|
| Capability | How it is provided |
|
|
127
131
|
| --- | --- |
|
|
128
132
|
| Environment health check | `stm32_env_probe` (read-only), `stm32_doctor` (toolchain + busy probes + ports + project warnings) |
|
|
129
|
-
|
|
|
133
|
+
| Pre-flight gate | Every tool that needs the toolchain runs `ensureToolchain` first: missing pieces are refused up front with what to install and what stops working; `envCheck: "block"` (default) / `"warn"` / `"off"` |
|
|
134
|
+
| Install the toolchain | `stm32_env_install`: plan first (what is downloaded, how large, which PATH entry changes), install only after you confirm — MSYS2 + 5 pacman packages + a **user-level** PATH entry, then it writes the config file itself |
|
|
135
|
+
| 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) |
|
|
136
|
+
| Project from scratch | `stm32_project_create`: `route: "hal"` uses the template snapshot + firmware Drivers (byte-identical to a CubeMX GUI project); `route: "register"` builds a register-level project with no CubeMX at all, pulling the CMSIS template into the cache on first use (every file is pinned by upstream sha256 and refused if it changed); `mcu` names the part (both routes accept it; the HAL route renders its startup file / device define / `<DeviceId>_FLASH.ld` from it); both routes also ship an `openocd.cfg` (CMSIS-DAP + `hla_swd` + 2 MHz) |
|
|
137
|
+
| 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 |
|
|
130
138
|
| `.ioc` as a transaction | `stm32_ioc_inspect` (read-only parse) → `stm32_ioc_plan` (diff, no writes) → `stm32_ioc_apply` (SHA check + backup + rollback) |
|
|
131
139
|
| USER CODE only | `stm32_code_patch`: writes only between `/* USER CODE BEGIN X */` and `END X`; everything else untouched |
|
|
132
140
|
| Code generation | `stm32_generate`: headless CubeMX + ST project layout + USER CODE carried over by label |
|
|
133
|
-
| Build | `stm32_build`: build directory and `.elf` inferred, deduplicated errors, RAM/FLASH usage parsed after linking |
|
|
134
|
-
| Flash | `stm32_flash`: openocd `program verify reset exit`, probe released afterwards; checks that the `.ioc` has Serial Wire enabled |
|
|
141
|
+
| Build | `stm32_build`: build directory and `.elf` inferred, deduplicated errors, RAM/FLASH usage parsed after linking; ask for `artifacts: ["hex","bin"]` and the same toolchain's `arm-none-eabi-objcopy` produces them |
|
|
142
|
+
| Flash | `stm32_flash`: openocd `program verify reset exit`, probe released afterwards; checks that the `.ioc` has Serial Wire enabled; failures carry an `errorCode` (`no-probe` / `probe-busy` / `swd-locked` …) |
|
|
135
143
|
| Debug | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
|
|
136
144
|
| Prove it is running | `stm32_regs_read`: reads any peripheral register back by physical address, halts, reads, then `resume` — no chip reset |
|
|
137
145
|
| 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) |
|
|
@@ -143,15 +151,20 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
143
151
|
| Tool | What it does |
|
|
144
152
|
| --- | --- |
|
|
145
153
|
| `stm32_env_probe` | 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 |
|
|
154
|
+
| `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 |
|
|
155
|
+
| `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 |
|
|
146
156
|
| `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 |
|
|
147
|
-
| `stm32_project_create` | Empty directory → full CMake project (including both "flash only" and "flash and debug" launch configs in `.vscode`). Refuses a non-empty target unless `overwrite: true` |
|
|
157
|
+
| `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` |
|
|
158
|
+
| `stm32_cache` | Inspect / verify / fetch / purge the download cache: `action: "list"` (default), `"verify"` (per-file check), `"fetch"` (pull the template for an `mcu`, reusing the cache without touching the network), `"purge"` (drop entries; clears everything without an `id`). The cache holds what the register route needs but the plugin does not ship — CMSIS device headers, startup file, core headers — downloaded once, reused forever |
|
|
159
|
+
| `stm32_project_export` | Hands the project to someone else as one zip: sources, CMake, `.vscode` and the `.ioc` by default, skipping `build/`, `.dsh-stm32/`, `node_modules/`, `.git/`; `includePrebuilt: true` also packs the `.elf`, `readme: false` skips the in-archive README, `outDir` moves the output (default `<name>-export.zip` next to the project) |
|
|
160
|
+
| `stm32_firmware_install` | One-stop firmware-package install: `dryRun` (default) returns only the plan — where it would land, which two source repos it would download, which checks must pass; `dryRun: false` + `confirm: true` actually downloads (HAL driver + CMSIS device support + core headers, ~2 MB total from GitHub), assembles an official-shaped `STM32Cube_FW_<family>_V<version>` package (writing `package.xml` itself) and runs five checks. Does nothing when the official package is already installed; installs into `<CubeMX root>/dsh-firmware` by default (not `Repository` — a self-made version there is silently ignored), and `stm32_generate` points CubeMX at it with `setCustomFWPath` |
|
|
148
161
|
|
|
149
162
|
### .ioc: read-only and transactions
|
|
150
163
|
|
|
151
164
|
| Tool | What it does |
|
|
152
165
|
| --- | --- |
|
|
153
166
|
| `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`" |
|
|
154
|
-
| `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,
|
|
167
|
+
| `stm32_ioc_plan` | Step one of any `.ioc` change: computes a per-key diff plus the source SHA-256 and returns a `planId`, **without touching the source**. Supports setting/removing keys, adding GPIO from the chip pin table, one-shot Serial Wire repair, and retargeting clocks to the nearest reachable frequency (`clock: { targetHz }`, derived keys recomputed, per-peripheral frequencies reported) |
|
|
155
168
|
| `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` |
|
|
156
169
|
|
|
157
170
|
### Code and build
|
|
@@ -159,14 +172,14 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
159
172
|
| Tool | What it does |
|
|
160
173
|
| --- | --- |
|
|
161
174
|
| `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 |
|
|
162
|
-
| `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 |
|
|
163
|
-
| `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 |
|
|
175
|
+
| `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 |
|
|
176
|
+
| `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 |
|
|
164
177
|
|
|
165
178
|
### Flash and debug
|
|
166
179
|
|
|
167
180
|
| Tool | What it does |
|
|
168
181
|
| --- | --- |
|
|
169
|
-
| `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)) |
|
|
182
|
+
| `stm32_flash` | **Flash**: openocd `program verify reset exit`, no debug session, no halt at `main`. Reads the `.ioc` first and refuses when the debug port is disabled (see [Design notes](#design-notes)). Failures carry an `errorCode` (`no-probe` / `probe-busy` / `swd-locked` / `flash-protected` / `no-power` / `target-mismatch` / `unknown`), and when no device is found the USB shape (no USB on this machine / probe unplugged / driver problem) is added to the notes |
|
|
170
183
|
| `stm32_debug_run` | Starts openocd + gdb, `break main` → `continue` → captures pc/sp/lr/bt/locals → `reset run` + `detach`; no Flash write, nothing left running |
|
|
171
184
|
| `stm32_debug_session` | Long-lived openocd session (`.elf` resolved automatically), closed after 90 s idle, hard limit 10 min |
|
|
172
185
|
| `stm32_debug_eval` | Runs gdb commands or reads expressions (e.g. `g_led_blink_count`) inside the session, then `resume` + `detach` immediately |
|
|
@@ -180,6 +193,8 @@ Tools are for the model; when you want to act yourself, use a command — one co
|
|
|
180
193
|
| Command | What it does | Touches the board |
|
|
181
194
|
| --- | --- | --- |
|
|
182
195
|
| `/stm32-doctor` | Health check: toolchain, busy debug processes, ports, `.elf`, `.ioc` warnings | No |
|
|
196
|
+
| `/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 |
|
|
197
|
+
| `/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 |
|
|
183
198
|
| `/stm32-build [dir] [--clean]` | Build, printing memory usage / `.elf` / errors | No |
|
|
184
199
|
| `/stm32-flash [dir]` | **Flash**: program + verify + reset, no debug session, no breakpoints | Yes |
|
|
185
200
|
| `/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 |
|
|
@@ -195,15 +210,74 @@ Tools are for the model; when you want to act yourself, use a command — one co
|
|
|
195
210
|
- **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.
|
|
196
211
|
- **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.
|
|
197
212
|
|
|
213
|
+
## Chips, linker scripts and clocks
|
|
214
|
+
|
|
215
|
+
- **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.
|
|
216
|
+
- **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).
|
|
217
|
+
- **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**.
|
|
218
|
+
- **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".
|
|
198
219
|
## Configuration
|
|
199
220
|
|
|
221
|
+
### User config file (`~/.dsh-stm32/config.json`)
|
|
222
|
+
|
|
223
|
+
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:
|
|
224
|
+
|
|
225
|
+
```json
|
|
226
|
+
{
|
|
227
|
+
"version": 1,
|
|
228
|
+
"msys64": "E:/msys64",
|
|
229
|
+
"binDirs": [],
|
|
230
|
+
"packages": ["mingw-w64-ucrt-x86_64-arm-none-eabi-gcc", "mingw-w64-ucrt-x86_64-cmake"],
|
|
231
|
+
"cubeMxRoot": "",
|
|
232
|
+
"updatedAt": "2026-02-01T00:00:00.000Z"
|
|
233
|
+
}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
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".
|
|
237
|
+
|
|
238
|
+
**Precedence**: tool arguments (`binDirs` / `cubeMxRoots`) > environment variables > this config file > built-in defaults; auto-discovered installs are only appended when no argument was given.
|
|
239
|
+
|
|
240
|
+
### Settings panel (GUI)
|
|
241
|
+
|
|
242
|
+
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:
|
|
243
|
+
|
|
244
|
+
- **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;
|
|
245
|
+
- **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);
|
|
246
|
+
- **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.
|
|
247
|
+
|
|
248
|
+
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.
|
|
249
|
+
|
|
250
|
+
### Download cache (register-route template)
|
|
251
|
+
|
|
252
|
+
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:
|
|
253
|
+
|
|
254
|
+
- Location: `DSH_STM32_CACHE` (supports `~`) > `%LOCALAPPDATA%\dsh-stm32\cache`;
|
|
255
|
+
- Index: `index.json` under the cache root records each entry's source URLs, byte counts and license (`THIRD_PARTY_NOTICES.md` is written alongside);
|
|
256
|
+
- 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;
|
|
257
|
+
- 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;
|
|
258
|
+
- Visible and removable: `stm32_cache` with `list` / `verify` / `fetch` / `purge`.
|
|
259
|
+
|
|
260
|
+
### Firmware packages (HAL route)
|
|
261
|
+
|
|
262
|
+
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. For the families the plugin can fetch, `stm32_firmware_install` assembles it from two GitHub source archives:
|
|
263
|
+
|
|
264
|
+
- 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;
|
|
265
|
+
- 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);
|
|
266
|
+
- 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;
|
|
267
|
+
- 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`;
|
|
268
|
+
- 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);
|
|
269
|
+
- 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.
|
|
270
|
+
|
|
200
271
|
### Environment variables (optional)
|
|
201
272
|
|
|
202
273
|
| Variable | Purpose | Default |
|
|
203
274
|
| --- | --- | --- |
|
|
204
|
-
| `STM32_BIN_DIRS` | Toolchain directory candidates, `;`-separated; **replaces** the built-in list (auto-discovered dirs are still appended after it) | `
|
|
205
|
-
| `STM32_CUBEMX_ROOT` | STM32CubeMX installation root; **replaces** the built-in list | `
|
|
275
|
+
| `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` |
|
|
276
|
+
| `STM32_CUBEMX_ROOT` | STM32CubeMX installation root; **replaces** the built-in list | `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` |
|
|
206
277
|
| `STM32_NO_DISCOVER` | Set to `1` / `true` to turn auto-discovery off (CI, or when you only want the built-in list) | unset = on |
|
|
278
|
+
| `DSH_STM32_CONFIG` | Point the config file elsewhere (several toolchains / project isolation) | `%USERPROFILE%\.dsh-stm32\config.json` |
|
|
279
|
+
| `DSH_STM32_NO_CONFIG` | Set to `1` / `true` to ignore the config file entirely (environment variables only) | unset = read |
|
|
280
|
+
| `DSH_STM32_CACHE` | Download cache root (register-route template etc.), supports `~` | `%LOCALAPPDATA%\dsh-stm32\cache` |
|
|
207
281
|
| `DSH_STM32_E2E_PROJECT` | Project used by hardware e2e runs (with `openocd.cfg` and `build/Debug/*.elf`) | none |
|
|
208
282
|
| `DSH_STM32_E2E_ROOT` | Scratch directory for e2e copies | system temp |
|
|
209
283
|
|
|
@@ -246,7 +320,7 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
|
|
|
246
320
|
| Limitation | Detail | Workaround |
|
|
247
321
|
| --- | --- | --- |
|
|
248
322
|
| 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 |
|
|
249
|
-
| **
|
|
323
|
+
| **STM32F1 family** only | The part → startup file / device define / linker script maps exist for F1 only (`src/data/stm32f1.ts` + `src/engine/hal-chip.ts`, 14 density grades); the clock tree knows F1 only (HSE 8 MHz, PLL ×2..×16, SYSCLK ≤72 MHz) | Another family needs real repo names plus per-file measured sha256 (`src/data/cmsis-sources.ts`, `src/data/firmware-packages.ts`) and a clock-limit table; the pin table itself can be derived from the local CubeMX `db/mcu/*.xml` (`deriveChipPinTable`) |
|
|
250
324
|
| Default probe is **CMSIS-DAP** | Falls back to cmsis-dap without an `openocd.cfg` | Put `interface/stlink.cfg` into `openocd.cfg` (see above) |
|
|
251
325
|
| 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` |
|
|
252
326
|
| Generation/scaffolding needs **CubeMX + the F1 firmware package** | Package version defaults to `STM32Cube_FW_F1_V1.8.7` | Pass another version via `firmwarePackage` |
|
|
@@ -256,23 +330,42 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
|
|
|
256
330
|
|
|
257
331
|
| Symptom | Cause and fix |
|
|
258
332
|
| --- | --- |
|
|
333
|
+
| `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 |
|
|
259
334
|
| 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 |
|
|
260
|
-
| `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 |
|
|
335
|
+
| `Error: No device found` / `transfer count mismatch` | Another process holds the probe. Run `/stm32-stop`, then use `stm32_doctor` to inspect openocd / gdb processes and port 3333. Reading registers while a debug session is open no longer hits this: `stm32_regs_read` reuses the session's openocd instead of starting a second one |
|
|
336
|
+
| Reading registers with a live session shows a `gdb-multiarch … target extended-remote 127.0.0.1:3333` `report.command` | That is the normal "reuse" shape: while `stm32_debug_session` is alive, `stm32_regs_read` drives the session's own gdb connection with `print/x $pc` and `print/x *(unsigned int *)0x…`, then `monitor resume` and detach; the first note reads "reusing the openocd of the debug session (port N), not starting another". Only without a session does it start its own openocd. Older builds failed here with `CMSIS-DAP transfer count mismatch: expected N, got M` |
|
|
261
337
|
| Build "succeeds" but the old firmware runs | The project was copied or renamed with `build/` included: the CMakeCache directory no longer matches, yet ninja still exits 0. `stm32_build` treats that as a failure; clean or delete `build/Debug` as prompted |
|
|
338
|
+
| 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) |
|
|
262
339
|
| `stm32_doctor` cannot find gcc / openocd | First read the "searched ..." list and the auto-discovery line in the doctor notes / error; if it is installed elsewhere, set `STM32_BIN_DIRS` or pass `binDirs`. **If you do not know what to install, run `stm32_env_probe` first**: every missing component carries `impact` (what stops working), `install` (recommended way, easiest first) and `verify` (self-check after installing), while the top-level `recommendations` gives the install order and offers to install for you |
|
|
263
|
-
| `stm32_generate` feels stuck |
|
|
340
|
+
| `stm32_generate` feels stuck | The first run (cold start, no cache) legitimately takes 3.5–4 minutes; later runs are skipped (<1 s) while the `.ioc` and outputs are unchanged. It runs as a background job by default — watch it with `job_output`, or pass `foreground: true`. Check `skipped` in the result and the reason in the notes to see whether the cache hit |
|
|
341
|
+
| 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` |
|
|
342
|
+
| 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 |
|
|
343
|
+
| 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) |
|
|
264
344
|
| `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 |
|
|
265
345
|
|
|
266
346
|
## Development and testing
|
|
267
347
|
|
|
268
348
|
```powershell
|
|
269
349
|
npm run build # tsc -> lib/ (lib/ is committed: rebuild before you commit)
|
|
270
|
-
npm test #
|
|
350
|
+
npm test # 29 offline suites, 418 cases; no board, CubeMX, or toolchain needed
|
|
351
|
+
npm run test:pack # pack a tarball, unpack it, scaffold a real register project from the unpacked lib
|
|
352
|
+
npm run test:size # package guard: tarball <=1.2 MB, templates <=60 KB, no binaries/diagrams inside
|
|
271
353
|
```
|
|
272
354
|
|
|
273
|
-
CI (`.github/workflows/ci.yml`) runs `npm ci → build → check that the committed lib/ matches src/ → npm test` on every push and PR (windows-latest).
|
|
355
|
+
CI (`.github/workflows/ci.yml`) runs `npm ci → build → check that the committed lib/ matches src/ → npm test → test:pack → test:size` on every push and PR (windows-latest).
|
|
356
|
+
|
|
357
|
+
A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that need the real firmware package are skipped: CI reports **416 passed + 2 skipped**, while a developer machine runs all 418. The offline suites only read the bundled [`test/fixtures/`](test/fixtures/README.md); the session cases build a fake toolchain directory with `fakeBinDirs()` (empty placeholder files for openocd / gdb), so nothing depends on what is installed locally.
|
|
358
|
+
|
|
359
|
+
### What ships where (decide before you add a file)
|
|
360
|
+
|
|
361
|
+
| Where | What | Size |
|
|
362
|
+
| --- | --- | --- |
|
|
363
|
+
| npm tarball | `lib/**` (including `lib/client.js`), `client/client.js`, `templates/scaffold/**`, `cordis.patch.yml`, both READMEs, `LICENSE`, `docs/*.md` | 99 files / 525.7 KB packed, 1538.3 KB unpacked; `templates/**` alone is 38.5 KB |
|
|
364
|
+
| Git only, not packed | `src/**`, `test/**`, `scripts/**`, `docs/diagrams/**` (two interactive HTML pages) | diagrams are 2 MB raw / 891 KB gz; `files` in `package.json` narrows `docs` to `docs/*.md` |
|
|
365
|
+
| Downloaded on demand | CMSIS device headers / startup files / core headers (fetched into the cache on first use, pinned per file by sha256); HAL firmware packages | manage the cache with `stm32_cache list/verify/purge` |
|
|
366
|
+
| Rendered on the spot | `.ioc` content (`renderIoc`), `.ld` MEMORY (`renderLinkerScript`), the cmake source list | rendered per part, never stored as a template |
|
|
274
367
|
|
|
275
|
-
|
|
368
|
+
The guard is `scripts/pack-size.mjs` (`npm run test:size`): tarball ≤ 1.2 MB (1 200 000 B), `templates/**` ≤ 60 KB, no `.png/.jpg/.gif/.webp/.bmp/.pdf/.html/.zip/.7z/.exe/.dll` inside, and `README.md` / `README_EN.md` / `LICENSE` / `cordis.patch.yml` / `docs/reading-guide.md` all present.
|
|
276
369
|
|
|
277
370
|
Hardware e2e writes to the board and needs a project you point it at:
|
|
278
371
|
|
|
@@ -288,20 +381,23 @@ See the [development notes](docs/development-notes.md) for the suite breakdown a
|
|
|
288
381
|
```text
|
|
289
382
|
src/
|
|
290
383
|
index.ts plugin entry (name / inject / apply)
|
|
291
|
-
tools/ the
|
|
384
|
+
tools/ the 20 tools, L3 (parameter schema + output contract + rendering)
|
|
292
385
|
engine/ pure logic and workflows (generate / build / flash / debug / ioc / scaffold …)
|
|
293
|
-
commands/register.ts the
|
|
386
|
+
commands/register.ts the 7 slash commands
|
|
294
387
|
skill/stm32-workflow.ts the SKILL shipped with the plugin
|
|
295
388
|
data/ paths and chip data (paths are data, not logic)
|
|
296
389
|
templates/scaffold/ project template snapshot (CMake / .ld / .vscode / .ioc)
|
|
297
|
-
test/ offline suites + fixtures + hardware e2e
|
|
298
|
-
|
|
390
|
+
test/ offline suites (29) + fixtures + hardware e2e
|
|
391
|
+
scripts/ guards and generators (pack-size / pack-smoke / gen-chip-table / gen-xcube-catalog / copy-client)
|
|
392
|
+
docs/ specification + development notes + reading guide + diagrams/ (not packed)
|
|
299
393
|
```
|
|
300
394
|
|
|
301
395
|
## Documentation
|
|
302
396
|
|
|
303
397
|
- [Specification](docs/dsh-stm32-plugin-规格.md): tool contracts, state machine, acceptance criteria A1–A13
|
|
304
398
|
- [Development notes](docs/development-notes.md): milestones, host-contract pitfalls, implementation details and measured numbers
|
|
399
|
+
- [Source reading guide](docs/reading-guide.md): layered reading order, per-file responsibilities and exports, 14 flow diagrams, 20 invariants
|
|
400
|
+
- Visuals: [architecture](docs/diagrams/dsh-stm32-architecture.html) / [main journey](docs/diagrams/dsh-stm32-journey.html) — single-file HTML, opens offline, exports PNG/SVG
|
|
305
401
|
|
|
306
402
|
## License
|
|
307
403
|
|