dsh-stm32 0.1.7 → 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 +256 -363
- package/README_EN.md +257 -357
- package/client/client.js +4340 -1
- package/docs/reading-guide.md +62 -0
- package/lib/client.js +4340 -1
- package/lib/engine/artifacts.js +123 -0
- package/lib/engine/breakpoint-hits.js +73 -0
- package/lib/engine/build.js +73 -3
- package/lib/engine/channel-tap.js +227 -0
- package/lib/engine/channels.js +48 -0
- package/lib/engine/clocks.js +192 -0
- package/lib/engine/debug-session.js +46 -1
- package/lib/engine/event-bus.js +158 -0
- package/lib/engine/event-log.js +335 -0
- package/lib/engine/fault-hints.js +146 -0
- package/lib/engine/interrupts.js +247 -0
- package/lib/engine/ioc-diff.js +369 -0
- package/lib/engine/ioc-sync.js +58 -0
- package/lib/engine/msys2-install.js +31 -6
- package/lib/engine/panel-actions.js +103 -0
- package/lib/engine/pinout.js +140 -0
- package/lib/engine/probe-info.js +95 -0
- package/lib/engine/progress.js +99 -0
- package/lib/engine/project-conf.js +199 -0
- package/lib/engine/session-context.js +19 -0
- package/lib/engine/source-slice.js +59 -0
- package/lib/engine/tool-events.js +119 -0
- 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 +886 -4
- package/lib/engine/web-routes.js +18 -1
- package/lib/engine/workspace-memo.js +41 -0
- package/lib/index.js +67 -24
- package/lib/tools/ioc-apply.js +9 -0
- package/lib/tools/project-create.js +28 -0
- package/lib/tools/project-dir.js +7 -1
- package/lib/tools/rtt.js +8 -0
- package/lib/tools/serial.js +22 -0
- package/lib/tools/watch.js +24 -2
- package/package.json +1 -1
package/README_EN.md
CHANGED
|
@@ -1,299 +1,260 @@
|
|
|
1
1
|
# dsh-stm32
|
|
2
2
|
|
|
3
|
-
> Hand the whole **STM32 family** (27 families: C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / MP1 / MP2 / N6 / U0 / U3 / U5 / WB / WB0 / WBA / WL / WL3) development chain to DSH: probe the toolchain → scaffold a project → edit the .ioc (clocks included) → generate code → build → debug → flash, plus serial interaction (`stm32_serial`, Windows P1). The family is read from the .ioc's `Mcu.Family`: pin names, SWD debug signal names, EXTI NVIC vector grouping, the openocd target and the hardware breakpoint/watchpoint budget all follow the family and its core. **HAL scaffolding** (firmware package, startup file, device define, linker script, .ioc template, cmake and debug configuration) is implemented per family for the 21 single-core families (C0 / F0 / F1 / F2 / F3 / F4 / F7 / G0 / G4 / H5 / H7 / L0 / L1 / L4 / L4+ / L5 / U0 / U3 / U5 / WBA / WL); the register route covers 21 families, all verified through create→build (the per-family results for the 8 new ones are in development-notes §87.5); clock planning covers 18 families (PLL1 on H5 / U5 / WBA / L4+), .ioc peripheral presets are derived from the CubeMX db, and SVD validation is still F1-only — uncovered capabilities are refused with a reason instead of silently reusing F1 tables (see [Known limitations](#known-limitations)).
|
|
4
|
-
|
|
5
|
-
[中文](./README.md) · [Quick start](#quick-start-a-minimal-end-to-end-check-empty-directory-to-a-blinking-led) · [Features](#features) · [Tool reference](#tool-reference) · [Slash commands](#slash-commands) · [Design notes](#design-notes) · [Known limitations](#known-limitations) · [Troubleshooting](#troubleshooting) · [Specification](docs/dsh-stm32-plugin-规格.md)
|
|
6
|
-
|
|
7
3
|
[](https://github.com/JingYu-er/dsh-stm32)
|
|
8
4
|
[](LICENSE)
|
|
9
5
|
[](#known-limitations)
|
|
10
6
|
[](#known-limitations)
|
|
11
|
-
[](https://github.com/deepseek-ai/deepseek-harness) **plugin** (host-side, no UI): it registers 25 tools, 7 slash commands and 1 SKILL shipped with the plugin, so the model can probe the toolchain, scaffold a CubeMX CMake project, edit the `.ioc`, run CubeMX, build, flash and debug on its own, then read the state back out of the registers — hardware programming that actually stays inside DSH.
|
|
7
|
+
[](https://github.com/JingYu-er/dsh-stm32/releases)
|
|
14
8
|
|
|
15
|
-
|
|
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.
|
|
16
10
|
|
|
17
|
-
|
|
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.
|
|
18
12
|
|
|
19
|
-
|
|
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 |
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
**中文:** [README.md](./README.md)
|
|
22
23
|
|
|
23
|
-
|
|
24
|
-
| --- | --- | --- |
|
|
25
|
-
| Create the project | Click through the clock tree, pins and project settings in the GUI, generate CMake, then hand-write `launch.json` | One sentence: `stm32_project_create` produces a templated project in 2 s (byte-identical to the GUI output), both `.vscode` debug configs already in place |
|
|
26
|
-
| Change the configuration | Edit in the GUI, regenerate, pray that USER CODE survives | `stm32_ioc_plan` shows the diff first (source untouched) → you approve → `stm32_ioc_apply` writes with SHA verification, backup and rollback on failure |
|
|
27
|
-
| Write code | Edit the whole file, accidentally touch a generated region, lose it on the next generate | `stm32_code_patch` writes only inside `USER CODE` blocks; everything outside stays byte-for-byte |
|
|
28
|
-
| Build | Build in Keil, or hand-write the CMake files for the VS Code extension | DSH builds automatically via `/stm32-build [dir] [--clean]` |
|
|
29
|
-
| Flash | Flash in Keil, or maintain a `tasks.json` that calls openocd | DSH flashes automatically via `/stm32-debug [dir]` |
|
|
30
|
-
| Verify | Set a breakpoint and read the register values yourself | After flashing, `stm32_regs_read` reads the state back: `GPIOC.ODR` twice to see the counter grow (with the SVD data it also prints `ODR5=1`), `AFIO.MAPR` to confirm the firmware did not disable SWD |
|
|
31
|
-
| Debug | `F5`, set breakpoints by hand, remember to close the session | `stm32_debug_run` halts at `main`, captures one snapshot and releases the probe; use `stm32_debug_session` only for continuous debugging, it closes itself when idle |
|
|
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)
|
|
32
25
|
|
|
26
|
+
## What it does
|
|
33
27
|
|
|
34
|
-
|
|
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.
|
|
35
29
|
|
|
36
|
-
|
|
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.
|
|
37
31
|
|
|
38
|
-
|
|
|
32
|
+
| Step | Manual flow | This plugin |
|
|
39
33
|
| --- | --- | --- |
|
|
40
|
-
|
|
|
41
|
-
|
|
|
42
|
-
|
|
|
43
|
-
|
|
|
44
|
-
|
|
|
45
|
-
|
|
|
46
|
-
|
|
|
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
|
|
47
43
|
|
|
48
|
-
|
|
44
|
+
### Install the plugin
|
|
49
45
|
|
|
50
|
-
|
|
46
|
+
Only DSH itself is required at this point; the toolchain can be added later.
|
|
51
47
|
|
|
52
48
|
```powershell
|
|
53
49
|
dsh plugin --profile desktop add dsh-stm32
|
|
54
50
|
```
|
|
55
51
|
|
|
56
|
-
|
|
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
|
+
```
|
|
57
82
|
|
|
58
|
-
|
|
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.
|
|
59
84
|
|
|
60
|
-
|
|
85
|
+
### Bundled assets
|
|
61
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.
|
|
62
88
|
|
|
63
|
-
|
|
89
|
+
### Install from source
|
|
64
90
|
|
|
65
|
-
|
|
91
|
+
Only for development or when the code itself must change. Build and test commands are listed under [Development and testing](#development-and-testing).
|
|
66
92
|
|
|
67
93
|
```powershell
|
|
68
94
|
git clone https://github.com/JingYu-er/dsh-stm32.git
|
|
69
95
|
cd dsh-stm32
|
|
70
96
|
npm install --no-audit --no-fund # typescript only
|
|
71
|
-
npm run build
|
|
72
|
-
npm test # optional: 947 offline cases in 60 suites, no board needed
|
|
73
|
-
npm run test:pack # pack a tarball, unpack it, scaffold a real register project from it
|
|
74
|
-
npm run test:size # package guard: tarball <=3.9 MB, runtime assets under templates/ (.ioc/.xml/.ld/.json/.cfg) <=40 KB, no binaries/diagrams inside
|
|
97
|
+
npm run build # tsc -> lib/, required before committing
|
|
75
98
|
```
|
|
76
99
|
|
|
77
|
-
|
|
100
|
+
Mount a working copy with `link:`, not `file:`:
|
|
78
101
|
|
|
79
102
|
```powershell
|
|
80
103
|
cd "$env:USERPROFILE\.dsh\profiles\desktop"
|
|
81
104
|
pnpm add "link:D:\path\to\dsh-stm32"
|
|
82
105
|
|
|
83
|
-
#
|
|
84
|
-
#
|
|
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)
|
|
85
108
|
```
|
|
86
109
|
|
|
87
|
-
|
|
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.
|
|
88
111
|
|
|
89
|
-
## Quick start:
|
|
112
|
+
## Quick start: minimal end-to-end check
|
|
90
113
|
|
|
91
|
-
This chain
|
|
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.
|
|
92
115
|
|
|
93
|
-
| Step |
|
|
116
|
+
| Step | Action | Tool | Measured |
|
|
94
117
|
| --- | --- | --- | --- |
|
|
95
|
-
| 1 |
|
|
96
|
-
| 2 |
|
|
97
|
-
| 3 |
|
|
98
|
-
| 4 | Build (first run configures with `cmake --preset`) | `stm32_build` |
|
|
99
|
-
| 5 |
|
|
100
|
-
| 6 | Read `GPIOC.ODR` (or
|
|
101
|
-
|
|
102
|
-
> Step 6 uses the symbol form (`GPIOC.ODR`), which needs the SVD tables bundled with the plugin (`assets/device/f1/svd/`, `full` logical tier). A `core`-only or incomplete install still reads raw addresses — write `0x4001100C` instead, and the report has neither register names nor bit-field decoding.
|
|
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 |
|
|
103
124
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
```text
|
|
107
|
-
/stm32-doctor # health check before you start
|
|
108
|
-
/stm32-env # what each capability is missing (works even when incomplete)
|
|
109
|
-
/stm32-build # build, print memory usage and errors
|
|
110
|
-
/stm32-flash # flash only, no debug session
|
|
111
|
-
/stm32-debug # flash + halt at main
|
|
112
|
-
/stm32-stop # close the debug session, hand the probe back to VS Code
|
|
113
|
-
/stm32-setup # health check + install plan (the word "install" in the command actually installs)
|
|
114
|
-
```
|
|
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.
|
|
115
126
|
|
|
116
|
-
|
|
127
|
+
On the model side a single sentence suffices: "Create an STM32F103C8T6 blink project in `D:\work\blink`, build it and flash it".
|
|
117
128
|
|
|
118
|
-
The
|
|
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.
|
|
119
130
|
|
|
120
|
-
|
|
|
131
|
+
| Real-project task | Path | Verification status |
|
|
121
132
|
| --- | --- | --- |
|
|
122
|
-
| Peripheral setup: GPIO / timers / USART / I2C / SPI / ADC / DMA / interrupts | `stm32_ioc_plan`
|
|
123
|
-
| HAL sources for
|
|
124
|
-
|
|
|
125
|
-
|
|
|
126
|
-
| Tuning
|
|
127
|
-
| Confirm
|
|
128
|
-
|
|
|
129
|
-
|
|
130
|
-
So the blinking LED is the acceptance sample, not the ceiling: **this covers the whole engineering chain, not one demo.** The real boundaries are the ones under [Known limitations](#known-limitations) — HAL scaffolding covers 21 single-core families and the register route covers 21 families (the verified board is a C8T6), verified on Windows only, CMSIS-DAP by default, plus the manual HAL-source step above. Peripheral types themselves are not limited by the tools: whatever the `.ioc` can configure goes through the same generate → build → flash → read-back chain; it just has not been tested peripheral by peripheral yet, so run `stm32_doctor` before starting a real project.
|
|
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`) |
|
|
131
140
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
| Capability | How it is provided |
|
|
135
|
-
| --- | --- |
|
|
136
|
-
| Environment health check | `stm32_doctor` (read-only), `stm32_doctor` (toolchain + busy probes + ports + project warnings) |
|
|
137
|
-
| Pre-flight gate | Every tool that needs the toolchain runs `ensureToolchain` first: missing pieces are refused up front with what to install and what stops working; `envCheck: "block"` (default) / `"warn"` / `"off"` |
|
|
138
|
-
| Install the toolchain | `stm32_env_install`: plan first (what is downloaded, how large, which PATH entry changes), install only after you confirm — MSYS2 + 5 pacman packages + a **user-level** PATH entry, then it writes the config file itself |
|
|
139
|
-
| Installer downloads (download only) | `stm32_download`: J-Link direct link + SHA256; CubeMX / CubeProgrammer return the official page or verify a local file; it downloads/verifies but never runs an installer or asks for admin |
|
|
140
|
-
| Choose the technical route | `stm32_route_plan`: for **this project's** requirements, lays out the HAL and register cost per peripheral (effort / readability / debugging), then says whether what is missing is installable-by-the-plugin or human-only (CubeMX is a GUI wizard needing an ST account; firmware packages are only maintained by the CubeMX package manager) |
|
|
141
|
-
| Chip facts (part → startup file / device define / sizes) | The plugin **ships the chip table inside the npm package**: part, startup file, device define and Flash/RAM come from `assets/device/f1/chips.json` (`lib/engine/assets.js` resolves `assets/` from the package root; `DSH_STM32_ASSETS` can still point elsewhere for development). A missing file only means an incomplete install: locate it with `stm32_assets verify`, then reinstall the plugin — no network needed |
|
|
142
|
-
| Project from scratch | `stm32_project_create`: `route: "hal"` uses the template snapshot + firmware Drivers (byte-identical to a CubeMX GUI project); `route: "register"` builds a register-level project with no CubeMX at all, pulling the CMSIS template into the cache on first use (every file is pinned by upstream sha256 and refused if it changed); `mcu` names the part (both routes accept it; the HAL route renders its startup file / device define / `<DeviceId>_FLASH.ld` from it); both routes also ship an `openocd.cfg` (CMSIS-DAP + `hla_swd` + 2 MHz) |
|
|
143
|
-
| Export a project | `stm32_project_export`: packs the sources into one zip (without `build/`, `.dsh-stm32/`, `node_modules/`, `.git/`), optionally including the `.elf`, plus a hand-off README |
|
|
144
|
-
| `.ioc` as a transaction | `stm32_ioc_inspect` (read-only parse) → `stm32_ioc_plan` (diff, no writes) → `stm32_ioc_apply` (SHA check + backup + rollback) |
|
|
145
|
-
| USER CODE only | `stm32_code_patch`: writes only between `/* USER CODE BEGIN X */` and `END X`; everything else untouched |
|
|
146
|
-
| Code generation | `stm32_generate`: headless CubeMX + ST project layout + USER CODE carried over by label |
|
|
147
|
-
| Build | `stm32_build`: build directory and `.elf` inferred, deduplicated errors, RAM/FLASH usage parsed after linking; ask for `artifacts: ["hex","bin"]` and the same toolchain's `arm-none-eabi-objcopy` produces them |
|
|
148
|
-
| Flash | `stm32_flash`: openocd `program verify reset exit`, probe released afterwards; checks that the `.ioc` has Serial Wire enabled; failures carry a structured `probeError` (`kind` / `cause` / `hint` / `evidence` / `retryable`, `kind` is one of 9) |
|
|
149
|
-
| Debug | `stm32_debug_run` / `stm32_debug_session` / `stm32_debug_eval` / `stm32_debug_stop` |
|
|
150
|
-
| Prove it is running | `stm32_regs_read`: reads any peripheral register back by address or symbol name (`GPIOC.ODR`), decoding bit fields when SVD data is installed (`→ ODR5=1`); halts, reads, then `resume` — no chip reset |
|
|
151
|
-
| Variable watch / watchpoints | `stm32_watch`: `action=add` registers expressions (`kind=value` is sampling only and needs no session); `action=sample` halts, evaluates each expression, computes the delta, and resumes if the target was running; `kind=write/read/access` installs hardware watchpoints (gdb `watch`/`rwatch`/`awatch`), bounded by the F1's 4 data comparators |
|
|
152
|
-
| Firmware logs (RTT) | `stm32_rtt`: a SEGGER-shaped control block in RAM, openocd `rtt setup/start/server start` turns channel 0 into a TCP stream, and a 13-byte frame header carries level and timestamp — no UART, no rewiring |
|
|
153
|
-
| Serial interaction (Windows P1) | `stm32_serial`: `list` / `open` / `read` / `send` / `transact` / `status` / `close`; zero npm dependencies (a PowerShell 5.1 + `System.IO.Ports` bridge holds the COM port), default 115200 8N1, DTR/RTS not asserted, `persist=false`, one session at a time; **no GUI panel, no SSE, no Linux/macOS, no auto-reconnect** (see [Serial](#serial-windows-p1)) |
|
|
154
|
-
| Working discipline for the model | SKILL `stm32-workflow` shipped with the plugin (USER CODE only, never touch generated regions, flash and debug are separate, claims need register evidence) |
|
|
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.
|
|
155
142
|
|
|
156
143
|
## Tool reference
|
|
157
144
|
|
|
158
|
-
### Environment and
|
|
145
|
+
### Environment and projects
|
|
159
146
|
|
|
160
|
-
| Tool |
|
|
147
|
+
| Tool | Purpose |
|
|
161
148
|
| --- | --- |
|
|
162
|
-
| `stm32_doctor` |
|
|
163
|
-
| `
|
|
164
|
-
| `
|
|
165
|
-
| `
|
|
166
|
-
| `
|
|
167
|
-
| `
|
|
168
|
-
| `
|
|
169
|
-
| `
|
|
170
|
-
| `stm32_project_export` |
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
| Tool | What it does |
|
|
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 |
|
|
176
162
|
| --- | --- |
|
|
177
|
-
| `stm32_ioc_inspect` |
|
|
178
|
-
| `stm32_ioc_plan` |
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
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 |
|
|
181
167
|
|
|
182
168
|
### Code and build
|
|
183
169
|
|
|
184
|
-
| Tool |
|
|
170
|
+
| Tool | Purpose |
|
|
185
171
|
| --- | --- |
|
|
186
|
-
| `stm32_code_patch` |
|
|
187
|
-
| `stm32_generate` | Runs
|
|
188
|
-
| `stm32_build` |
|
|
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 |
|
|
189
175
|
|
|
190
|
-
### Flash and
|
|
176
|
+
### Flash, debug and runtime
|
|
191
177
|
|
|
192
|
-
| Tool |
|
|
178
|
+
| Tool | Purpose |
|
|
193
179
|
| --- | --- |
|
|
194
|
-
| `stm32_flash` |
|
|
195
|
-
| `stm32_debug_run` |
|
|
196
|
-
| `stm32_debug_session` |
|
|
197
|
-
| `stm32_debug_eval` |
|
|
198
|
-
| `stm32_debug_stop` |
|
|
199
|
-
| `stm32_regs_read` | Reads registers
|
|
200
|
-
| `stm32_watch` |
|
|
201
|
-
| `stm32_rtt` |
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
A register-level project (`route: "register"`) already ships `Core/Src/rtt.c` and `Core/Inc/rtt.h`, but **they are off by default**: with nobody referencing them, `--gc-sections` drops the code and the 3 KB ring buffers (the default firmware is 1576 B RAM / 1368 B FLASH and `nm` shows no `_SEGGER_RTT`). To turn logging on, add three lines inside a USER CODE block:
|
|
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)
|
|
206
191
|
|
|
207
192
|
```c
|
|
208
|
-
/* USER CODE BEGIN
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
/*
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
(`rtt.h` already sits in `Core/Inc`; you may also add an explicit `#include "rtt.h"` to `USER CODE BEGIN Includes`.) After building, grab the control block address on the host:
|
|
215
|
-
|
|
216
|
-
```powershell
|
|
217
|
-
arm-none-eabi-nm build/Debug/<project>.elf | findstr _SEGGER_RTT
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
Then have the model run these three steps (three `stm32_rtt` tool calls, arguments named as in the tool schema):
|
|
221
|
-
|
|
222
|
-
```text
|
|
223
|
-
stm32_rtt action=start addr=0x20000DE0 # control block address from the nm line above
|
|
224
|
-
stm32_rtt action=dump seconds=3 level=3 # 3 s of info and above
|
|
225
|
-
stm32_rtt action=stop # releases the port; also runs at turn end
|
|
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 */
|
|
226
199
|
```
|
|
227
200
|
|
|
228
|
-
|
|
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).
|
|
229
202
|
|
|
230
|
-
##
|
|
231
|
-
|
|
232
|
-
`stm32_serial` lets the model open a serial port, send, receive and wait for replies itself — no serial terminal on the side, no copy-paste. This is **P1**: the smallest end-to-end loop, Windows only, with the boundaries stated below.
|
|
203
|
+
## Slash commands
|
|
233
204
|
|
|
234
|
-
|
|
|
205
|
+
| Command | Description |
|
|
235
206
|
| --- | --- |
|
|
236
|
-
| `
|
|
237
|
-
| `
|
|
238
|
-
| `
|
|
239
|
-
| `
|
|
240
|
-
| `
|
|
241
|
-
| `
|
|
242
|
-
| `
|
|
243
|
-
|
|
244
|
-
Defaults: **115200 8N1, no flow control, DTR and RTS both de-asserted (asserting them resets many boards), UTF-8, CRLF appended on send**; `persist=false` closes the port at turn end (`persist=true` keeps it across turns). **One session at a time**: a second `open` returns `already-open` and asks you to `close` first — the "two logical sessions fighting over one port" class of bug cannot happen.
|
|
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 |
|
|
245
214
|
|
|
246
|
-
|
|
247
|
-
stm32_serial action=list
|
|
248
|
-
stm32_serial action=open port=COM3 baudRate=115200
|
|
249
|
-
stm32_serial action=send text="AT"
|
|
250
|
-
stm32_serial action=transact text="AT" until="OK|ERROR" timeoutMs=1000
|
|
251
|
-
stm32_serial action=read cursor=0
|
|
252
|
-
stm32_serial action=close
|
|
253
|
-
```
|
|
215
|
+
## Debug console (panel)
|
|
254
216
|
|
|
255
|
-
|
|
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.
|
|
256
218
|
|
|
257
|
-
|
|
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 |
|
|
258
230
|
|
|
259
|
-
|
|
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.
|
|
260
232
|
|
|
261
|
-
##
|
|
233
|
+
## Serial (Windows)
|
|
262
234
|
|
|
263
|
-
|
|
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.
|
|
264
236
|
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
| `/stm32-build [dir] [--clean]` | Build, printing memory usage / `.elf` / errors | No |
|
|
271
|
-
| `/stm32-flash [dir]` | **Flash**: program + verify + reset, no debug session, no breakpoints | Yes |
|
|
272
|
-
| `/stm32-debug [dir]` | **Flash + debug**: halt at `main` after flashing, session kept (3 min idle / 10 min limit, also closed when the turn ends) | Yes |
|
|
273
|
-
| `/stm32-stop` | Closes the session opened by `/stm32-debug` and hands the probe back to VS Code | No |
|
|
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.
|
|
274
242
|
|
|
275
|
-
`
|
|
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.
|
|
276
244
|
|
|
277
245
|
## Design notes
|
|
278
246
|
|
|
279
|
-
- **
|
|
280
|
-
- **
|
|
281
|
-
-
|
|
282
|
-
- **
|
|
283
|
-
- **
|
|
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.
|
|
284
252
|
|
|
285
|
-
## Chips, linker scripts and clocks
|
|
286
|
-
|
|
287
|
-
- **The part is a parameter, not a constant.** `stm32_project_create` / `stm32_generate` swap three things together from `mcu`: the startup file (`startup_stm32f103xe.s`), the device define (`STM32F103xE`) and the linker script (`STM32F103RCTx_FLASH.ld`). The HAL route goes through `src/engine/hal-chip.ts` (`resolveHalChip()` + `renderStartupAndDefine` / `renderLinkerScript` / `renderIoc`); the register route resolves F1 through `src/data/stm32f1.ts` (`resolveF1Chip()`, 14 density grades, every startup file pinned by upstream sha256) and the other 20 families through `CMSIS_FAMILIES` in `src/data/cmsis-sources.ts` plus their bundled `assets/device/<family>/chips.json`. An unknown part returns a reason instead of inventing a startup file that does not exist upstream.
|
|
288
|
-
- **Linker scripts are named after the `DeviceId`: `<DeviceId>_FLASH.ld`.** C8T6 → `STM32F103C8Tx_FLASH.ld` (64 KiB Flash / 20 KiB RAM), RCT6 → `STM32F103RCTx_FLASH.ld` (256 / 48), F107VCT6 → `STM32F107VCTx_FLASH.ld` (256 / 64). The old `STM32F103XX_FLASH.ld` in the template survives only as a C8T6 compatibility copy; CMake's `-T` always points at the rendered one (`pointLinkerFlagAt()` rewrites the old name inside the toolchain file so you never end up with two `-T` flags and the wrong script).
|
|
289
|
-
- **Clocks: nearest, and say so when unreachable.** `stm32_ioc_plan`'s `clock: { targetHz }` (or `pllMul` to pin the multiplier, `pllSource` to pick HSE / HSI) enumerates every reachable PLL combination, takes the one with the smallest |SYSCLK − target| and states the gap: for 60 MHz the F1 PLL only multiplies integers and HSE 8 MHz cannot hit that step, so it picks 64 MHz and reports "unreachable, chose 64 MHz (+4 MHz)" (ties go to the higher step). The same plan **recomputes every derived key** (`SYSCLKFreq_VALUE`, `HCLKFre`, `PLLMUL`, APB1/APB2/ADC dividers) — changing only SYSCLK leaves CubeMX recomputing from stale values or ignoring them — and lists per-peripheral frequencies, UART baud error and a few alternatives. On an out-of-range request (SYSCLK > 72 MHz, APB1 > 36 MHz, ADC > 14 MHz, USB wanting 48 MHz outside PLLCLK/1.5) it **writes no key at all**.
|
|
290
|
-
- **The register route maps memory per chip, not per family template.** Startup file, device define and Flash/RAM all come from `assets/device/<family>/chips.json` for the 21 families; H7 uses only the 128 KiB DTCM (`0x20000000`) by default — all 138 parts carry a `linkerRam` window — U5 follows the per-line SRAM window (256 / 768 / 2496 KiB), while L4+ and L5 are single contiguous blocks (L5's 192 + 64 KiB are adjacent and merge to 256 KiB). The rendered `MEMORY` ORIGIN/LENGTH and `_estack` follow that window, so "builds fine, HardFaults on boot" from silent RAM overflow does not happen (see development-notes §87).
|
|
291
|
-
- **Five consistency checks before flashing.** `stm32_doctor` cross-checks `.ioc` part ↔ startup file name ↔ device define in cmake ↔ `.ld` MEMORY sizes ↔ `.elf` Flash usage, and reports a blocker on any mismatch. The `.elf` figure sums `p_filesz` from the ELF program headers rather than using the file size — with `-g3` a 20 KiB firmware produces a 600 KB `.elf`, which would false-alarm "over Flash".
|
|
292
253
|
## Configuration
|
|
293
254
|
|
|
294
|
-
###
|
|
255
|
+
### Config file (`~/.dsh-stm32/config.json`)
|
|
295
256
|
|
|
296
|
-
|
|
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:
|
|
297
258
|
|
|
298
259
|
```json
|
|
299
260
|
{
|
|
@@ -306,87 +267,51 @@ The plugin remembers where the toolchain lives. `stm32_env_install` writes this
|
|
|
306
267
|
}
|
|
307
268
|
```
|
|
308
269
|
|
|
309
|
-
An empty `binDirs`
|
|
310
|
-
|
|
311
|
-
**Precedence**: tool arguments (`binDirs` / `cubeMxRoots`) > environment variables > this config file > built-in defaults; auto-discovered installs are only appended when no argument was given.
|
|
312
|
-
|
|
313
|
-
### Settings panel (GUI)
|
|
314
|
-
|
|
315
|
-
The config file above can also be edited without a terminal: **Settings → STM32 toolchain** in DSH (a browser-side panel shipped with the plugin, same origin, no extra dependency). Three cards:
|
|
316
|
-
|
|
317
|
-
- **Where it is installed**: reads the current config; edit `msys64` / `cubeMxRoot` / extra `binDirs` and save — it writes the same file, and the next tool call picks it up without restarting DSH;
|
|
318
|
-
- **What is missing**: one probe run (it executes each tool's version command, installs nothing) showing the resolved path and version per tool, the `hint` for missing ones, plus four capability badges (build / flash / debug / generate);
|
|
319
|
-
- **Install the toolchain**: first a plan (steps, download size, how PATH and the config file would change), then **a second click to confirm** before anything is installed; progress and the log tail stream into the card. It drives the very same installer as `stm32_env_install`. When the toolchain is already complete, the plan is a single line — "toolchain complete, nothing to install" — instead of seven skipped steps.
|
|
320
|
-
|
|
321
|
-
The panel talks to six `/dsh-stm32/api/*` routes the plugin registers on the host (read config, save config, probe, install plan, install start, install state). The bundle is `lib/client.js`, source in `client/client.js`, copied verbatim by `npm run build` — hand-written plain JS requiring only `react`, no bundler and no runtime dependency. When the host has no `webServer` service (a pure CLI composition) this layer is skipped silently; tools and slash commands are unaffected.
|
|
322
|
-
|
|
323
|
-
### Download cache (register-route template)
|
|
324
|
-
|
|
325
|
-
What the register route needs — CMSIS device headers, the startup file, core headers — is **not vendored into the plugin** (covering any STM32 part would make the package unusable), so it is downloaded on first use into a searchable cache directory and reused from then on:
|
|
326
|
-
|
|
327
|
-
- Location: `DSH_STM32_CACHE` (supports `~`) > `%LOCALAPPDATA%\dsh-stm32\cache`;
|
|
328
|
-
- Index: `index.json` under the cache root records each entry's source URLs, byte counts and license (`THIRD_PARTY_NOTICES.md` is written alongside);
|
|
329
|
-
- Sources: tried in the order `fastly.jsdelivr` → `cdn.jsdelivr` → `raw.githubusercontent` → `ghproxy`; an HTTP error, HTML-looking body or an implausible byte count counts as a failed source;
|
|
330
|
-
- A partial download is deleted outright (a half cache is worse than none); missing or size-mismatched files trigger a re-download on the next run;
|
|
331
|
-
- Visible and removable: `stm32_cache` with `list` / `verify` / `fetch` / `purge`.
|
|
332
|
-
|
|
333
|
-
### Firmware packages (HAL route)
|
|
334
|
-
|
|
335
|
-
Having CubeMX installed does not mean the package for **this particular part** is there — it is not part of the installer and has to be added in the package manager. `stm32_firmware_install` has two channels and tries the official one first:
|
|
336
|
-
|
|
337
|
-
- Official download (first step of `source: "auto"`): build `https://sw-center.st.com/packs/resource/firmware/stm32cube_fw_<family>_v<version digits>.zip` from the part's db `FwLibrary` (empty for most families, where the family name is used; H7RS / MP13 / WB0 / WL3 have their own), download it, verify `Content-Length` plus the CRC32 of every zip entry, then run CubeMX's `swmgr install <local zip> ask` to land it in `Repository` — this package is tracked by CubeMX itself, visible and removable in the package manager;
|
|
338
|
-
- Three failures are recorded in `notes` before falling back to the GitHub route below: no CubeMX installed, CubeMX GUI already running, and **the first install of a family/version, where CubeMX opens a licence dialog and waits for a human** (headless can only time out; the plugin never clicks it for you). With `source: "official"` this channel is the only one and failure is reported instead;
|
|
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.
|
|
339
271
|
|
|
340
|
-
|
|
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.
|
|
341
273
|
|
|
342
|
-
|
|
343
|
-
- Integrity: every archive comes from exactly one source, `codeload.github.com/<repo>/tar.gz/refs/heads/<ref>`, and every archive plus every core header is pinned by sha256 in `src/data/firmware-pins.ts` (regenerate with `scripts/firmware/pin-firmware.mjs`). A hash mismatch rejects the whole package before anything is unpacked; the error reports the expected and actual hashes when upstream master moves.
|
|
344
|
-
- Why the `STM32CubeF1` source archive is not enough: its HAL and CMSIS device directories are **git submodules**, so the tarball ships them empty — unpacking it yields a package that cannot compile (no startup file, no HAL sources);
|
|
345
|
-
- Where it lands: `<CubeMX root>/dsh-firmware/<package>` by default (a plugin-owned folder next to `Repository`, official packages untouched); only if that root is not writable does it fall back to the user cache. **Do not drop self-made version names into `Repository`** — measured: CubeMX does not recognise that version, silently falls back to the package it knows, and reports a successful generation with stale HAL files;
|
|
346
|
-
- How generation picks it up: `stm32_generate` resolves the package named in the `.ioc` (`ProjectManager.FirmwarePackage`), looking in both `Repository` and `<CubeMX root>/dsh-firmware`, and passes `project setCustomFWPath <package dir>` to the CubeMX script — the only mechanism proven to work, and it leaves no absolute path in the `.ioc`;
|
|
347
|
-
- The assembled package matches the official layout: a six-line `package.xml` (version tags `FW.<family>.<x.y.z>`) and `THIRD_PARTY_NOTICES.md`; `package.xml` carries no hash manifest (CubeMX does not verify provenance), because integrity is enforced per file by sha256 at download time — measured: generating with `setCustomFWPath` copies HAL sources byte-for-byte out of our directory;
|
|
348
|
-
- But "generation succeeded" proves nothing: with a non-existent package name in the `.ioc`, CubeMX prints no error, exits 0 and simply skips copying HAL. So five checks are mandatory (core headers / HAL Inc / HAL Src / device headers / `startup_*.s`), and the installer runs them right after assembling.
|
|
274
|
+
### Settings panel
|
|
349
275
|
|
|
350
|
-
|
|
276
|
+
The "STM32 toolchain" page under DSH settings offers three cards:
|
|
351
277
|
|
|
352
|
-
|
|
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.
|
|
353
281
|
|
|
354
|
-
|
|
355
|
-
| --- | --- |
|
|
356
|
-
| `jlink` | Downloads SEGGER 8.18.0 from the official direct link (~59 MB), hashing while it writes and comparing against `63110b6fc55e494d197d6efa156d7f61c0dd0c1f776424995a05407e2d7f566f`; an existing file with the right hash is reused; a failed or mismatched download deletes its temp file |
|
|
357
|
-
| `cubemx` / `cubeprogrammer` | ST requires a myST login and licence acceptance and direct links expire: the default is the official page; `dryRun:false + confirm:true` opens it in the browser. A downloaded `file: "D:/.../installer.exe"` is hashed so you can compare it yourself |
|
|
282
|
+
### Download cache and firmware packages
|
|
358
283
|
|
|
359
|
-
|
|
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.
|
|
360
287
|
|
|
361
288
|
### Environment variables (optional)
|
|
362
289
|
|
|
363
290
|
| Variable | Purpose | Default |
|
|
364
291
|
| --- | --- | --- |
|
|
365
|
-
| `STM32_BIN_DIRS` | Toolchain directory candidates, `;`-separated
|
|
366
|
-
| `STM32_CUBEMX_ROOT` |
|
|
367
|
-
| `STM32_NO_DISCOVER` | Set to `1`
|
|
368
|
-
| `DSH_STM32_CONFIG` |
|
|
369
|
-
| `DSH_STM32_NO_CONFIG` | Set to `1`
|
|
370
|
-
| `DSH_STM32_CACHE` | Download cache root
|
|
371
|
-
| `DSH_STM32_DOWNLOADS` | Installer download
|
|
372
|
-
| `
|
|
373
|
-
| `
|
|
374
|
-
| `
|
|
375
|
-
| `
|
|
376
|
-
| `
|
|
377
|
-
| `
|
|
378
|
-
| `
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
### openocd.cfg (in the project, takes precedence over built-in fallbacks)
|
|
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)
|
|
390
315
|
|
|
391
316
|
CMSIS-DAP (default):
|
|
392
317
|
|
|
@@ -396,7 +321,7 @@ source [find target/stm32f1x.cfg]
|
|
|
396
321
|
adapter speed 4000
|
|
397
322
|
```
|
|
398
323
|
|
|
399
|
-
ST-Link
|
|
324
|
+
ST-Link:
|
|
400
325
|
|
|
401
326
|
```text
|
|
402
327
|
source [find interface/stlink.cfg]
|
|
@@ -404,106 +329,81 @@ transport select hla_swd
|
|
|
404
329
|
source [find target/stm32f1x.cfg]
|
|
405
330
|
```
|
|
406
331
|
|
|
407
|
-
Without
|
|
408
|
-
C0 / U0 have no official script in openocd 0.12, so the plugin ships adapted copies: scaffolding puts them at `openocd/stm32c0x.cfg` (or `stm32u0x.cfg`) inside the project, `openocd.cfg` uses `source [find openocd/stm32c0x.cfg]` and `launch.json` uses `${workspaceFolder}/openocd/stm32c0x.cfg`. Families with no script at all (H5 / N6 / U3 / WBA / WB0 / WL3 / MP2) are **refused** instead of borrowing another family's script. ST-Link users put the second block into the project root as `openocd.cfg`.
|
|
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.
|
|
409
333
|
|
|
410
|
-
### Two hard requirements on the
|
|
334
|
+
### Two hard requirements on the `.ioc`
|
|
411
335
|
|
|
412
|
-
1. **SYS
|
|
413
|
-
2. **`ProjectManager.KeepUserCode=true`**; otherwise USER CODE is
|
|
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.
|
|
414
338
|
|
|
415
339
|
## Known limitations
|
|
416
340
|
|
|
417
|
-
| Limitation | Detail |
|
|
341
|
+
| Limitation | Detail | Handling |
|
|
418
342
|
| --- | --- | --- |
|
|
419
|
-
|
|
|
420
|
-
|
|
|
421
|
-
|
|
|
422
|
-
|
|
|
423
|
-
|
|
|
424
|
-
|
|
|
425
|
-
|
|
|
426
|
-
|
|
|
427
|
-
|
|
|
428
|
-
|
|
|
429
|
-
| **The 8 new register families passed independent acceptance** | 0.1.5 grows the register route from 13 to 21 families (+ H5 / H7 / L4+ / L5 / U3 / U5 / WBA / WL): all eight pass create→build with warning 0 / error 0 (per-family FLASH/RAM in development-notes §87.5); H7's per-family `-mcpu` and the missing `cachel1_armv7.h` were fixed in the template | independent acceptance (t8) passed: 21-family inventory, GPIO gates, linkerRam, 296 fact assertions, all eight rebuilt at exit 0 (development-notes §87.6); try the new eight with the parts listed in §87.5 |
|
|
430
|
-
| Register **symbol names and bit-field decoding need the bundled SVD (`full` logical tier)** | `GPIOC.ODR` / `GPIOC->ODR` and peripheral dumps (a bare `GPIOC`) are resolved from `assets/device/f1/svd/<line>.json`, derived from ST's SVDs (ST EULA, 1.71 MiB); only lines 100/101/102/103/105/107 exist. Without SVD data plain addresses still read, just with no names or bit fields; a symbol name fails with a hint to reinstall the plugin (the `full` tier ships in the package) | use `0x…` addresses; or run `stm32_assets verify` to check the install |
|
|
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 |
|
|
431
353
|
|
|
432
354
|
## Troubleshooting
|
|
433
355
|
|
|
434
|
-
| Symptom | Cause
|
|
435
|
-
| --- | --- |
|
|
436
|
-
| `ERR_PNPM_GIT_UNKNOWN_ERROR … connect ETIMEDOUT …:443` while installing | The **package fetch hop** cannot reach GitHub (`dsh plugin add github:…` clones over git). It is unrelated to the pnpm 11 `allowBuilds` allow-list, package signatures, or a broken tarball — the same command works from another network. Three options, easiest first: (1) install the published package: `dsh plugin --profile desktop add dsh-stm32` (npm registry, no GitHub); (2) if you must install from GitHub, proxy **only that one command** with process-scoped `GIT_CONFIG_*` (your global git config stays untouched): `$env:GIT_CONFIG_COUNT="1"; $env:GIT_CONFIG_KEY_0="http.https://github.com.proxy"; $env:GIT_CONFIG_VALUE_0="http://127.0.0.1:7890"; dsh plugin --profile desktop add github:JingYu-er/dsh-stm32#main` (use your own port); (3) skip git entirely and take the HTTPS tarball: `dsh plugin --profile desktop add https://codeload.github.com/JingYu-er/dsh-stm32/tar.gz/refs/heads/main`. For the newest code use `github:JingYu-er/dsh-stm32#main`; for a published release use `dsh-stm32@latest` — same content, no GitHub dependency |
|
|
437
|
-
| SWD lost after flashing | The firmware generated `__HAL_AFIO_REMAP_SWJ_DISABLE()`. Hold BOOT0 while powering up to enter the system bootloader and reflash, then set SYS back to Serial Wire — `stm32_flash` now blocks this case first |
|
|
438
|
-
| `Error: No device found` / `transfer count mismatch` | Another process holds the probe. Run `/stm32-stop`, then use `stm32_doctor` to inspect openocd / gdb processes and port 3333. Reading registers while a debug session is open no longer hits this: `stm32_regs_read` reuses the session's openocd instead of starting a second one |
|
|
439
|
-
| Reading registers with a live session shows a `gdb-multiarch … target extended-remote 127.0.0.1:3333` `report.command` | That is the normal "reuse" shape: while `stm32_debug_session` is alive, `stm32_regs_read` borrows that session's openocd and the notes say "reusing the debug session (gdb port N, tcl port M), no extra openocd". Since B3 the default path is **direct Tcl RPC** (one TCP connection: halt → read pc → consecutive `mdw` → resume, milliseconds), so a `gdb-multiarch …` `report.command` only means the Tcl fast path failed and it fell back to the session's gdb — the reason is in the notes. Only without a session does it start its own openocd. Older builds failed here with `CMSIS-DAP transfer count mismatch: expected N, got M` |
|
|
440
|
-
| Build "succeeds" but the old firmware runs | The project was copied or renamed with `build/` included: the CMakeCache directory no longer matches, yet ninja still exits 0. `stm32_build` treats that as a failure; clean or delete `build/Debug` as prompted |
|
|
441
|
-
| A tool answers "missing arm-none-eabi-gcc …, X was not started" | That is the pre-flight gate (`envCheck` defaults to `block`) doing its job, not a bug: it is cheaper than discovering the problem halfway through. Answer "install", and the model runs `stm32_env_install` for a plan; after you confirm, the toolchain is installed and the config written — **the next call works without a restart**. Run `/stm32-env` for the whole picture, or pass `envCheck: "warn"` (continue with a warning) / `"off"` (skip the check) |
|
|
442
|
-
| The first project build answers "device facts are not ready …" | The chip table ships inside the package (`assets/device/f1/chips.json`), so a normal install never hits this. It means the plugin install is incomplete: run `stm32_assets verify` to list missing files, then reinstall the plugin (offline is fine); `DSH_STM32_ASSETS` is only a development override |
|
|
443
|
-
| `stm32_doctor` cannot find gcc / openocd | First read the "searched ..." list and the auto-discovery line in the doctor notes / error; if it is installed elsewhere, set `STM32_BIN_DIRS` or pass `binDirs`. **If you do not know what to install, run `stm32_doctor` first**: every missing component carries `impact` (what stops working), `install` (recommended way, easiest first) and `verify` (self-check after installing), while the top-level `recommendations` gives the install order and offers to install for you |
|
|
444
|
-
| `stm32_generate` feels stuck | The first run (cold start, no cache) legitimately takes 3.5–4 minutes; later runs are skipped (<1 s) while the `.ioc` and outputs are unchanged. It runs as a background job by default — watch it with `job_output`, or pass `foreground: true`. Check `skipped` in the result and the reason in the notes to see whether the cache hit |
|
|
445
|
-
| It regenerates for 3 minutes even though nothing changed | The cache key covers the CubeMX `size:mtime` and every output hash, so swapping CubeMX, editing generated files or changing the layout invalidates it. Read the reason in the notes, or delete `.dsh-stm32/generate-cache.json` |
|
|
446
|
-
| Generate got faster but the CubeMX GUI no longer lists expansion packs | With `thirdpartyPacks: "auto"` the `thirdparties/pdsc` directory is parked as `pdsc.dsh-parked` when no pack is needed and restored after the run. Pass `thirdpartyPacks: "keep"` while picking packs by hand in the CubeMX GUI |
|
|
447
|
-
| The notes say the local pack index has no such pack | An X-CUBE pack the project needs is not installed here (the decision matches `Mcu.ThirdParty<k>` in the `.ioc` against the built-in catalog by name). Install it in the CubeMX *Manage embedded software packages* dialog, then generate again. This note also shows up in **failed** generate reports (a timeout or a CubeMX error still carries the notes — read them before guessing). The catalog is a snapshot: after installing new packs, rerun `node scripts/gen-xcube-catalog.mjs` (an older catalog only fails to recognise new packs, it never wrongly decides the index is unnecessary) |
|
|
448
|
-
| `stm32_code_patch` says the block does not exist | `main.c` uses short labels (`PV` = private variables, `PFP` = prototypes, `2` = init before while, `3` = loop body); the error lists every available label — copy one from there |
|
|
449
|
-
|
|
450
|
-
## Development and testing
|
|
451
|
-
|
|
452
|
-
```powershell
|
|
453
|
-
npm run build # tsc -> lib/ (lib/ is committed: rebuild before you commit)
|
|
454
|
-
npm test # 60 offline suites, 947 cases; no board, CubeMX, or toolchain needed
|
|
455
|
-
npm run test:pack # pack a tarball, unpack it, scaffold a real register project from the unpacked lib
|
|
456
|
-
npm run test:size # package guard: tarball <=3.9 MB, runtime assets under templates/ (.ioc/.xml/.ld/.json/.cfg) <=40 KB, no binaries/diagrams inside
|
|
457
|
-
```
|
|
458
|
-
|
|
459
|
-
CI (`.github/workflows/ci.yml`) runs `npm ci → build → check that the committed lib/ matches src/ → npm test → test:pack → test:size` on every push and PR (windows-latest).
|
|
460
|
-
|
|
461
|
-
A GitHub runner has neither msys64 nor CubeMX, so two scaffolding cases that need the real firmware package are skipped: CI skips those two; a developer machine runs all **947 pass / 0 fail**. The offline suites only read the bundled [`test/fixtures/`](test/fixtures/README.md); the session cases build a fake toolchain directory with `fakeBinDirs()` (empty placeholder files for openocd / gdb), so nothing depends on what is installed locally.
|
|
462
|
-
|
|
463
|
-
### What ships where (decide before you add a file)
|
|
464
|
-
|
|
465
|
-
| Where | What | Size |
|
|
356
|
+
| Symptom | Cause | Action |
|
|
466
357
|
| --- | --- | --- |
|
|
467
|
-
|
|
|
468
|
-
|
|
|
469
|
-
|
|
|
470
|
-
|
|
|
471
|
-
|
|
|
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 |
|
|
472
366
|
|
|
473
|
-
|
|
367
|
+
## Development and testing
|
|
474
368
|
|
|
475
|
-
|
|
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 |
|
|
476
376
|
|
|
477
|
-
|
|
478
|
-
$env:DSH_STM32_E2E_PROJECT = 'D:\work\my-stm32'
|
|
479
|
-
node test\e2e-flash.mjs
|
|
480
|
-
```
|
|
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.
|
|
481
378
|
|
|
482
|
-
|
|
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.
|
|
483
380
|
|
|
484
381
|
## Repository layout
|
|
485
382
|
|
|
486
383
|
```text
|
|
487
384
|
src/
|
|
488
|
-
index.ts
|
|
489
|
-
tools/
|
|
490
|
-
engine/
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
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
|
|
498
398
|
```
|
|
499
399
|
|
|
500
400
|
## Documentation
|
|
501
401
|
|
|
502
|
-
- [Specification](docs/dsh-stm32-plugin-规格.md): tool contracts, state machine, acceptance criteria
|
|
503
|
-
- [Development notes](docs/development-notes.md): milestones, host-contract
|
|
504
|
-
- [Source reading guide](docs/reading-guide.md): layered reading order, per-file responsibilities and exports,
|
|
505
|
-
-
|
|
506
|
-
- Visuals: [architecture](docs/diagrams/dsh-stm32-architecture.html) / [main journey](docs/diagrams/dsh-stm32-journey.html) — single-file HTML, opens offline
|
|
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
|
|
507
407
|
|
|
508
408
|
## License
|
|
509
409
|
|