dsh-stm32 0.1.1 → 0.1.3
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 +98 -31
- package/README_EN.md +96 -29
- package/docs/development-notes.md +837 -4
- package/docs/reading-guide.md +759 -0
- package/lib/commands/register.js +49 -0
- package/lib/data/chips.js +147 -30
- package/lib/data/clock-f1.js +158 -0
- package/lib/data/cmsis-sources.js +237 -42
- package/lib/data/device-facts.js +201 -0
- package/lib/data/stm32f1.js +130 -0
- package/lib/data/svd.js +627 -0
- package/lib/engine/assets.js +924 -0
- package/lib/engine/breakpoints.js +242 -0
- package/lib/engine/build.js +115 -16
- package/lib/engine/cache.js +56 -0
- package/lib/engine/clock-plan.js +608 -0
- package/lib/engine/cmake-sources.js +428 -0
- package/lib/engine/debug-session.js +153 -5
- package/lib/engine/debug.js +114 -15
- package/lib/engine/doctor.js +395 -4
- package/lib/engine/fetch.js +174 -30
- package/lib/engine/flash.js +70 -9
- package/lib/engine/generate.js +11 -0
- package/lib/engine/hal-chip.js +230 -0
- package/lib/engine/ioc-plan.js +33 -7
- package/lib/engine/msys2-install.js +332 -61
- package/lib/engine/probe-error.js +212 -0
- package/lib/engine/probe-session.js +311 -0
- 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 +115 -20
- package/lib/engine/regs.js +2 -0
- package/lib/engine/rtt.js +600 -0
- package/lib/engine/scaffold.js +104 -28
- package/lib/engine/zip.js +142 -0
- package/lib/index.js +10 -0
- package/lib/skill/stm32-workflow.js +3 -3
- package/lib/tools/assets.js +341 -0
- package/lib/tools/build.js +12 -0
- package/lib/tools/cache.js +47 -8
- package/lib/tools/debug-session.js +40 -5
- package/lib/tools/debug.js +41 -4
- package/lib/tools/doctor.js +22 -2
- package/lib/tools/flash.js +15 -3
- package/lib/tools/generate.js +3 -0
- package/lib/tools/ioc-apply.js +2 -0
- package/lib/tools/ioc-inspect.js +2 -0
- package/lib/tools/ioc-plan.js +198 -4
- package/lib/tools/project-create.js +50 -1
- package/lib/tools/project-export.js +100 -0
- package/lib/tools/regs.js +453 -61
- package/lib/tools/route-plan.js +3 -0
- package/lib/tools/rtt.js +347 -0
- package/package.json +5 -3
- package/templates/register/CMakeLists.txt +25 -6
- package/templates/register/Core/Inc/rtt.h +103 -0
- package/templates/register/Core/Src/main.c +43 -9
- package/templates/register/Core/Src/rtt.c +297 -0
- package/templates/scaffold/RTT.md +86 -0
- package/templates/scaffold/cmake/user/CMakeLists.txt +7 -0
- package/templates/scaffold/openocd.cfg +8 -0
package/README_EN.md
CHANGED
|
@@ -1,22 +1,22 @@
|
|
|
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 21 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
|
|
|
17
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
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 `
|
|
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
20
|
|
|
21
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
22
|
|
|
@@ -27,7 +27,7 @@ That is what "hardware programming inside DSH" means here: **the model does not
|
|
|
27
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
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
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: `
|
|
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
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
32
|
|
|
33
33
|
|
|
@@ -55,7 +55,9 @@ 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.3`); after a restart `/stm32-doctor` should respond.
|
|
59
|
+
|
|
60
|
+
> **First run needs one online download of the asset pack**: the plugin embeds no chip table. Device facts (part → startup file / device define / Flash·RAM size) are installed on first use by `stm32_assets` (`profile: "core"`, 30 files ≈ 237 KiB: chip table + memory layout + `.ioc` templates + linker scripts). After that the whole chain works offline; it only goes online again when the version changes.
|
|
59
61
|
|
|
60
62
|
|
|
61
63
|
**Uninstall**: `dsh plugin --profile desktop remove dsh-stm32`, then restart dsh.
|
|
@@ -67,7 +69,9 @@ git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
|
67
69
|
cd dsh-stm32
|
|
68
70
|
npm install --no-audit --no-fund # typescript only
|
|
69
71
|
npm run build # tsc -> lib/ (required before committing)
|
|
70
|
-
npm test # optional:
|
|
72
|
+
npm test # optional: 497 offline cases in 34 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, templates <=60 KB, no binaries/diagrams inside
|
|
71
75
|
```
|
|
72
76
|
|
|
73
77
|
Link it into your dsh profile — **while editing code use `link:`, never `file:`**:
|
|
@@ -93,7 +97,9 @@ This chain ran on a real board (acceptance A1, 2026-10-22), driven entirely by t
|
|
|
93
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 |
|
|
94
98
|
| 4 | Build (first run configures with `cmake --preset`) | `stm32_build` | ~5 s configure + 3 s build |
|
|
95
99
|
| 5 | **Flash only**: program + verify + reset | `stm32_flash` | 2.1–2.6 s |
|
|
96
|
-
| 6 | Read `
|
|
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 from the asset pack's `full` profile: `stm32_assets action="refresh" profile="full"` (128 files, of which 1.71 MiB is SVD). A `core`-only install still works — write the address `0x4001100C` instead, and the report has neither register names nor bit-field decoding.
|
|
97
103
|
|
|
98
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:
|
|
99
105
|
|
|
@@ -104,6 +110,7 @@ On the model side it is one sentence: "create a blinking-LED project for STM32F1
|
|
|
104
110
|
/stm32-flash # flash only, no debug session
|
|
105
111
|
/stm32-debug # flash + halt at main
|
|
106
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)
|
|
107
114
|
```
|
|
108
115
|
|
|
109
116
|
### This is a minimal check, not the ceiling
|
|
@@ -117,10 +124,10 @@ The blinking LED is the **smallest smoke test** for this chain: it walks create
|
|
|
117
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 |
|
|
118
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) |
|
|
119
126
|
| Tuning parameters, changing clocks | `.ioc` transactions: diff first → SHA check → backup → rollback on failure | Verified |
|
|
120
|
-
| Confirm a peripheral is really running after flashing | `stm32_regs_read` reads any peripheral register
|
|
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 asset pack with a fake probe, **hardware re-test pending** (development notes §31.11) |
|
|
121
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`) |
|
|
122
129
|
|
|
123
|
-
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) —
|
|
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.
|
|
124
131
|
|
|
125
132
|
## Features
|
|
126
133
|
|
|
@@ -130,14 +137,17 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
130
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"` |
|
|
131
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 |
|
|
132
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) |
|
|
133
|
-
|
|
|
140
|
+
| Chip facts (part → startup file / device define / sizes) | The plugin **ships no chip table**: part, startup file, device define and Flash/RAM come only from the local assets cache (`~/.dsh-stm32/assets/<version>/device/f1/chips.json`, root overridable with `DSH_STM32_ASSETS`), installed once on first use (`stm32_assets` with `action: "refresh"`) and offline afterwards. With no network and no cache, `stm32_project_create` / `stm32_doctor` say "run stm32_assets refresh, or check the network" instead of inventing a startup file from a built-in table |
|
|
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 |
|
|
134
143
|
| `.ioc` as a transaction | `stm32_ioc_inspect` (read-only parse) → `stm32_ioc_plan` (diff, no writes) → `stm32_ioc_apply` (SHA check + backup + rollback) |
|
|
135
144
|
| USER CODE only | `stm32_code_patch`: writes only between `/* USER CODE BEGIN X */` and `END X`; everything else untouched |
|
|
136
145
|
| Code generation | `stm32_generate`: headless CubeMX + ST project layout + USER CODE carried over by label |
|
|
137
|
-
| Build | `stm32_build`: build directory and `.elf` inferred, deduplicated errors, RAM/FLASH usage parsed after linking |
|
|
138
|
-
| Flash | `stm32_flash`: openocd `program verify reset exit`, probe released afterwards; checks that the `.ioc` has Serial Wire enabled |
|
|
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 8) |
|
|
139
148
|
| Debug | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
|
|
140
|
-
| Prove it is running | `stm32_regs_read`: reads any peripheral register back by
|
|
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
|
+
| 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 |
|
|
141
151
|
| 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) |
|
|
142
152
|
|
|
143
153
|
## Tool reference
|
|
@@ -151,7 +161,9 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
151
161
|
| `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 |
|
|
152
162
|
| `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 |
|
|
153
163
|
| `stm32_project_create` | Empty directory → full CMake project. `route: "hal"` (default) is the CubeMX route (including both "flash only" and "flash and debug" launch configs in `.vscode`); `route: "register"` builds a **no-CubeMX, no-HAL** register-level project (`mcu` picks the part, CMSIS headers and startup file come from the cache). Refuses a non-empty target unless `overwrite: true` |
|
|
164
|
+
| `stm32_assets` | Manages the **device-facts asset pack** (chip table / memory layout / .ioc templates / linker scripts / SVD — not the CMSIS download cache): `action: "refresh"` (default `profile: "core"`, 30 files ≈ 237 KiB; an already installed version is reused; `profile: "full"` is 128 files, adding the SVD tables) fetches `manifest.json` from GitHub → jsDelivr → gitcode and installs it file-by-file, every file pinned by sha256, into `~/.dsh-stm32/assets/<version>/`; `list` / `verify` / `prune` manage versions. **The plugin no longer embeds any chip table**, so device facts come only from here — the first use needs one online install, offline afterwards |
|
|
154
165
|
| `stm32_cache` | Inspect / verify / fetch / purge the download cache: `action: "list"` (default), `"verify"` (per-file check), `"fetch"` (pull the template for an `mcu`, reusing the cache without touching the network), `"purge"` (drop entries; clears everything without an `id`). The cache holds what the register route needs but the plugin does not ship — CMSIS device headers, startup file, core headers — downloaded once, reused forever |
|
|
166
|
+
| `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) |
|
|
155
167
|
| `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` |
|
|
156
168
|
|
|
157
169
|
### .ioc: read-only and transactions
|
|
@@ -159,7 +171,7 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
159
171
|
| Tool | What it does |
|
|
160
172
|
| --- | --- |
|
|
161
173
|
| `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`" |
|
|
162
|
-
| `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,
|
|
174
|
+
| `stm32_ioc_plan` | Step one of any `.ioc` change: computes a per-key diff plus the source SHA-256 and returns a `planId`, **without touching the source**. Supports setting/removing keys, adding GPIO from the chip pin table, one-shot Serial Wire repair, and retargeting clocks to the nearest reachable frequency (`clock: { targetHz }`, derived keys recomputed, per-peripheral frequencies reported) |
|
|
163
175
|
| `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` |
|
|
164
176
|
|
|
165
177
|
### Code and build
|
|
@@ -168,18 +180,46 @@ So the blinking LED is the acceptance sample, not the ceiling: **this covers the
|
|
|
168
180
|
| --- | --- |
|
|
169
181
|
| `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 |
|
|
170
182
|
| `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 |
|
|
171
|
-
| `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 |
|
|
183
|
+
| `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 |
|
|
172
184
|
|
|
173
185
|
### Flash and debug
|
|
174
186
|
|
|
175
187
|
| Tool | What it does |
|
|
176
188
|
| --- | --- |
|
|
177
|
-
| `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)) |
|
|
178
|
-
| `stm32_debug_run` | Starts openocd + gdb, `break main` → `continue` → captures pc/sp/lr/bt/locals → `reset run` + `detach`; no Flash write, nothing left running |
|
|
189
|
+
| `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 |
|
|
190
|
+
| `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 |
|
|
179
191
|
| `stm32_debug_session` | Long-lived openocd session (`.elf` resolved automatically), closed after 90 s idle, hard limit 10 min |
|
|
180
192
|
| `stm32_debug_eval` | Runs gdb commands or reads expressions (e.g. `g_led_blink_count`) inside the session, then `resume` + `detach` immediately |
|
|
181
193
|
| `stm32_debug_stop` | Releases the probe immediately, idempotent |
|
|
182
|
-
| `stm32_regs_read` | Reads
|
|
194
|
+
| `stm32_regs_read` | Reads registers; each `addresses` entry accepts five forms: physical address `0x4001100C` / `4001100C`, symbol name `GPIOC.ODR` / `GPIOC->ODR`, or a bare peripheral `GPIOC` (dumps all its 7 registers in ascending offset, capped at 64). With the asset pack's `full` profile 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 run `stm32_assets refresh --profile full`. 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 |
|
|
195
|
+
| `stm32_rtt` | **RTT logs** without a UART: `action: "start"` first reads three words with `mdw` to confirm a `SEGGER RTT` control block is really there (`addr` is the control block address, not a channel buffer), then issues `rtt setup/start/server start`; with no live session it starts one itself. `action: "dump"` reads for `seconds` (default 3 s) or up to `maxRecords` (default 200) and returns `records[{ t, level, text }]` — `level` is the **highest level kept** (1 error / 2 warn / 3 info / 4 debug, default 4 = everything), with `dropped` / `truncated` reported honestly. `action: "stop"` is idempotent (also run at turn end), `action: "status"` shows the port and uptime. The target must **actually be running** (`rtt start` reads live RAM). Failures carry `probeError`: an all-zero control block means the firmware never called `rtt_init()`, a magic mismatch means a wrong `addr`, a refused connection means the session died or port 9090 is taken |
|
|
196
|
+
|
|
197
|
+
### Adding RTT to the firmware (shortest example)
|
|
198
|
+
|
|
199
|
+
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:
|
|
200
|
+
|
|
201
|
+
```c
|
|
202
|
+
/* USER CODE BEGIN 2 */ /* must come after clock init: timestamps use SystemCoreClock */
|
|
203
|
+
rtt_init();
|
|
204
|
+
rtt_printf(RTT_LEVEL_INFO, "boot: sysclk=%lu", (unsigned long)SystemCoreClock);
|
|
205
|
+
/* USER CODE END 2 */
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
(`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:
|
|
209
|
+
|
|
210
|
+
```powershell
|
|
211
|
+
arm-none-eabi-nm build/Debug/<project>.elf | findstr _SEGGER_RTT
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
Then have the model run these three steps (three `stm32_rtt` tool calls, arguments named as in the tool schema):
|
|
215
|
+
|
|
216
|
+
```text
|
|
217
|
+
stm32_rtt action=start addr=0x20000DE0 # control block address from the nm line above
|
|
218
|
+
stm32_rtt action=dump seconds=3 level=3 # 3 s of info and above
|
|
219
|
+
stm32_rtt action=stop # releases the port; also runs at turn end
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
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.
|
|
183
223
|
|
|
184
224
|
## Slash commands
|
|
185
225
|
|
|
@@ -188,6 +228,7 @@ Tools are for the model; when you want to act yourself, use a command — one co
|
|
|
188
228
|
| Command | What it does | Touches the board |
|
|
189
229
|
| --- | --- | --- |
|
|
190
230
|
| `/stm32-doctor` | Health check: toolchain, busy debug processes, ports, `.elf`, `.ioc` warnings | No |
|
|
231
|
+
| `/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 |
|
|
191
232
|
| `/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 |
|
|
192
233
|
| `/stm32-build [dir] [--clean]` | Build, printing memory usage / `.elf` / errors | No |
|
|
193
234
|
| `/stm32-flash [dir]` | **Flash**: program + verify + reset, no debug session, no breakpoints | Yes |
|
|
@@ -204,6 +245,12 @@ Tools are for the model; when you want to act yourself, use a command — one co
|
|
|
204
245
|
- **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.
|
|
205
246
|
- **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.
|
|
206
247
|
|
|
248
|
+
## Chips, linker scripts and clocks
|
|
249
|
+
|
|
250
|
+
- **The part is a parameter, not a constant.** `stm32_project_create` / `stm32_generate` swap three things together from `mcu`: the startup file (`startup_stm32f103xe.s`), the device define (`STM32F103xE`) and the linker script (`STM32F103RCTx_FLASH.ld`). The HAL route goes through `src/engine/hal-chip.ts` (`resolveHalChip()` + `renderStartupAndDefine` / `renderLinkerScript` / `renderIoc`); the register route 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.
|
|
251
|
+
- **Linker scripts are named after the `DeviceId`: `<DeviceId>_FLASH.ld`.** C8T6 → `STM32F103C8Tx_FLASH.ld` (64 KiB Flash / 20 KiB RAM), RCT6 → `STM32F103RCTx_FLASH.ld` (256 / 48), F107VCT6 → `STM32F107VCTx_FLASH.ld` (256 / 64). The old `STM32F103XX_FLASH.ld` in the template survives only as a C8T6 compatibility copy; CMake's `-T` always points at the rendered one (`pointLinkerFlagAt()` rewrites the old name inside the toolchain file so you never end up with two `-T` flags and the wrong script).
|
|
252
|
+
- **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**.
|
|
253
|
+
- **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".
|
|
207
254
|
## Configuration
|
|
208
255
|
|
|
209
256
|
### User config file (`~/.dsh-stm32/config.json`)
|
|
@@ -308,21 +355,25 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
|
|
|
308
355
|
| Limitation | Detail | Workaround |
|
|
309
356
|
| --- | --- | --- |
|
|
310
357
|
| 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 |
|
|
311
|
-
| **
|
|
358
|
+
| **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`) |
|
|
312
359
|
| Default probe is **CMSIS-DAP** | Falls back to cmsis-dap without an `openocd.cfg` | Put `interface/stlink.cfg` into `openocd.cfg` (see above) |
|
|
313
360
|
| 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` |
|
|
314
361
|
| Generation/scaffolding needs **CubeMX + the F1 firmware package** | Package version defaults to `STM32Cube_FW_F1_V1.8.7` | Pass another version via `firmwarePackage` |
|
|
315
362
|
| Not yet verified on other machines | This machine: Windows 10 + MSYS2 UCRT64 + DAPLink + a Blue Pill; other combinations rely on your feedback | Open an issue with the full `stm32_doctor` output |
|
|
363
|
+
| **RTT channel 0 only**, and the frame format is ours | `stm32_rtt` parses channel 0 only, with a 13-byte header (4 B length + 1 B level + 8 B timestamp + UTF-8 text); it is neither defmt nor SEGGER raw bytes — a native client (RTT Viewer / J-Link RTT Client) reading channel 0 sees that header as payload. RTT also lives in target RAM: no `rtt_init()` means no control block, and a full ring drops records | Use `level` as a filter (`level: 3` keeps info and above), put JSON in `text` for structured output; change channel count and buffer size via `RTT_UP_CHANNELS` / `RTT_BUF_SIZE` in `rtt.h` (default 3 × 1 KB = 3 KB `.bss` on a 20 KB C8T6); defmt decoding or native RTT output would be a separate feature |
|
|
364
|
+
| Register **symbol names and bit-field decoding need the asset pack's `full` profile** | `GPIOC.ODR` / `GPIOC->ODR` and peripheral dumps (a bare `GPIOC`) are resolved from `device/f1/svd/<line>.json`, derived from ST's SVDs (ST EULA, 1.71 MiB), which `core` (30 files ≈ 237 KiB) does not contain; 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 an actionable hint | `stm32_assets action="refresh" profile="full"` (128 files); or just use `0x…` addresses |
|
|
316
365
|
|
|
317
366
|
## Troubleshooting
|
|
318
367
|
|
|
319
368
|
| Symptom | Cause and fix |
|
|
320
369
|
| --- | --- |
|
|
370
|
+
| `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 |
|
|
321
371
|
| 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 |
|
|
322
372
|
| `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 |
|
|
323
|
-
| 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`
|
|
373
|
+
| 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` |
|
|
324
374
|
| 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 |
|
|
325
375
|
| A tool answers "missing arm-none-eabi-gcc …, X was not started" | That is the pre-flight gate (`envCheck` defaults to `block`) doing its job, not a bug: it is cheaper than discovering the problem halfway through. Answer "install", and the model runs `stm32_env_install` for a plan; after you confirm, the toolchain is installed and the config written — **the next call works without a restart**. Run `/stm32-env` for the whole picture, or pass `envCheck: "warn"` (continue with a warning) / `"off"` (skip the check) |
|
|
376
|
+
| The first project build answers "device facts are not ready … run stm32_assets refresh, or check the network" | The plugin ships no chip table: part → startup file / device define / Flash / RAM come only from the local assets cache (`~/.dsh-stm32/assets/<version>/`). Once online, run `stm32_assets` (`action: "refresh"`, default `profile: "core"`, 30 files ≈ 237 KiB); offline afterwards. `DSH_STM32_ASSETS` overrides the root |
|
|
326
377
|
| `stm32_doctor` cannot find gcc / openocd | First read the "searched ..." list and the auto-discovery line in the doctor notes / error; if it is installed elsewhere, set `STM32_BIN_DIRS` or pass `binDirs`. **If you do not know what to install, run `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 |
|
|
327
378
|
| `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 |
|
|
328
379
|
| 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` |
|
|
@@ -334,12 +385,25 @@ Without an `openocd.cfg` the plugin falls back to `interface/cmsis-dap.cfg` + `t
|
|
|
334
385
|
|
|
335
386
|
```powershell
|
|
336
387
|
npm run build # tsc -> lib/ (lib/ is committed: rebuild before you commit)
|
|
337
|
-
npm test #
|
|
388
|
+
npm test # 34 offline suites, 497 cases; no board, CubeMX, or toolchain needed
|
|
389
|
+
npm run test:pack # pack a tarball, unpack it, scaffold a real register project from the unpacked lib
|
|
390
|
+
npm run test:size # package guard: tarball <=1.2 MB, templates <=60 KB, no binaries/diagrams inside
|
|
338
391
|
```
|
|
339
392
|
|
|
340
|
-
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).
|
|
393
|
+
CI (`.github/workflows/ci.yml`) runs `npm ci → build → check that the committed lib/ matches src/ → npm test → test:pack → test:size` on every push and PR (windows-latest).
|
|
394
|
+
|
|
395
|
+
A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that need the real firmware package are skipped: CI reports **495 passed + 2 skipped**, while a developer machine runs all 497. The offline suites only read the bundled [`test/fixtures/`](test/fixtures/README.md); the session cases build a fake toolchain directory with `fakeBinDirs()` (empty placeholder files for openocd / gdb), so nothing depends on what is installed locally.
|
|
396
|
+
|
|
397
|
+
### What ships where (decide before you add a file)
|
|
398
|
+
|
|
399
|
+
| Where | What | Size |
|
|
400
|
+
| --- | --- | --- |
|
|
401
|
+
| 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 |
|
|
402
|
+
| Git only, not packed | `src/**`, `test/**`, `scripts/**`, `docs/diagrams/**` (two interactive HTML pages) | diagrams are 2 MB raw / 891 KB gz; `files` in `package.json` narrows `docs` to `docs/*.md` |
|
|
403
|
+
| 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; the **device-facts asset pack** (chips.json / memory.json / .ioc templates / .ld / SVD — 30 files ≈ 237 KiB for the core profile, 128 files for `full`, which is where the SVDs live — the plugin ships no chip table, the first run needs one online `stm32_assets refresh` and it is offline afterwards) | manage the caches with `stm32_cache list/verify/purge` and `stm32_assets list/verify/prune` |
|
|
404
|
+
| Rendered on the spot | `.ioc` content (`renderIoc`), `.ld` MEMORY (`renderLinkerScript`), the cmake source list | rendered per part, never stored as a template |
|
|
341
405
|
|
|
342
|
-
|
|
406
|
+
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.
|
|
343
407
|
|
|
344
408
|
Hardware e2e writes to the board and needs a project you point it at:
|
|
345
409
|
|
|
@@ -355,20 +419,23 @@ See the [development notes](docs/development-notes.md) for the suite breakdown a
|
|
|
355
419
|
```text
|
|
356
420
|
src/
|
|
357
421
|
index.ts plugin entry (name / inject / apply)
|
|
358
|
-
tools/ the
|
|
422
|
+
tools/ the 21 tools, L3 (parameter schema + output contract + rendering)
|
|
359
423
|
engine/ pure logic and workflows (generate / build / flash / debug / ioc / scaffold …)
|
|
360
|
-
commands/register.ts the
|
|
424
|
+
commands/register.ts the 7 slash commands
|
|
361
425
|
skill/stm32-workflow.ts the SKILL shipped with the plugin
|
|
362
426
|
data/ paths and chip data (paths are data, not logic)
|
|
363
427
|
templates/scaffold/ project template snapshot (CMake / .ld / .vscode / .ioc)
|
|
364
|
-
test/ offline suites + fixtures + hardware e2e
|
|
365
|
-
|
|
428
|
+
test/ offline suites (36, registered in run-units) + fixtures + hardware e2e
|
|
429
|
+
scripts/ guards and generators (pack-size / pack-smoke / gen-xcube-catalog / copy-client)
|
|
430
|
+
docs/ specification + development notes + reading guide + diagrams/ (not packed)
|
|
366
431
|
```
|
|
367
432
|
|
|
368
433
|
## Documentation
|
|
369
434
|
|
|
370
435
|
- [Specification](docs/dsh-stm32-plugin-规格.md): tool contracts, state machine, acceptance criteria A1–A13
|
|
371
436
|
- [Development notes](docs/development-notes.md): milestones, host-contract pitfalls, implementation details and measured numbers
|
|
437
|
+
- [Source reading guide](docs/reading-guide.md): layered reading order, per-file responsibilities and exports, 14 flow diagrams, 23 invariants
|
|
438
|
+
- Visuals: [architecture](docs/diagrams/dsh-stm32-architecture.html) / [main journey](docs/diagrams/dsh-stm32-journey.html) — single-file HTML, opens offline, exports PNG/SVG
|
|
372
439
|
|
|
373
440
|
## License
|
|
374
441
|
|