dsh-stm32 0.1.6 → 0.1.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +410 -517
- package/README_EN.md +410 -510
- package/client/client.js +4363 -24
- package/docs/reading-guide.md +62 -0
- package/lib/client.js +4363 -24
- package/lib/commands/register.js +5 -5
- package/lib/data/chips.js +4 -4
- package/lib/data/clock-db.js +24 -24
- package/lib/data/clock-f1.js +2 -2
- package/lib/data/cmsis-sources.js +6 -6
- package/lib/data/db-presets.js +4 -4
- package/lib/data/device-facts.js +6 -6
- package/lib/data/family.js +16 -16
- package/lib/data/firmware-packages.js +10 -10
- package/lib/data/install-guides.js +18 -18
- package/lib/data/ioc-presets.js +3 -3
- package/lib/data/ioc-schema.js +32 -32
- package/lib/data/rm-topics.js +6 -6
- package/lib/data/search-roots.js +62 -16
- package/lib/data/serial-config.js +7 -7
- package/lib/data/stm32f1.js +1 -1
- package/lib/data/svd.js +7 -7
- package/lib/data/toolchain-config.js +3 -3
- package/lib/engine/artifacts.js +123 -0
- package/lib/engine/assets.js +5 -5
- package/lib/engine/breakpoint-hits.js +73 -0
- package/lib/engine/breakpoints.js +5 -5
- package/lib/engine/build.js +73 -3
- package/lib/engine/cache.js +4 -4
- package/lib/engine/channel-tap.js +227 -0
- package/lib/engine/channels.js +48 -0
- package/lib/engine/clock-derived.js +2 -2
- package/lib/engine/clock-direct.js +3 -3
- package/lib/engine/clock-plan.js +7 -7
- package/lib/engine/clock-pllmn.js +6 -6
- package/lib/engine/clocks.js +192 -0
- package/lib/engine/cmake-sources.js +9 -9
- package/lib/engine/code-patch.js +5 -5
- package/lib/engine/cube-mx-guard.js +3 -3
- package/lib/engine/cube-programmer.js +4 -4
- package/lib/engine/cubemx-db.js +7 -7
- package/lib/engine/debug-session.js +58 -13
- package/lib/engine/debug.js +3 -3
- package/lib/engine/doctor.js +12 -12
- package/lib/engine/download.js +1 -1
- package/lib/engine/event-bus.js +158 -0
- package/lib/engine/event-log.js +335 -0
- package/lib/engine/facts-acquire.js +3 -3
- package/lib/engine/fault-hints.js +146 -0
- package/lib/engine/fetch.js +2 -2
- package/lib/engine/firmware-install.js +16 -16
- package/lib/engine/firmware-official.js +8 -8
- package/lib/engine/flash.js +22 -22
- package/lib/engine/fs-longpath.js +1 -1
- package/lib/engine/gdb-mi.js +7 -7
- package/lib/engine/generate-script.js +2 -2
- package/lib/engine/generate.js +17 -17
- package/lib/engine/hal-chip.js +7 -7
- package/lib/engine/interrupts.js +247 -0
- package/lib/engine/ioc-diff.js +369 -0
- package/lib/engine/ioc-plan.js +52 -52
- package/lib/engine/ioc-rules.js +9 -9
- package/lib/engine/ioc-sync.js +58 -0
- package/lib/engine/ioc-verify.js +34 -34
- package/lib/engine/msys2-install.js +81 -56
- package/lib/engine/panel-actions.js +103 -0
- package/lib/engine/pinout.js +140 -0
- package/lib/engine/probe-error.js +8 -8
- package/lib/engine/probe-info.js +95 -0
- package/lib/engine/probe-session.js +3 -3
- package/lib/engine/probe.js +47 -50
- package/lib/engine/progress.js +99 -0
- package/lib/engine/project-conf.js +199 -0
- package/lib/engine/project-export.js +1 -1
- package/lib/engine/register-clock.js +5 -5
- package/lib/engine/register-gpio.js +3 -3
- package/lib/engine/register-linker.js +7 -7
- package/lib/engine/register-template.js +22 -22
- package/lib/engine/regs.js +3 -3
- package/lib/engine/rm-extract.js +2 -2
- package/lib/engine/rm-sources.js +1 -1
- package/lib/engine/route-plan.js +9 -9
- package/lib/engine/rtt.js +18 -18
- package/lib/engine/scaffold.js +22 -22
- package/lib/engine/serial.js +24 -24
- package/lib/engine/session-context.js +19 -0
- package/lib/engine/source-slice.js +59 -0
- package/lib/engine/tar.js +1 -1
- package/lib/engine/text-file.js +1 -1
- package/lib/engine/thirdparty.js +3 -3
- package/lib/engine/tool-env.js +2 -2
- package/lib/engine/tool-events.js +119 -0
- package/lib/engine/toolchain-gate.js +8 -8
- package/lib/engine/usercode-merge.js +2 -2
- package/lib/engine/vscode-config.js +2 -2
- package/lib/engine/watch-admin.js +101 -0
- package/lib/engine/watch-record.js +39 -0
- package/lib/engine/watch-recorder.js +116 -0
- package/lib/engine/web-api.js +887 -5
- package/lib/engine/web-routes.js +18 -1
- package/lib/engine/workspace-memo.js +41 -0
- package/lib/engine/xcube-catalog.js +1 -1
- package/lib/index.js +72 -29
- package/lib/skill/stm32-workflow.js +1 -1
- package/lib/tools/assets.js +1 -1
- package/lib/tools/cache.js +2 -2
- package/lib/tools/debug-session.js +5 -5
- package/lib/tools/doctor.js +2 -2
- package/lib/tools/download.js +1 -1
- package/lib/tools/env-install.js +3 -3
- package/lib/tools/firmware-install.js +5 -5
- package/lib/tools/flash.js +8 -8
- package/lib/tools/generate.js +1 -1
- package/lib/tools/ioc-apply.js +10 -1
- package/lib/tools/ioc-plan.js +1 -1
- package/lib/tools/ioc-verify.js +11 -11
- package/lib/tools/project-create.js +32 -4
- package/lib/tools/project-dir.js +8 -2
- package/lib/tools/regs.js +10 -10
- package/lib/tools/route-plan.js +9 -9
- package/lib/tools/rtt.js +17 -9
- package/lib/tools/serial.js +30 -8
- package/lib/tools/watch.js +24 -2
- package/package.json +70 -70
- package/templates/scaffold/RTT.md +26 -34
package/README_EN.md
CHANGED
|
@@ -1,510 +1,410 @@
|
|
|
1
|
-
# dsh-stm32
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[
|
|
6
|
-
|
|
7
|
-
[; the session cases build a fake toolchain directory with `fakeBinDirs()` (empty placeholder files for openocd / gdb), so nothing depends on what is installed locally.
|
|
462
|
-
|
|
463
|
-
### What ships where (decide before you add a file)
|
|
464
|
-
|
|
465
|
-
| Where | What | Size |
|
|
466
|
-
| --- | --- | --- |
|
|
467
|
-
| npm tarball | `lib/**` (including `lib/client.js`), `client/client.js`, `templates/scaffold/**`, `assets/**`, `cordis.patch.yml`, both READMEs, `LICENSE`, `docs/*.md` | 272 files / 1825.2 KB packed, 15181.3 KB unpacked; `assets/**` is 12.5 MB of source (headers compress well) |
|
|
468
|
-
| Git only, not packed | `src/**`, `test/**`, `scripts/**`, `docs/diagrams/**` (two interactive HTML pages) | diagrams are 2 MB raw / 891 KB gz; `files` in `package.json` narrows `docs` to `docs/*.md` |
|
|
469
|
-
| Bundled (npm package) | Device-facts layer (21 families of `device/<family>/chips.json`), `.ioc` templates, `.ld`, SVD, startup files and headers — 75 files for `core`, 105 for `full`, shipped offline | inspect and verify with `stm32_assets list/verify`; `prune` only removes historical external versions |
|
|
470
|
-
| Downloaded on demand | CMSIS device headers / startup files / core headers (fetched into the cache on first use, pinned per file by sha256); HAL firmware packages | manage the cache with `stm32_cache list/verify/purge` |
|
|
471
|
-
| Rendered on the spot | `.ioc` content (`renderIoc`), `.ld` MEMORY (`renderLinkerScript`), the cmake source list | rendered per part, never stored as a template |
|
|
472
|
-
|
|
473
|
-
The guard is `scripts/pack-size.mjs` (`npm run test:size`): tarball ≤ 4 MB (4 000 000 B; 1.82 MB measured with `assets/**` bundled), the runtime assets under `templates/**` (`.ioc/.xml/.ld/.json/.cfg/.svd/.csv`) ≤ 40 KB with a 24 KB per-file cap (Markdown docs and C/CMake sources are not assets), no `.png/.jpg/.gif/.webp/.bmp/.pdf/.html/.zip/.7z/.exe/.dll` inside, and `README.md` / `README_EN.md` / `LICENSE` / `cordis.patch.yml` / `docs/reading-guide.md` / `assets/manifest.json` / `assets/device/f1/chips.json` all present.
|
|
474
|
-
|
|
475
|
-
Hardware e2e writes to the board and needs a project you point it at:
|
|
476
|
-
|
|
477
|
-
```powershell
|
|
478
|
-
$env:DSH_STM32_E2E_PROJECT = 'D:\work\my-stm32'
|
|
479
|
-
node test\e2e-flash.mjs
|
|
480
|
-
```
|
|
481
|
-
|
|
482
|
-
See the [development notes](docs/development-notes.md) for the suite breakdown and what each script covers.
|
|
483
|
-
|
|
484
|
-
## Repository layout
|
|
485
|
-
|
|
486
|
-
```text
|
|
487
|
-
src/
|
|
488
|
-
index.ts plugin entry (name / inject / apply)
|
|
489
|
-
tools/ the 25 registered tools, L3 (24 files: parameter schema + output contract + rendering)
|
|
490
|
-
engine/ pure logic and workflows (generate / build / flash / debug / ioc / scaffold …)
|
|
491
|
-
commands/register.ts the 7 slash commands
|
|
492
|
-
skill/stm32-workflow.ts the SKILL shipped with the plugin
|
|
493
|
-
data/ paths and chip data (paths are data, not logic)
|
|
494
|
-
templates/scaffold/ project template snapshot (CMake / .ld / .vscode / .ioc)
|
|
495
|
-
test/ offline suites (60, registered in run-units) + fixtures + hardware e2e
|
|
496
|
-
scripts/ guards and generators (pack-size / pack-smoke / gen-xcube-catalog / copy-client)
|
|
497
|
-
docs/ specification + development notes + reading guide + diagrams/ (not packed)
|
|
498
|
-
```
|
|
499
|
-
|
|
500
|
-
## Documentation
|
|
501
|
-
|
|
502
|
-
- [Specification](docs/dsh-stm32-plugin-规格.md): tool contracts, state machine, acceptance criteria A1–A13
|
|
503
|
-
- [Development notes](docs/development-notes.md): milestones, host-contract pitfalls, implementation details and measured numbers
|
|
504
|
-
- [Source reading guide](docs/reading-guide.md): layered reading order, per-file responsibilities and exports, 14 flow diagrams, 23 invariants
|
|
505
|
-
- [Release notes 0.1.5](docs/release-notes/v0.1.5.md): serial P1, the 21-family register route, installer downloads and P0/P1/P2 hardening (0.1.4 and earlier live in git history)
|
|
506
|
-
- Visuals: [architecture](docs/diagrams/dsh-stm32-architecture.html) / [main journey](docs/diagrams/dsh-stm32-journey.html) — single-file HTML, opens offline, exports PNG/SVG
|
|
507
|
-
|
|
508
|
-
## License
|
|
509
|
-
|
|
510
|
-
[MIT](LICENSE)
|
|
1
|
+
# dsh-stm32
|
|
2
|
+
|
|
3
|
+
[](https://github.com/JingYu-er/dsh-stm32)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](#known-limitations)
|
|
6
|
+
[](#known-limitations)
|
|
7
|
+
[](https://github.com/JingYu-er/dsh-stm32/releases)
|
|
8
|
+
|
|
9
|
+
Full-chain STM32 tooling distributed as a [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) plugin: 25 tools, 7 slash commands and one bundled SKILL that hand the chain "probe toolchain → scaffold a project → edit `.ioc` (clocks included) → generate code → build → flash → debug → read registers back" to the model, plus serial interaction (Windows) and an in-session debug console panel.
|
|
10
|
+
|
|
11
|
+
Within the supported range the same tools behave the same way from F1 to H7; for an unsupported family or capability the call states what is missing instead of returning a guessed result.
|
|
12
|
+
|
|
13
|
+
| Capability | Coverage |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| Chip families | 27 families: C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / MP1 / MP2 / N6 / U0 / U3 / U5 / WB / WB0 / WBA / WL / WL3 |
|
|
16
|
+
| HAL scaffolding | 21 single-core families: C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / U0 / U3 / U5 / WBA / WL |
|
|
17
|
+
| Register scaffolding | 21 families, all passing the create→build matrix |
|
|
18
|
+
| Clock planning | 18 families; PLL1 on H5 / U5 / WBA / L4+ |
|
|
19
|
+
| `.ioc` peripheral presets | Derived from official CubeMX data: USART / TIM PWM / ADC |
|
|
20
|
+
| Register names and bitfields | F1 |
|
|
21
|
+
|
|
22
|
+
**中文:** [README.md](./README.md)
|
|
23
|
+
|
|
24
|
+
[Quick start](#quick-start-minimal-end-to-end-check) · [Tool reference](#tool-reference) · [Slash commands](#slash-commands) · [Debug console](#debug-console-panel) · [Configuration](#configuration) · [Known limitations](#known-limitations) · [Troubleshooting](#troubleshooting)
|
|
25
|
+
|
|
26
|
+
## What it does
|
|
27
|
+
|
|
28
|
+
Most "AI writes STM32 code" setups stop at the source level: a `main.c` is produced, and whether it compiles and blinks is still confirmed by hand across CubeMX, a terminal and a debugger. The model cannot see the board, so it cannot be accountable for the result.
|
|
29
|
+
|
|
30
|
+
This plugin puts the hardware side inside DSH: the `.ioc` is readable and writable (transaction with rollback), code goes only into `USER CODE` blocks, generation and builds return real error lines, flashing never holds the probe a debugger needs, and register state is read back after flashing. Every step returns something checkable (a plan id, `file:line:col`, `Verified OK`, bit13 of `GPIOC.ODR`, reported as `ODR13=1` when register tables are present), which the model uses to decide the next step.
|
|
31
|
+
|
|
32
|
+
| Step | Manual flow | This plugin |
|
|
33
|
+
| --- | --- | --- |
|
|
34
|
+
| Scaffold | Configure clocks, pins and project settings in the GUI, generate CMake, hand-write `launch.json` | `stm32_project_create` produces a template project in about 2 s, matching CubeMX GUI output, with both `.vscode` configs in place |
|
|
35
|
+
| Reconfigure | Edit in the GUI, regenerate, hope `USER CODE` survives | `stm32_ioc_plan` shows the diff without writing → confirm → `stm32_ioc_apply` with checks, backup and rollback |
|
|
36
|
+
| Write code | Whole-file edits that can land in generated regions and vanish on regeneration | `stm32_code_patch` writes only inside `USER CODE` blocks; bytes outside are preserved |
|
|
37
|
+
| Build | Keil, or hand-maintained CMake and VS Code tasks | `/stm32-build [dir] [--clean]` |
|
|
38
|
+
| Flash | Keil, or a hand-written `tasks.json` calling openocd | `/stm32-flash [dir]` |
|
|
39
|
+
| Verify | Breakpoints and manual register inspection | `stm32_regs_read` reads state back: two `GPIOC.ODR` samples confirm the counter advances, `AFIO.MAPR` confirms firmware did not disable SWD |
|
|
40
|
+
| Debug | F5, manual breakpoints, close the session afterwards | `stm32_debug_run` halts at `main`, captures one snapshot and releases the probe; continuous work uses `stm32_debug_session`, which closes when idle |
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
### Install the plugin
|
|
45
|
+
|
|
46
|
+
Only DSH itself is required at this point; the toolchain can be added later.
|
|
47
|
+
|
|
48
|
+
```powershell
|
|
49
|
+
dsh plugin --profile desktop add dsh-stm32
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`dsh plugin` runs `pnpm add` inside the profile directory and appends `dsh-stm32` to that profile's `dsh.profile.bundles`. Exit DSH completely and start it again afterwards; bundle layers load at process start only.
|
|
53
|
+
|
|
54
|
+
- Verify: `dsh plugin --profile desktop why dsh-stm32` prints `0.1.8`
|
|
55
|
+
- Uninstall: `dsh plugin --profile desktop remove dsh-stm32`, then restart DSH
|
|
56
|
+
- Web profile: replace `desktop` with `web`
|
|
57
|
+
|
|
58
|
+
### Add the toolchain
|
|
59
|
+
|
|
60
|
+
With the plugin installed, parsing `.ioc` files, inspecting pins / clocks / interrupts and previewing plans all work already. Compilers and probe tools are needed only when building, flashing or debugging.
|
|
61
|
+
|
|
62
|
+
| Task | Requires | How to add |
|
|
63
|
+
| --- | --- | --- |
|
|
64
|
+
| Build | `arm-none-eabi-gcc`, `cmake`, `ninja` | `/stm32-setup` installs everything (MSYS2 plus toolchain, about 300 MB); a manual installation is discovered automatically |
|
|
65
|
+
| Flash, debug | `openocd`, `arm-none-eabi-gdb` (or `gdb-multiarch`), a CMSIS-DAP / ST-Link probe | Same command; probe drivers are supplied by the OS |
|
|
66
|
+
| Generate code, scaffold HAL projects | STM32CubeMX (with bundled JRE) and its firmware package | Install CubeMX from the ST website (ST account required); the plugin locates it automatically; install firmware packages in the CubeMX package manager |
|
|
67
|
+
|
|
68
|
+
When the missing piece is unclear, check the diagnosis first:
|
|
69
|
+
|
|
70
|
+
```text
|
|
71
|
+
/stm32-env # what build / flash / debug / generate are missing, where things install, how to install
|
|
72
|
+
/stm32-setup # plan first, install after confirmation, self-check when done
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`/stm32-env` works with no toolchain at all: it only runs version queries and writes nothing.
|
|
76
|
+
|
|
77
|
+
### Pre-flight check
|
|
78
|
+
|
|
79
|
+
```text
|
|
80
|
+
/stm32-doctor
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Read-only checks: toolchain completeness, leftover openocd / gdb processes holding the probe, gdb port usage, whether `.elf` and `.ioc` exist in the project, and whether the `.ioc` has a configuration that would lose SWD after flashing.
|
|
84
|
+
|
|
85
|
+
### Bundled assets
|
|
86
|
+
|
|
87
|
+
The mapping from part number to startup file, device macro and Flash / RAM size ships with the plugin, together with `.ioc` templates, linker scripts and register tables. Everything works offline after installation; no resource download is involved. `stm32_assets verify` checks integrity and points to a reinstall when files are missing.
|
|
88
|
+
|
|
89
|
+
### Install from source
|
|
90
|
+
|
|
91
|
+
Only for development or when the code itself must change. Build and test commands are listed under [Development and testing](#development-and-testing).
|
|
92
|
+
|
|
93
|
+
```powershell
|
|
94
|
+
git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
95
|
+
cd dsh-stm32
|
|
96
|
+
npm install --no-audit --no-fund # typescript only
|
|
97
|
+
npm run build # tsc -> lib/, required before committing
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Mount a working copy with `link:`, not `file:`:
|
|
101
|
+
|
|
102
|
+
```powershell
|
|
103
|
+
cd "$env:USERPROFILE\.dsh\profiles\desktop"
|
|
104
|
+
pnpm add "link:D:\path\to\dsh-stm32"
|
|
105
|
+
|
|
106
|
+
# append "dsh-stm32" to dsh.profile.bundles in that directory's package.json
|
|
107
|
+
# restart dsh afterwards (bundle layers load at process start only)
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Reason: under `nodeLinker: hoisted`, `file:` copies the package into a real directory, so a freshly built `lib/` is never read by the host, which shows up as "code changed, behaviour unchanged". `link:` reads `lib/` from the working copy; DSH still has to restart to reload the plugin.
|
|
111
|
+
|
|
112
|
+
## Quick start: minimal end-to-end check
|
|
113
|
+
|
|
114
|
+
This chain was verified on real hardware, driven entirely by tool calls. Every step uses the same tools; blinking an LED is simply the cheapest sample.
|
|
115
|
+
|
|
116
|
+
| Step | Action | Tool | Measured |
|
|
117
|
+
| --- | --- | --- | --- |
|
|
118
|
+
| 1 | Probe: toolchain, occupied probes, ports, `.elf`, `.ioc` warnings | `stm32_doctor` | about 2 s |
|
|
119
|
+
| 2 | Scaffold a CMake project in an empty directory (`.ioc` with SWD configured) | `stm32_project_create` | about 2 s |
|
|
120
|
+
| 3 | Run CubeMX headless; output lands in `Core/` | `stm32_generate` | 130–175 s first run; skipped (< 1 s) when nothing changed |
|
|
121
|
+
| 4 | Build (first run configures with `cmake --preset`) | `stm32_build` | about 5 s configure + 3 s compile |
|
|
122
|
+
| 5 | Flash only: program + verify + reset | `stm32_flash` | 2.1–2.6 s |
|
|
123
|
+
| 6 | Read `GPIOC.ODR` (or address `0x4001100C`) and confirm the state toggles | `stm32_regs_read` | 0.4–1.3 s |
|
|
124
|
+
|
|
125
|
+
Step 6 uses symbolic names, which rely on the bundled register tables. With an incomplete installation the address form `0x4001100C` still works, but the report carries no register names or bitfields.
|
|
126
|
+
|
|
127
|
+
On the model side a single sentence suffices: "Create an STM32F103C8T6 blink project in `D:\work\blink`, build it and flash it".
|
|
128
|
+
|
|
129
|
+
The minimal check covers scaffold → generate → build → flash → read-back; no step is blink-specific. Real projects follow the same chain, differing only in the number of peripherals in the `.ioc`, the number of `USER CODE` blocks and the code size.
|
|
130
|
+
|
|
131
|
+
| Real-project task | Path | Verification status |
|
|
132
|
+
| --- | --- | --- |
|
|
133
|
+
| Peripheral setup: GPIO / timers / USART / I2C / SPI / ADC / DMA / interrupts | `stm32_ioc_plan` (GPIO checked against the pin table) → `stm32_ioc_apply` → `stm32_generate` | GPIO, clocks and SWD measured on hardware; other peripherals use the same mechanism, not measured individually |
|
|
134
|
+
| Add HAL sources for new peripherals | Add `stm32f1xx_hal_<peripheral>.c` to `STM32_Drivers_Src` in `cmake/stm32cubemx/CMakeLists.txt`, or write into `cmake/user/CMakeLists.txt` | Manual step: the plugin places only `Src/` and `Inc/`, never CubeMX-generated `cmake/**` |
|
|
135
|
+
| Multiple sources and custom modules | Write into `cmake/user/CMakeLists.txt` (placeholder provided) | Placeholder in place; not measured separately |
|
|
136
|
+
| Application code | `stm32_code_patch` writes per block and carries blocks back on regeneration | Measured (append / replace; an unknown tag lists all available tags) |
|
|
137
|
+
| Tuning, clock changes | `.ioc` transaction: diff → checks → backup → rollback on failure | Measured |
|
|
138
|
+
| Confirm peripherals run | `stm32_regs_read` reads any peripheral register by symbol (`TIM2.CNT`, `USART1.SR`, `ADC1.DR`) or address (`0x40000024`); naming only `GPIOC` dumps all its registers | Address form measured on hardware; symbolic names and bitfields being retested |
|
|
139
|
+
| Inspect a failure | `stm32_debug_run` halts at `main` once; continuous work uses `stm32_debug_session` + `stm32_debug_eval` | Measured (halted at `main () at main.c:67`) |
|
|
140
|
+
|
|
141
|
+
Boundaries are listed under [Known limitations](#known-limitations): HAL scaffolding covers 21 single-core families, register scaffolding 21 (validation board is C8T6), the host is verified on Windows only, the default probe is CMSIS-DAP, and new peripherals need manual HAL sources. Peripheral variety is not a tool limitation: whatever the `.ioc` can express follows the same chain; peripherals other than the blink sample have not been measured individually on hardware, so running `/stm32-doctor` before starting a project is recommended.
|
|
142
|
+
|
|
143
|
+
## Tool reference
|
|
144
|
+
|
|
145
|
+
### Environment and projects
|
|
146
|
+
|
|
147
|
+
| Tool | Purpose |
|
|
148
|
+
| --- | --- |
|
|
149
|
+
| `stm32_doctor` | Read-only health check: toolchain completeness, leftover openocd / gdb processes, gdb port usage, `.elf` and `.ioc` status; per-chip capabilities and known issues |
|
|
150
|
+
| `stm32_route_plan` | Estimates HAL versus register cost for a specific project and requirement; separates auto-installable gaps from manual ones |
|
|
151
|
+
| `stm32_env_install` | Installs MSYS2 and toolchain components (gcc / gdb / openocd / cmake / ninja); plan only by default, executes with `dryRun:false` + `confirm:true`; writes user-level PATH only, no administrator rights |
|
|
152
|
+
| `stm32_download` | Download without installing: J-Link direct link with checksum; CubeMX / CubeProgrammer open the official page or validate a local file |
|
|
153
|
+
| `stm32_firmware_install` | Downloads and assembles STM32Cube firmware packages, official archive first, GitHub assembly as fallback; plan only by default |
|
|
154
|
+
| `stm32_assets` | Lists, verifies and prunes bundled assets (chip data, `.ioc` templates, linker scripts, startup files, register tables) |
|
|
155
|
+
| `stm32_cache` | Lists, verifies, fetches and prunes the download cache (register-route CMSIS templates) |
|
|
156
|
+
| `stm32_project_create` | Scaffolds a project: `route:"hal"` from templates plus firmware package, `route:"register"` without CubeMX; both emit `openocd.cfg` |
|
|
157
|
+
| `stm32_project_export` | Packs a project as a zip, excluding `build/`, `.dsh-stm32/`, `node_modules/`, `.git/` by default, optionally with prebuilt artifacts |
|
|
158
|
+
|
|
159
|
+
### `.ioc`: inspect and edit
|
|
160
|
+
|
|
161
|
+
| Tool | Purpose |
|
|
162
|
+
| --- | --- |
|
|
163
|
+
| `stm32_ioc_inspect` | Read-only parse: part number, pins, signals, enabled peripherals, interrupts, clock tree, project settings, risk notes |
|
|
164
|
+
| `stm32_ioc_plan` | Computes a per-key diff without writing: peripheral presets, pins, interrupts, debug port, clock planning, bulk entries |
|
|
165
|
+
| `stm32_ioc_apply` | Applies a plan: source checks → backup → atomic replace; rollback from backup |
|
|
166
|
+
| `stm32_ioc_verify` | Has CubeMX re-read the `.ioc` and points out silently dropped peripherals and missing init calls |
|
|
167
|
+
|
|
168
|
+
### Code and build
|
|
169
|
+
|
|
170
|
+
| Tool | Purpose |
|
|
171
|
+
| --- | --- |
|
|
172
|
+
| `stm32_code_patch` | Writes only inside `USER CODE BEGIN/END` blocks, preserving all other bytes; backs up first |
|
|
173
|
+
| `stm32_generate` | Runs CubeMX headless, places output in `Core/`, carries `USER CODE` back by tag; skips when `.ioc` is unchanged |
|
|
174
|
+
| `stm32_build` | Builds: infers build directory and `.elf`, returns error lines, warning count, FLASH / RAM usage; optional hex / bin |
|
|
175
|
+
|
|
176
|
+
### Flash, debug and runtime
|
|
177
|
+
|
|
178
|
+
| Tool | Purpose |
|
|
179
|
+
| --- | --- |
|
|
180
|
+
| `stm32_flash` | Flash only: program + verify + reset, then releases the probe; checks Serial Wire first; failures return the probe error class and a suggested action |
|
|
181
|
+
| `stm32_debug_run` | Flashes, halts at `main`, captures registers, stack and locals, then resets, runs and releases the probe |
|
|
182
|
+
| `stm32_debug_session` | Opens a long-lived debug session (idle and total limits) for repeated `stm32_debug_eval` calls |
|
|
183
|
+
| `stm32_debug_eval` | Executes gdb commands in the session: variables, registers, backtrace, memory |
|
|
184
|
+
| `stm32_debug_stop` | Closes the session and releases the probe |
|
|
185
|
+
| `stm32_regs_read` | Reads registers by address or symbol, resolving bitfields when register tables are present; pauses briefly to read, then resumes without resetting |
|
|
186
|
+
| `stm32_watch` | Registers and samples expressions (with deltas); `kind=write/read/access` installs hardware watchpoints, limited by the chip's watchpoint count |
|
|
187
|
+
| `stm32_rtt` | RTT channel: firmware keeps the control block in RAM, the host reads it through openocd, output carries level and timestamp |
|
|
188
|
+
| `stm32_serial` | Serial interaction (Windows): `list` / `open` / `read` / `send` / `transact` / `status` / `close` |
|
|
189
|
+
|
|
190
|
+
### RTT on the firmware side (shortest example)
|
|
191
|
+
|
|
192
|
+
```c
|
|
193
|
+
/* USER CODE BEGIN 0 */
|
|
194
|
+
static char rtt_buf[3][1024];
|
|
195
|
+
static void rtt_init(void) {
|
|
196
|
+
/* Control block follows the SEGGER convention in RAM: acId / acName / three rings, see rtt.h in templates/ */
|
|
197
|
+
}
|
|
198
|
+
/* USER CODE END 0 */
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
The full implementation ships in `templates/`; channel count and ring size are controlled by `RTT_UP_CHANNELS` / `RTT_BUF_SIZE` (default 3×1 KB = 3 KB `.bss`; C8T6 has 20 KB RAM).
|
|
202
|
+
|
|
203
|
+
## Slash commands
|
|
204
|
+
|
|
205
|
+
| Command | Description |
|
|
206
|
+
| --- | --- |
|
|
207
|
+
| `/stm32-doctor` | Health check: toolchain, leftover processes, ports, `.elf` and `.ioc` warnings |
|
|
208
|
+
| `/stm32-env` | Toolchain check: what build / flash / debug / generate are missing, where things install, how to install |
|
|
209
|
+
| `/stm32-setup` | Probe → install plan → install after confirmation → self-check |
|
|
210
|
+
| `/stm32-build [dir] [--clean]` | Build (CMake + Ninja, `build/Debug` by default); `--clean` wipes first |
|
|
211
|
+
| `/stm32-flash [dir]` | Flash only: program + verify + reset, then release the probe |
|
|
212
|
+
| `/stm32-debug [dir]` | Flash and enter debugging, halted at `main`; then use `stm32_debug_eval` |
|
|
213
|
+
| `/stm32-stop` | Close the debug session and release the probe for VS Code F5 |
|
|
214
|
+
|
|
215
|
+
## Debug console (panel)
|
|
216
|
+
|
|
217
|
+
The in-session debug console shows one timeline for both sides: the start, success, failure and duration of `stm32_*` calls, plus serial, RTT, watch, pin, clock, interrupt and `.ioc` state.
|
|
218
|
+
|
|
219
|
+
| Tab | Content | Actions |
|
|
220
|
+
| --- | --- | --- |
|
|
221
|
+
| Overview | Project, part number, SYSCLK, capacity, debug session, toolchain, build and flash, evidence usage, alert summary | Jump to failed events or the live channel, export an operation log as Markdown |
|
|
222
|
+
| Events | Call start and end, duration, slow-call marker, argument summary | Failures only, filter by tool, sort by duration, bulk quoting, JSONL export, event deep links |
|
|
223
|
+
| Live channels | Serial / RTT / watch output | Pause, clear, keyword filter, RTT level filter, send a serial line, persistent capture, export |
|
|
224
|
+
| Pins | Grouped by peripheral, by port, or as a package outline | Filter, copy references, inspect `.ioc` keys, CSV export |
|
|
225
|
+
| Clocks | Tree and flow views, per-node frequency and divider | Over-limit markers and "change to ÷N" advice computed from the parent clock |
|
|
226
|
+
| Interrupts | NVIC enablement, preemption and sub-priority | Filter, sort, edit in place, bulk edit |
|
|
227
|
+
| Faults | Raw failure events, rule decoding, grouping by rule | Category filter, copy group hint, CSV export |
|
|
228
|
+
| Artifacts | elf / hex / bin, size, checksum, capacity, build-to-build comparison | Copy checksums |
|
|
229
|
+
| Changes | `.ioc` differences against a baseline | Record a baseline, restore one key, restore all |
|
|
230
|
+
|
|
231
|
+
Opening the panel first loads the most recent records for the session, then appends live. Events are written every 30 seconds to `~/.dsh-stm32/evidence/<date>/<session>/` for replay and export, retained for 7 days and the last 20 sessions by default, all configurable. The panel shows only this plugin's own tool calls.
|
|
232
|
+
|
|
233
|
+
## Serial (Windows)
|
|
234
|
+
|
|
235
|
+
`stm32_serial` exposes seven actions: `list` / `open` / `read` / `send` / `transact` / `status` / `close`. Once opened, the port is held by the plugin, one port at a time; 115200 8N1 by default, no flow control, DTR / RTS not asserted, closed at the end of a turn.
|
|
236
|
+
|
|
237
|
+
- Platform: Windows only. Linux and macOS return `unsupported-platform`.
|
|
238
|
+
- Ports: `list` enumerates available ports; parameters are remembered per device, so a different COM number still reuses them.
|
|
239
|
+
- Read: `read` accepts a cursor and returns only newer lines.
|
|
240
|
+
- Write: `send` writes one line; `transact` writes and waits for a matching reply (regular expression).
|
|
241
|
+
- Retention: `persist=true` keeps the port open across turns.
|
|
242
|
+
|
|
243
|
+
The reference validation board uses a CH340 (`1A86:7523`, COM5, 115200). The DAPLink virtual serial port on the same board (`c251:f001`, COM4) does not carry application data.
|
|
244
|
+
|
|
245
|
+
## Design notes
|
|
246
|
+
|
|
247
|
+
- **Own files only**: the `.ioc` goes through a transaction (plan → checks → backup → replace); generated regions receive only `USER CODE` content; no other generated file is modified.
|
|
248
|
+
- **Flash and debug are separate**: `stm32_flash` never opens a debug session and releases the probe immediately; debugging opens `stm32_debug_session` on demand and closes it when idle, so VS Code is not locked out.
|
|
249
|
+
- **Conclusions carry evidence**: failures return compiler `file:line:col`, probe error class and register values rather than vague prose.
|
|
250
|
+
- **Say what is missing**: when a chip, a clock plan or a debug script is unsupported, the error names the missing piece instead of guessing or silently skipping.
|
|
251
|
+
- **No host takeover**: the panel displays state and performs explicit project actions; it does not edit code or run Git operations.
|
|
252
|
+
|
|
253
|
+
## Configuration
|
|
254
|
+
|
|
255
|
+
### Config file (`~/.dsh-stm32/config.json`)
|
|
256
|
+
|
|
257
|
+
Toolchain locations are maintained by the plugin: `stm32_env_install` writes this file and later tools read it, with no DSH restart and no environment variables required. Manual editing is supported:
|
|
258
|
+
|
|
259
|
+
```json
|
|
260
|
+
{
|
|
261
|
+
"version": 1,
|
|
262
|
+
"msys64": "E:/msys64",
|
|
263
|
+
"binDirs": [],
|
|
264
|
+
"packages": ["mingw-w64-ucrt-x86_64-arm-none-eabi-gcc", "mingw-w64-ucrt-x86_64-cmake"],
|
|
265
|
+
"cubeMxRoot": "",
|
|
266
|
+
"updatedAt": "2026-02-01T00:00:00.000Z"
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
An empty `binDirs` derives `<msys64>/ucrt64/bin` from `msys64`. A corrupt file (invalid JSON) is treated as absent and does not break other features.
|
|
271
|
+
|
|
272
|
+
Precedence: tool arguments (`binDirs` / `cubeMxRoots`) > environment variables > config file > built-in defaults. Built-in defaults contain only common Windows locations, never machine-specific paths.
|
|
273
|
+
|
|
274
|
+
### Settings panel
|
|
275
|
+
|
|
276
|
+
The "STM32 toolchain" page under DSH settings offers three cards:
|
|
277
|
+
|
|
278
|
+
- **Locations**: reads and saves `msys64` / `cubeMxRoot` / extra `binDirs`; the next tool call sees the change.
|
|
279
|
+
- **Missing pieces**: runs a probe (version queries only) and lists path, version and reason per item, plus badges for build / flash / debug / generate.
|
|
280
|
+
- **Install toolchain**: emits a plan first (steps, download size, PATH and config changes), executes after confirmation, and streams steps with a log tail.
|
|
281
|
+
|
|
282
|
+
### Download cache and firmware packages
|
|
283
|
+
|
|
284
|
+
- Register-route CMSIS templates are downloaded on first use into the cache (default `%LOCALAPPDATA%\dsh-stm32\cache`) and reused afterwards; files are verified and mismatches rejected. `stm32_cache` lists, verifies, fetches and prunes entries.
|
|
285
|
+
- The HAL route uses locally installed CubeMX firmware packages: F1 defaults to `STM32Cube_FW_F1_V1.8.7`, other families use the highest installed version; `firmwarePackage` overrides. When missing, install it through the CubeMX package manager or use `stm32_firmware_install`.
|
|
286
|
+
- `stm32_download` only downloads or verifies installers (default directory `%LOCALAPPDATA%\dsh-stm32\downloads`); it never executes them and never requests administrator rights.
|
|
287
|
+
|
|
288
|
+
### Environment variables (optional)
|
|
289
|
+
|
|
290
|
+
| Variable | Purpose | Default |
|
|
291
|
+
| --- | --- | --- |
|
|
292
|
+
| `STM32_BIN_DIRS` | Toolchain directory candidates, `;`-separated, replaces the built-in list entirely (auto-discovery still appends) | `C:/msys64/ucrt64/bin`, `C:/msys64/mingw64/bin` |
|
|
293
|
+
| `STM32_CUBEMX_ROOT` | CubeMX root, replaces the built-in list | `C:/Program Files/STMicroelectronics/STM32Cube/STM32CubeMX` |
|
|
294
|
+
| `STM32_NO_DISCOVER` | Set to `1` to disable auto-discovery (built-in list only) | unset |
|
|
295
|
+
| `DSH_STM32_CONFIG` | Alternate config file path | `%USERPROFILE%\.dsh-stm32\config.json` |
|
|
296
|
+
| `DSH_STM32_NO_CONFIG` | Set to `1` to ignore the config file entirely | unset |
|
|
297
|
+
| `DSH_STM32_CACHE` | Download cache root, supports `~` | `%LOCALAPPDATA%\dsh-stm32\cache` |
|
|
298
|
+
| `DSH_STM32_DOWNLOADS` | Installer download directory, supports `~` | `%LOCALAPPDATA%\dsh-stm32\downloads` |
|
|
299
|
+
| `DSH_STM32_HOME` | Plugin data root (config, evidence, snapshots, memo) | `%USERPROFILE%\.dsh-stm32` |
|
|
300
|
+
| `DSH_STM32_EVIDENCE` | Evidence directory | `~/.dsh-stm32/evidence` |
|
|
301
|
+
| `DSH_STM32_EVIDENCE_FLUSH_SECONDS` | Flush interval (5–3600 s) | 30 |
|
|
302
|
+
| `DSH_STM32_EVIDENCE_KEEP_DAYS` | Evidence retention in days (0–365, 0 = keep) | 7 |
|
|
303
|
+
| `DSH_STM32_EVIDENCE_KEEP_SESSIONS` | Evidence retention in sessions (1–200) | 20 |
|
|
304
|
+
| `DSH_STM32_SNAPSHOTS` | `.ioc` baseline directory | `~/.dsh-stm32/ioc-snapshots` |
|
|
305
|
+
| `DSH_STM32_OFFLINE` | Set to `1` to forbid network downloads (cache only) | unset |
|
|
306
|
+
| `MSYS2_MIRROR` | Installer mirror; must be set together with `MSYS2_INSTALLER_SHA256` | official → TUNA → NJU → Aliyun |
|
|
307
|
+
| `MSYS2_INSTALLER_URL` / `MSYS2_INSTALLER_SHA256` | Installer URL and checksum overrides; must be set together | official pinned release |
|
|
308
|
+
| `DSH_STM32_JLINK_URL` / `DSH_STM32_JLINK_SHA256` | J-Link direct link and checksum overrides; must be set together | SEGGER official |
|
|
309
|
+
|
|
310
|
+
Tool arguments mirror these variables: flash and debug tools accept `binDirs`, `elfPath`, `buildDir`, `configFile`, `adapterSpeed`; generation and scaffolding accept `cubeMxRoots`, `firmwarePackage`.
|
|
311
|
+
|
|
312
|
+
Toolchain locations usually need no configuration: when `binDirs` / `STM32_BIN_DIRS` are absent, the plugin searches common locations and appends candidates — `ucrt64/bin`, `mingw64/bin` and `clang64/bin` under `<drive>/msys64`, `<drive>/msys2`, `<drive>/app/msys64`, `<drive>/tools/msys64`, `%LOCALAPPDATA%/Programs/msys64`; and CubeMX under the `STM32CubeMX_PATH` environment variable, its uninstall registration, and `Program Files\STMicroelectronics\STM32Cube`. When nothing is found, errors and `stm32_doctor` list the directories that were checked.
|
|
313
|
+
|
|
314
|
+
### openocd.cfg (project-level, takes precedence)
|
|
315
|
+
|
|
316
|
+
CMSIS-DAP (default):
|
|
317
|
+
|
|
318
|
+
```text
|
|
319
|
+
source [find interface/cmsis-dap.cfg]
|
|
320
|
+
source [find target/stm32f1x.cfg]
|
|
321
|
+
adapter speed 4000
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
ST-Link:
|
|
325
|
+
|
|
326
|
+
```text
|
|
327
|
+
source [find interface/stlink.cfg]
|
|
328
|
+
transport select hla_swd
|
|
329
|
+
source [find target/stm32f1x.cfg]
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
Without `openocd.cfg`, the debug script follows the chip family in the `.ioc` (F1 → `stm32f1x`, F4 → `stm32f4x`, G4 → `stm32g4x`; L4 and L4+ share `stm32l4x`). C0 / U0 scripts ship with the plugin and are copied into the project's `openocd/` directory during scaffolding; H5 / N6 / U3 / WBA / WB0 / WL3 / MP2 have no scripts and flashing is refused explicitly.
|
|
333
|
+
|
|
334
|
+
### Two hard requirements on the `.ioc`
|
|
335
|
+
|
|
336
|
+
1. **SYS debug port set to Serial Wire** (PA13 = `SYS_JTMS-SWDIO`, PA14 = `SYS_JTCK-SWCLK`); use `stm32_ioc_plan` with `serialWire: true` when missing.
|
|
337
|
+
2. **`ProjectManager.KeepUserCode=true`**; otherwise `USER CODE` content is lost on regeneration.
|
|
338
|
+
|
|
339
|
+
## Known limitations
|
|
340
|
+
|
|
341
|
+
| Limitation | Detail | Handling |
|
|
342
|
+
| --- | --- | --- |
|
|
343
|
+
| Verified on Windows only | Code generation depends on the Windows installation of CubeMX | No alternative yet; flash, debug and register reads may work elsewhere with a complete toolchain, unverified |
|
|
344
|
+
| Some chips have no official debug script | C0 / U0 use plugin-supplied scripts (not verified on hardware); H5 / N6 / U3 / WBA / WB0 / WL3 / MP2 have none | Flashing states this explicitly instead of failing silently |
|
|
345
|
+
| HAL scaffolding excludes dual-core and MPU families | Dual-core WB, MP1 / MP2 / N6, WB0 / WL3 are out of scope | Scaffolding reports the chip as unsupported |
|
|
346
|
+
| Depth is graded per family | HAL 21 families, register 21, clocks 18; register names and bitfields currently F1 only | The missing capability is named at call time |
|
|
347
|
+
| Probes selected from what USB reports | ST-Link, DAPLink / CMSIS-DAP and J-Link are distinguished automatically; a project `openocd.cfg` wins | Write `openocd.cfg` to pin a choice |
|
|
348
|
+
| New peripherals need manual HAL sources | The plugin places only `Src/` and `Inc/`; CubeMX-generated `cmake/**` is not carried over | Edit `STM32_Drivers_Src` or write into `cmake/user/CMakeLists.txt` |
|
|
349
|
+
| Generation and scaffolding need CubeMX plus the family firmware package | F1 defaults to `STM32Cube_FW_F1_V1.8.7` | Pass `firmwarePackage`, or install the package in CubeMX first |
|
|
350
|
+
| RTT is channel 0 only with a custom frame | 13-byte header (length, level, timestamp, UTF-8 text) | Filter by level; put structured data in the text; channels and ring size in `rtt.h` |
|
|
351
|
+
| Serial is Windows-only | No streaming UI, no auto-reconnect, one port at a time | Use a system serial tool, or a later release |
|
|
352
|
+
| Register names and bitfields need the bundled register tables | Covers F1 lines 100 / 101 / 102 / 103 / 105 / 107 | Use `0x` addresses; `stm32_assets verify` checks the installation |
|
|
353
|
+
|
|
354
|
+
## Troubleshooting
|
|
355
|
+
|
|
356
|
+
| Symptom | Cause | Action |
|
|
357
|
+
| --- | --- | --- |
|
|
358
|
+
| Plugin not loaded | `dsh.profile.bundles` lacks `dsh-stm32`, or DSH was not restarted | Reinstall and restart; verify with `dsh plugin --profile desktop why dsh-stm32` |
|
|
359
|
+
| Code changes have no effect | Installed via `file:`, so the host reads a copy | Switch to `link:`, rebuild with `npm run build`, restart DSH |
|
|
360
|
+
| Missing toolchain reported | Not installed, or path not discovered | Run `/stm32-env` to see what is missing, then `/stm32-setup`; or set `binDirs` manually |
|
|
361
|
+
| Flash reports the probe is busy | Another debugger (VS Code, leftover openocd) holds the probe | `/stm32-stop`, close other debuggers, retry; `stm32_doctor` lists leftover processes |
|
|
362
|
+
| SWD is lost after flashing | `.ioc` did not enable Serial Wire | Add `serialWire: true` via `stm32_ioc_plan`, regenerate, flash again |
|
|
363
|
+
| Peripherals dropped after generation | `.ioc` keys inconsistent with peripheral derivation | Run `stm32_ioc_verify` for a CubeMX-side diagnosis |
|
|
364
|
+
| Panel is blank or stale | Server-side change without restart, or `lib` newer than the process | Fully exit DSH and start again; the status bar flags "new build available" |
|
|
365
|
+
| No serial data | Wrong port (for example the DAPLink virtual port) | Confirm with `stm32_serial list`; application serial usually lives on a CH340-class adapter |
|
|
366
|
+
|
|
367
|
+
## Development and testing
|
|
368
|
+
|
|
369
|
+
| Command | Purpose |
|
|
370
|
+
| --- | --- |
|
|
371
|
+
| `npm run build` | `tsc` into `lib/`, copying client and data assets |
|
|
372
|
+
| `node test/run-units.mjs` | Offline unit tests: 80 suites / 1088 cases, no board required |
|
|
373
|
+
| `node .dsh-stm32/acceptance.mjs` | Local acceptance script: panel API, event stream, evidence, artifacts, faults, interrupts, serial, probe |
|
|
374
|
+
| `npm run test:pack` | Pack, unpack and scaffold a register project with the unpacked build |
|
|
375
|
+
| `npm run test:size` | Package and asset guards |
|
|
376
|
+
|
|
377
|
+
Release shape: published content is limited to `files` in `package.json` (`lib`, `client`, `templates`, `assets`, `docs/reading-guide.md`, `cordis.patch.yml`, both READMEs, `LICENSE`). `docs/`, `test/` and `scripts/` stay out of the package.
|
|
378
|
+
|
|
379
|
+
Development-only environment variables (not needed in daily use): `DSH_STM32_ASSETS` and `DSH_STM32_FACTS` override asset directories, `DSH_STM32_SERIAL_BRIDGE` and `DSH_STM32_SERIAL_POWERSHELL` override the serial bridge path, `DSH_STM32_PYTHON` selects the Python interpreter used for parsing.
|
|
380
|
+
|
|
381
|
+
## Repository layout
|
|
382
|
+
|
|
383
|
+
```text
|
|
384
|
+
src/
|
|
385
|
+
index.ts plugin entry: tools, slash commands, panel API, SKILL
|
|
386
|
+
tools/ registration and argument validation for 25 tools
|
|
387
|
+
engine/ engines: project, .ioc, generation, build, flash, debug, events, panel API
|
|
388
|
+
data/ chip data, CubeMX data, clocks, search roots, toolchain config
|
|
389
|
+
commands/ 7 slash commands
|
|
390
|
+
skill/ bundled stm32-workflow SKILL
|
|
391
|
+
client/client.js panel source (plain JS + react, no bundler)
|
|
392
|
+
lib/ tsc output and copied assets (published)
|
|
393
|
+
assets/ chip data, .ioc templates, linker scripts, startup files, register tables
|
|
394
|
+
templates/ scaffolding templates, register route, serial bridge, RTT
|
|
395
|
+
test/ 80 offline suites and e2e scripts
|
|
396
|
+
scripts/ build, pack, size and smoke scripts
|
|
397
|
+
docs/ development notes, reading guide, spec, diagrams
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
## Documentation
|
|
401
|
+
|
|
402
|
+
- [Specification](docs/dsh-stm32-plugin-规格.md): tool contracts, state machine, acceptance criteria
|
|
403
|
+
- [Development notes](docs/development-notes.md): milestones, host-contract issues, per-tool implementation details and measurements
|
|
404
|
+
- [Source reading guide](docs/reading-guide.md): layered reading order, per-file responsibilities and exports, diagrams and invariants
|
|
405
|
+
- Release notes: provided per release on the release page; history lives in git and the development notes
|
|
406
|
+
- Visuals: [architecture](docs/diagrams/dsh-stm32-architecture.html) / [main journey](docs/diagrams/dsh-stm32-journey.html) — single-file HTML, opens offline
|
|
407
|
+
|
|
408
|
+
## License
|
|
409
|
+
|
|
410
|
+
[MIT](LICENSE)
|