dsh-stm32 0.1.0 → 0.1.1
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 +85 -16
- package/README_EN.md +84 -17
- package/client/client.js +682 -0
- package/docs/development-notes.md +920 -2
- package/docs/logic-audit.md +607 -0
- package/lib/client.js +682 -0
- package/lib/commands/register.js +165 -12
- package/lib/data/cmsis-sources.js +147 -0
- package/lib/data/firmware-packages.js +352 -0
- package/lib/data/install-guides.js +190 -0
- package/lib/data/search-roots.js +135 -15
- package/lib/data/toolchain-config.js +310 -0
- package/lib/engine/build.js +6 -0
- package/lib/engine/cache.js +280 -0
- package/lib/engine/code-patch.js +18 -6
- package/lib/engine/debug-session.js +163 -4
- package/lib/engine/debug.js +9 -9
- package/lib/engine/fetch.js +143 -0
- package/lib/engine/firmware-install.js +668 -0
- package/lib/engine/flash.js +51 -10
- package/lib/engine/fs-longpath.js +107 -0
- package/lib/engine/generate-cache.js +118 -0
- package/lib/engine/generate-script.js +30 -8
- package/lib/engine/generate.js +285 -14
- package/lib/engine/ioc-plan.js +19 -6
- package/lib/engine/msys2-install.js +1599 -0
- package/lib/engine/probe.js +57 -6
- package/lib/engine/register-template.js +378 -0
- package/lib/engine/regs.js +18 -4
- package/lib/engine/route-plan.js +553 -0
- package/lib/engine/scaffold.js +225 -70
- package/lib/engine/subprocess-runner.js +2 -0
- package/lib/engine/tar.js +250 -0
- package/lib/engine/text-file.js +150 -0
- package/lib/engine/thirdparty.js +243 -0
- package/lib/engine/tool-env.js +51 -0
- package/lib/engine/toolchain-gate.js +386 -0
- package/lib/engine/vscode-config.js +99 -0
- package/lib/engine/web-api.js +375 -0
- package/lib/engine/web-routes.js +100 -0
- package/lib/engine/xcube-catalog.js +102 -0
- package/lib/engine/xcube.js +254 -0
- package/lib/index.js +42 -2
- package/lib/skill/stm32-workflow.js +1 -1
- package/lib/tools/build.js +43 -3
- package/lib/tools/cache.js +219 -0
- package/lib/tools/code-patch.js +29 -2
- package/lib/tools/debug-session.js +56 -14
- package/lib/tools/debug.js +36 -2
- package/lib/tools/doctor.js +5 -1
- package/lib/tools/env-install.js +472 -0
- package/lib/tools/env-probe.js +6 -2
- package/lib/tools/firmware-install.js +255 -0
- package/lib/tools/flash.js +38 -2
- package/lib/tools/generate.js +96 -10
- package/lib/tools/ioc-apply.js +27 -11
- package/lib/tools/ioc-inspect.js +4 -2
- package/lib/tools/ioc-plan.js +14 -7
- package/lib/tools/project-create.js +204 -21
- package/lib/tools/project-dir.js +95 -0
- package/lib/tools/regs.js +82 -7
- package/lib/tools/route-plan.js +467 -0
- package/package.json +7 -2
- package/templates/register/CMakeLists.txt +39 -0
- package/templates/register/Core/Src/main.c +63 -0
- package/templates/scaffold/vscode/launch.json +8 -6
- package/templates/scaffold/vscode/settings.json +5 -11
|
@@ -0,0 +1,352 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 固件包(STM32Cube_FW_<族>_V<版本>)的组装清单。
|
|
3
|
+
*
|
|
4
|
+
* 背景(2026-10 实测,见 docs §14):ST 的固件包不是整体下载的,GitHub 上的 STM32Cube<族>
|
|
5
|
+
* 主仓库把 HAL 驱动与 CMSIS 设备支持都挂成了 git 子模块 —— 只拉主仓库 tarball,
|
|
6
|
+
* Drivers/STM32F1xx_HAL_Driver 与 Drivers/CMSIS/Device/ST/STM32F1xx 是**空目录**,
|
|
7
|
+
* 编译必挂。所以要分别拉:
|
|
8
|
+
* ① HAL 驱动仓库(stm32f1xx-hal-driver)→ Drivers/STM32F1xx_HAL_Driver/{Inc,Src}
|
|
9
|
+
* ② CMSIS 设备仓库(cmsis-device-f1) → Drivers/CMSIS/Device/ST/STM32F1xx/{Include,Source}
|
|
10
|
+
* ③ CMSIS 内核头(STM32CubeF1 主仓库 Drivers/CMSIS/Include 下的 5 个头文件,逐个拉)
|
|
11
|
+
* 然后自己补一个 257 字节的 package.xml —— 实测 CubeMX 认这种手工组装的包(docs §14)。
|
|
12
|
+
*
|
|
13
|
+
* 只登记实测过的一代:F1。其它代按同样字段补一条即可(repo 名、目录名、内核头不同)。
|
|
14
|
+
*/
|
|
15
|
+
import { existsSync, readdirSync } from "node:fs";
|
|
16
|
+
import { sourceUrls } from "./cmsis-sources.js";
|
|
17
|
+
/** codeload 直连是首选;GHProxy 走镜像;api.github.com 的 tarball 会 302 到 codeload,作最后兜底。 */
|
|
18
|
+
function archiveUrls(repo, ref) {
|
|
19
|
+
return [
|
|
20
|
+
"https://codeload.github.com/STMicroelectronics/" + repo + "/tar.gz/refs/heads/" + ref,
|
|
21
|
+
"https://ghproxy.net/https://github.com/STMicroelectronics/" + repo + "/archive/refs/heads/" + ref + ".tar.gz",
|
|
22
|
+
"https://api.github.com/repos/STMicroelectronics/" + repo + "/tarball/refs/heads/" + ref,
|
|
23
|
+
];
|
|
24
|
+
}
|
|
25
|
+
export const FIRMWARE_FAMILIES = {
|
|
26
|
+
F1: {
|
|
27
|
+
family: "F1",
|
|
28
|
+
packageBase: "STM32Cube_FW_F1",
|
|
29
|
+
defaultVersion: "1.8.7",
|
|
30
|
+
halDir: "Drivers/STM32F1xx_HAL_Driver",
|
|
31
|
+
deviceDir: "Drivers/CMSIS/Device/ST/STM32F1xx",
|
|
32
|
+
coreRepo: "STM32CubeF1",
|
|
33
|
+
coreRef: "master",
|
|
34
|
+
coreIncludeDir: "Drivers/CMSIS/Include",
|
|
35
|
+
coreHeaders: ["core_cm3.h", "cmsis_compiler.h", "cmsis_gcc.h", "cmsis_version.h", "mpu_armv7.h"],
|
|
36
|
+
archives: [
|
|
37
|
+
{
|
|
38
|
+
id: "hal",
|
|
39
|
+
label: "HAL 驱动(stm32f1xx-hal-driver)",
|
|
40
|
+
repo: "stm32f1xx-hal-driver",
|
|
41
|
+
ref: "master",
|
|
42
|
+
dirs: [
|
|
43
|
+
{ from: "Inc", to: "Drivers/STM32F1xx_HAL_Driver/Inc" },
|
|
44
|
+
{ from: "Src", to: "Drivers/STM32F1xx_HAL_Driver/Src" },
|
|
45
|
+
],
|
|
46
|
+
urls: archiveUrls("stm32f1xx-hal-driver", "master"),
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
id: "device",
|
|
50
|
+
label: "CMSIS 设备支持(cmsis-device-f1)",
|
|
51
|
+
repo: "cmsis-device-f1",
|
|
52
|
+
ref: "master",
|
|
53
|
+
dirs: [
|
|
54
|
+
{ from: "Include", to: "Drivers/CMSIS/Device/ST/STM32F1xx/Include" },
|
|
55
|
+
{ from: "Source", to: "Drivers/CMSIS/Device/ST/STM32F1xx/Source" },
|
|
56
|
+
],
|
|
57
|
+
urls: archiveUrls("cmsis-device-f1", "master"),
|
|
58
|
+
},
|
|
59
|
+
],
|
|
60
|
+
},
|
|
61
|
+
};
|
|
62
|
+
/** 从型号(STM32F103C8T6)或族名(F1)里认族;认不出返回空串。 */
|
|
63
|
+
export function firmwareFamilyOf(text) {
|
|
64
|
+
const raw = text.trim().toUpperCase();
|
|
65
|
+
if (raw in FIRMWARE_FAMILIES)
|
|
66
|
+
return raw;
|
|
67
|
+
const match = /^STM32([A-Z])(\d)/u.exec(raw);
|
|
68
|
+
if (match === null)
|
|
69
|
+
return "";
|
|
70
|
+
const family = (match[1] ?? "") + (match[2] ?? "");
|
|
71
|
+
return family in FIRMWARE_FAMILIES ? family : "";
|
|
72
|
+
}
|
|
73
|
+
/** 版本串规则(实测 ST 真包):1.8.7 → Release FW.F1.1.8.0 / Patch FW.F1.1.8.7。 */
|
|
74
|
+
export function firmwareVersionTags(family, version) {
|
|
75
|
+
const parts = version.split(".");
|
|
76
|
+
const a = parts[0] ?? "0";
|
|
77
|
+
const b = parts[1] ?? "0";
|
|
78
|
+
const c = parts[2] ?? "0";
|
|
79
|
+
return { release: "FW." + family + "." + a + "." + b + ".0", patch: "FW." + family + "." + a + "." + b + "." + c };
|
|
80
|
+
}
|
|
81
|
+
/** package.xml 全文:真包就 257 字节这么多,CubeMX 不看哈希也不校验来源。 */
|
|
82
|
+
export function packageXmlText(tags) {
|
|
83
|
+
return [
|
|
84
|
+
'<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>',
|
|
85
|
+
'<Package DBVersion="2.0">',
|
|
86
|
+
' <PackDescription Release="' + tags.release + '" Patch="' + tags.patch + '">',
|
|
87
|
+
' <Note Release="ReleaseNotes.html" Patch="ReleaseNotes_Patch.html"/>',
|
|
88
|
+
" </PackDescription>",
|
|
89
|
+
"</Package>",
|
|
90
|
+
"",
|
|
91
|
+
].join("\n");
|
|
92
|
+
}
|
|
93
|
+
function emptyPlan(error, family = "", version = "") {
|
|
94
|
+
return {
|
|
95
|
+
ok: false,
|
|
96
|
+
error,
|
|
97
|
+
family,
|
|
98
|
+
version,
|
|
99
|
+
packageBase: "",
|
|
100
|
+
dirName: "",
|
|
101
|
+
releaseTag: "",
|
|
102
|
+
patchTag: "",
|
|
103
|
+
packageXml: "",
|
|
104
|
+
halDir: "",
|
|
105
|
+
deviceDir: "",
|
|
106
|
+
archives: [],
|
|
107
|
+
coreTargets: [],
|
|
108
|
+
license: "",
|
|
109
|
+
};
|
|
110
|
+
}
|
|
111
|
+
/** 组一代固件包的下载/组装计划。纯计算,不碰磁盘也不联网。 */
|
|
112
|
+
export function firmwarePlanFor(request) {
|
|
113
|
+
const hint = request.family ?? request.mcu ?? "";
|
|
114
|
+
if (hint.trim() === "")
|
|
115
|
+
return emptyPlan("没说清要哪一代的固件包:给 family(例如 F1)或 mcu(例如 STM32F103C8T6)");
|
|
116
|
+
const family = firmwareFamilyOf(hint);
|
|
117
|
+
if (family === "") {
|
|
118
|
+
const known = Object.keys(FIRMWARE_FAMILIES).join("、");
|
|
119
|
+
return emptyPlan("插件还不会给 " + hint.trim() + " 自动组装固件包(目前只会:" + known + ")。可以在 CubeMX 的包管理器里装,见 guides 里的手动安装步骤。");
|
|
120
|
+
}
|
|
121
|
+
const spec = FIRMWARE_FAMILIES[family];
|
|
122
|
+
if (spec === undefined)
|
|
123
|
+
return emptyPlan("插件里没有 " + family + " 的固件包清单");
|
|
124
|
+
const version = (request.version ?? spec.defaultVersion).replace(/^[Vv]/u, "");
|
|
125
|
+
if (!/^\d+\.\d+\.\d+$/u.test(version)) {
|
|
126
|
+
return emptyPlan("版本号格式不对:" + version + "(要 1.8.7 这种三段式)", family);
|
|
127
|
+
}
|
|
128
|
+
const tags = firmwareVersionTags(family, version);
|
|
129
|
+
const dirName = spec.packageBase + "_V" + version;
|
|
130
|
+
const coreTargets = spec.coreHeaders.map((header) => ({
|
|
131
|
+
path: header,
|
|
132
|
+
urls: sourceUrls(spec.coreRepo, spec.coreRef, spec.coreIncludeDir + "/" + header),
|
|
133
|
+
minBytes: 500,
|
|
134
|
+
}));
|
|
135
|
+
const license = [
|
|
136
|
+
"# 第三方声明",
|
|
137
|
+
"",
|
|
138
|
+
"本目录是 STM32 固件包的**手工组装件**,由 dsh-stm32 从 GitHub 公开仓库下载拼装而成,",
|
|
139
|
+
"不是 ST 官方发布的安装包。各部分的许可如下:",
|
|
140
|
+
"",
|
|
141
|
+
"- HAL 驱动(stm32f1xx-hal-driver):ST 发布,BSD-3-Clause(见 ST 原文 LICENSE.md)。",
|
|
142
|
+
"- CMSIS 设备支持(cmsis-device-f1):Apache-2.0。",
|
|
143
|
+
"- CMSIS 内核头(STM32CubeF1 / Drivers/CMSIS/Include):Apache-2.0。",
|
|
144
|
+
"",
|
|
145
|
+
"CubeMX 认这个目录(实测),但 ST 的包管理器不会维护它:要升级请用 CubeMX 包管理器重装官方包。",
|
|
146
|
+
"",
|
|
147
|
+
].join("\n");
|
|
148
|
+
return {
|
|
149
|
+
ok: true,
|
|
150
|
+
error: "",
|
|
151
|
+
family,
|
|
152
|
+
version,
|
|
153
|
+
packageBase: spec.packageBase,
|
|
154
|
+
dirName,
|
|
155
|
+
releaseTag: tags.release,
|
|
156
|
+
patchTag: tags.patch,
|
|
157
|
+
packageXml: packageXmlText(tags),
|
|
158
|
+
halDir: spec.halDir,
|
|
159
|
+
deviceDir: spec.deviceDir,
|
|
160
|
+
archives: spec.archives,
|
|
161
|
+
coreTargets,
|
|
162
|
+
license,
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
function hasFiles(dir) {
|
|
166
|
+
try {
|
|
167
|
+
return readdirSync(dir).length > 0;
|
|
168
|
+
}
|
|
169
|
+
catch {
|
|
170
|
+
return false;
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
/** 目录里有没有 startup_*.s(启动文件按容量档分好几个,有一个就够)。 */
|
|
174
|
+
function hasStartup(dir) {
|
|
175
|
+
try {
|
|
176
|
+
return readdirSync(dir).some((name) => /^startup_.*\.s$/iu.test(name));
|
|
177
|
+
}
|
|
178
|
+
catch {
|
|
179
|
+
return false;
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* 三条判据(与 scaffold.ts 的 resolveFirmwareRoot 一致,多加一条 startup 检查):
|
|
184
|
+
* ① Drivers/CMSIS/Include 有内核头 ② Drivers/<族>_HAL_Driver 有 Inc 与 Src
|
|
185
|
+
* ③ Drivers/CMSIS/Device/ST/<族>/{Include,Source/Templates/gcc/startup_*.s}
|
|
186
|
+
* 为什么必须自查:CubeMX 找不到包时**不报错**(docs §14),只看它打印 Code succesfully generated 会被骗。
|
|
187
|
+
*/
|
|
188
|
+
export function verifyFirmwarePackage(root, family) {
|
|
189
|
+
const spec = FIRMWARE_FAMILIES[family];
|
|
190
|
+
const checks = [];
|
|
191
|
+
if (spec === undefined) {
|
|
192
|
+
return { ok: false, checks, missing: ["插件里没有 " + family + " 的固件包清单"] };
|
|
193
|
+
}
|
|
194
|
+
const join = (rel) => root.replace(/[\\/]+$/u, "") + "/" + rel;
|
|
195
|
+
const cmsisDir = join("Drivers/CMSIS/Include");
|
|
196
|
+
checks.push({
|
|
197
|
+
label: "CMSIS 内核头",
|
|
198
|
+
path: cmsisDir,
|
|
199
|
+
ok: spec.coreHeaders.every((header) => existsSync(join("Drivers/CMSIS/Include/" + header))),
|
|
200
|
+
});
|
|
201
|
+
const halInc = join(spec.halDir + "/Inc");
|
|
202
|
+
const halSrc = join(spec.halDir + "/Src");
|
|
203
|
+
checks.push({ label: "HAL 驱动 Inc", path: halInc, ok: hasFiles(halInc) });
|
|
204
|
+
checks.push({ label: "HAL 驱动 Src", path: halSrc, ok: hasFiles(halSrc) });
|
|
205
|
+
const deviceInclude = join(spec.deviceDir + "/Include");
|
|
206
|
+
checks.push({ label: "设备头 Include", path: deviceInclude, ok: hasFiles(deviceInclude) });
|
|
207
|
+
const templateDir = join(spec.deviceDir + "/Source/Templates/gcc");
|
|
208
|
+
checks.push({ label: "启动文件(gcc)", path: templateDir, ok: hasStartup(templateDir) });
|
|
209
|
+
const missing = checks.filter((check) => !check.ok).map((check) => check.label);
|
|
210
|
+
return { ok: missing.length === 0, checks, missing };
|
|
211
|
+
}
|
|
212
|
+
/* ---------------------------- 找包 / 认包 ---------------------------- */
|
|
213
|
+
/** 插件在 CubeMX 安装根里自建的固件包目录(与 Repository 并列,绝不动 Repository)。 */
|
|
214
|
+
export const DSH_FIRMWARE_DIR_NAME = "dsh-firmware";
|
|
215
|
+
/** <cubeMxRoot>/dsh-firmware(正斜杠,去掉根尾部斜杠)。 */
|
|
216
|
+
export function dshFirmwareDir(cubeMxRoot) {
|
|
217
|
+
const base = cubeMxRoot.trim().split("\\").join("/").replace(/\/+$/u, "");
|
|
218
|
+
return base + "/" + DSH_FIRMWARE_DIR_NAME;
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* 从 .ioc 正文里读它要哪个固件包。
|
|
222
|
+
* 首选 ProjectManager.FirmwarePackage=STM32Cube FW_F1 V1.8.7;
|
|
223
|
+
* 缺这一条时退回 Mcu.CPN 推族 + 该族默认版本。
|
|
224
|
+
*/
|
|
225
|
+
export function firmwareNeedFromIoc(text) {
|
|
226
|
+
const packaged = /ProjectManager\.FirmwarePackage\s*=\s*STM32Cube\s+FW_([A-Za-z]\d)\s+[Vv]?([0-9][0-9.]*)/u.exec(text);
|
|
227
|
+
if (packaged !== null) {
|
|
228
|
+
const family = (packaged[1] ?? "").toUpperCase();
|
|
229
|
+
const version = (packaged[2] ?? "").replace(/\.+$/u, "");
|
|
230
|
+
if (family !== "" && version !== "") {
|
|
231
|
+
return { family, version, packageName: "STM32Cube_FW_" + family + "_V" + version };
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
const mcu = /(?:Mcu\.CPN|Mcu\.Name)\s*=\s*(STM32[A-Za-z0-9]+)/u.exec(text);
|
|
235
|
+
if (mcu !== null) {
|
|
236
|
+
const family = firmwareFamilyOf(mcu[1] ?? "");
|
|
237
|
+
const spec = family === "" ? undefined : FIRMWARE_FAMILIES[family];
|
|
238
|
+
if (spec !== undefined) {
|
|
239
|
+
return { family, version: spec.defaultVersion, packageName: spec.packageBase + "_V" + spec.defaultVersion };
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
return { family: "", version: "", packageName: "" };
|
|
243
|
+
}
|
|
244
|
+
/**
|
|
245
|
+
* 不认具体族也能判「这目录像个固件包」:CMSIS 内核头 + 至少一个 HAL 驱动的 Src。
|
|
246
|
+
* 用在找包上(G4/H7 这类插件还没有清单的族也照样能找到官方包)。
|
|
247
|
+
*/
|
|
248
|
+
export function looksLikeFirmwarePackage(root) {
|
|
249
|
+
const dir = root.trim().replace(/[\\/]+$/u, "");
|
|
250
|
+
const driversDir = dir + "/Drivers";
|
|
251
|
+
if (!existsSync(driversDir + "/CMSIS/Include"))
|
|
252
|
+
return false;
|
|
253
|
+
let names;
|
|
254
|
+
try {
|
|
255
|
+
names = readdirSync(driversDir);
|
|
256
|
+
}
|
|
257
|
+
catch {
|
|
258
|
+
return false;
|
|
259
|
+
}
|
|
260
|
+
return names.some((name) => /_HAL_Driver$/u.test(name) && existsSync(driversDir + "/" + name + "/Src"));
|
|
261
|
+
}
|
|
262
|
+
/** 来源的人话。报告、进度、终端文案都从这里取,避免各处各写一份两值三元把 cache/custom 漏成空标签。 */
|
|
263
|
+
export function firmwareSourceLabel(source) {
|
|
264
|
+
switch (source) {
|
|
265
|
+
case "repository":
|
|
266
|
+
return "CubeMX 仓库";
|
|
267
|
+
case "dsh-firmware":
|
|
268
|
+
return "插件的 dsh-firmware 目录";
|
|
269
|
+
case "cache":
|
|
270
|
+
return "插件的下载缓存";
|
|
271
|
+
case "custom":
|
|
272
|
+
return "调用方指定的目录";
|
|
273
|
+
default:
|
|
274
|
+
return "";
|
|
275
|
+
}
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* 在 CubeMX 根下找 .ioc 要的固件包。两处都找:Repository(官方)与 dsh-firmware(插件组装)。
|
|
279
|
+
* 排序:包名精确匹配最优先 → 版本号大的 → 同版本优先 Repository。
|
|
280
|
+
* 为什么两处都找:官方包零拷贝直接用;没有官方包时才用我们组装的那份。
|
|
281
|
+
*/
|
|
282
|
+
export function locateFirmwarePackage(cubeMxRoots, request = {}) {
|
|
283
|
+
const wanted = (request.packageName ?? "").trim();
|
|
284
|
+
const family = (request.family ?? "").trim().toUpperCase();
|
|
285
|
+
const checked = [];
|
|
286
|
+
const found = [];
|
|
287
|
+
const accept = (parent, source) => {
|
|
288
|
+
let names;
|
|
289
|
+
try {
|
|
290
|
+
names = readdirSync(parent);
|
|
291
|
+
}
|
|
292
|
+
catch {
|
|
293
|
+
return;
|
|
294
|
+
}
|
|
295
|
+
for (const name of names) {
|
|
296
|
+
if (!/^STM32Cube_FW_[A-Za-z0-9]+_V[0-9.]+$/u.test(name))
|
|
297
|
+
continue;
|
|
298
|
+
if (family !== "" && !name.startsWith("STM32Cube_FW_" + family + "_"))
|
|
299
|
+
continue;
|
|
300
|
+
const dir = parent + "/" + name;
|
|
301
|
+
if (!looksLikeFirmwarePackage(dir))
|
|
302
|
+
continue;
|
|
303
|
+
found.push({ dir, dirName: name, source });
|
|
304
|
+
}
|
|
305
|
+
};
|
|
306
|
+
for (const root of cubeMxRoots) {
|
|
307
|
+
const base = root.trim().replace(/[\\/]+$/u, "");
|
|
308
|
+
if (base === "")
|
|
309
|
+
continue;
|
|
310
|
+
// <root>/Repository 里是包目录们;<root>/dsh-firmware 同理。
|
|
311
|
+
checked.push(base + "/Repository");
|
|
312
|
+
accept(base + "/Repository", "repository");
|
|
313
|
+
checked.push(dshFirmwareDir(base));
|
|
314
|
+
accept(dshFirmwareDir(base), "dsh-firmware");
|
|
315
|
+
}
|
|
316
|
+
for (const extra of request.extraDirs ?? []) {
|
|
317
|
+
const dir = extra.dir.trim().split("\\").join("/").replace(/\/+$/u, "");
|
|
318
|
+
if (dir === "")
|
|
319
|
+
continue;
|
|
320
|
+
checked.push(dir);
|
|
321
|
+
const own = dir.split("/").pop() ?? "";
|
|
322
|
+
if (/^STM32Cube_FW_[A-Za-z0-9]+_V[0-9.]+$/u.test(own)) {
|
|
323
|
+
// 显式 targetDir 就是包本身,不是包目录的父目录。
|
|
324
|
+
if (family !== "" && !own.startsWith("STM32Cube_FW_" + family + "_"))
|
|
325
|
+
continue;
|
|
326
|
+
if (looksLikeFirmwarePackage(dir))
|
|
327
|
+
found.push({ dir, dirName: own, source: extra.source });
|
|
328
|
+
continue;
|
|
329
|
+
}
|
|
330
|
+
accept(dir, extra.source);
|
|
331
|
+
}
|
|
332
|
+
const ranked = found.sort((left, right) => {
|
|
333
|
+
const leftExact = wanted !== "" && left.dirName === wanted ? 1 : 0;
|
|
334
|
+
const rightExact = wanted !== "" && right.dirName === wanted ? 1 : 0;
|
|
335
|
+
if (leftExact !== rightExact)
|
|
336
|
+
return rightExact - leftExact;
|
|
337
|
+
const leftVersion = left.dirName.replace(/^.*_V/u, "");
|
|
338
|
+
const rightVersion = right.dirName.replace(/^.*_V/u, "");
|
|
339
|
+
if (leftVersion !== rightVersion)
|
|
340
|
+
return rightVersion.localeCompare(leftVersion, "en", { numeric: true });
|
|
341
|
+
// 同一个包名+版本出现在多处时:官方仓库 > dsh-firmware > 指定目录 > 下载缓存。
|
|
342
|
+
const rank = (source) => source === "repository" ? 0 : source === "dsh-firmware" ? 1 : source === "custom" ? 2 : source === "cache" ? 3 : 9;
|
|
343
|
+
if (left.source !== right.source)
|
|
344
|
+
return rank(left.source) - rank(right.source);
|
|
345
|
+
return 0;
|
|
346
|
+
});
|
|
347
|
+
const best = ranked[0];
|
|
348
|
+
if (best === undefined) {
|
|
349
|
+
return { found: false, dir: "", packageName: wanted, family, source: "", checked };
|
|
350
|
+
}
|
|
351
|
+
return { found: true, dir: best.dir, packageName: best.dirName, family, source: best.source, checked };
|
|
352
|
+
}
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* L1:装不上(或不该由插件代装)的东西,怎么把话说清楚。
|
|
3
|
+
*
|
|
4
|
+
* 门禁把缺件分成两档,因为这两档的"下一步"完全不同:
|
|
5
|
+
* auto —— MSYS2 里一条 pacman 就能补(gcc / gdb / openocd / cmake / ninja),
|
|
6
|
+
* 插件能跑 stm32_env_install 出计划、确认后自己装;
|
|
7
|
+
* manual —— 装不了或不该代装:STM32CubeMX 是 InstallAnywhere 的 GUI 向导(要 ST 账号 +
|
|
8
|
+
* 同意许可),固件包只由 CubeMX 的包管理器维护(st.com 包清单 + 22 个 git 子模块)。
|
|
9
|
+
* 这两样只能给人一步步的指引,插件顶多帮它把路径写进配置。
|
|
10
|
+
*
|
|
11
|
+
* 本文件只有文案与元数据,不起进程、不读盘,便于单测与审计(改文案不用碰引擎)。
|
|
12
|
+
*/
|
|
13
|
+
import { FIRMWARE_FAMILIES } from "./firmware-packages.js";
|
|
14
|
+
/** 组件 → 安装方式。没列的按 auto 处理(默认乐观:pacman 能补的居多)。 */
|
|
15
|
+
export const COMPONENT_INSTALLABILITY = {
|
|
16
|
+
gcc: "auto",
|
|
17
|
+
gdb: "auto",
|
|
18
|
+
openocd: "auto",
|
|
19
|
+
cmake: "auto",
|
|
20
|
+
ninja: "auto",
|
|
21
|
+
// CubeMX 的主程序与其内置 JRE 永远一起出现,也可能一起缺:同一份指引。
|
|
22
|
+
cubemx: "manual",
|
|
23
|
+
"cubemx-java": "manual",
|
|
24
|
+
firmware: "manual",
|
|
25
|
+
};
|
|
26
|
+
const CUBEMX_LABEL = "STM32CubeMX(启动器)+ 内置 JRE";
|
|
27
|
+
/**
|
|
28
|
+
* CubeMX 的安装指引。
|
|
29
|
+
*
|
|
30
|
+
* 事实依据(2026-10 取证):安装器是 InstallAnywhere 生成的 GUI 向导,官方文档没有静默安装参数;
|
|
31
|
+
* 下载要登录 ST 账号并同意许可;装完约 1.5 GB,且固件包**不在**里面(要另下 293 MB / 一万多个文件)。
|
|
32
|
+
* 社区里唯一能看到的 /S 静默安装脚本,对 CubeMX 那一行是注释掉的 —— 所以不做自动装。
|
|
33
|
+
*/
|
|
34
|
+
export function cubeMxGuide() {
|
|
35
|
+
return {
|
|
36
|
+
component: "cubemx",
|
|
37
|
+
label: CUBEMX_LABEL,
|
|
38
|
+
installability: "manual",
|
|
39
|
+
why: "CubeMX 是 GUI 安装向导,没有官方静默参数,下载前还要登录 ST 账号并同意许可,"
|
|
40
|
+
+ "插件代装等于替你点同意、替你输账号 —— 这一步不做。",
|
|
41
|
+
sizeHint: "安装包数百 MB,装完约 1.5 GB(不含固件包);固件包另算,见固件包那条指引(实测 250 MB – 1.7 GB)。",
|
|
42
|
+
needsAccount: true,
|
|
43
|
+
steps: [
|
|
44
|
+
{
|
|
45
|
+
title: "下载 CubeMX 安装包",
|
|
46
|
+
detail: "打开 https://www.st.com/en/development-tools/stm32cubemx.html → Get Software,登录/注册 ST 账号并同意许可后下载 Windows 安装包(.exe)。",
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
title: "GUI 装一遍(默认选项即可)",
|
|
50
|
+
detail: "双击安装包按向导走完;装到哪个盘都行,别放在受保护目录(例如 C:\\Program Files 需要管理员权限,插件写固件包时会失败)。",
|
|
51
|
+
},
|
|
52
|
+
{
|
|
53
|
+
title: "把安装根写进配置",
|
|
54
|
+
detail: "安装根 = 同时含 STM32CubeMX.exe 与 jre\\bin\\java.exe 的那个目录。让插件写:stm32_env_install 只做配置落盘,或手动编辑 %USERPROFILE%\\.dsh-stm32\\config.json 的 cubeMxRoot。",
|
|
55
|
+
},
|
|
56
|
+
{
|
|
57
|
+
title: "自检",
|
|
58
|
+
detail: "stm32_env_probe 的 tools 里 cubemx 与 cubemx-java 都应带 path;缺 jre 的话无头生成会直接报 java 找不到。",
|
|
59
|
+
},
|
|
60
|
+
],
|
|
61
|
+
verify: "stm32_env_probe → capabilities.generate 为 true(cubemx 与 cubemx-java 都找到)。",
|
|
62
|
+
portable: "一台机器上 GUI 装一次,把整个安装目录拷到目标机任意路径(jre 在目录里,不依赖系统 Java),"
|
|
63
|
+
+ "再把 cubeMxRoot 指过去即可。",
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
/** 芯片族 → CubeMX 固件包名前缀里那一段,例如 F1 → STM32F1xx。 */
|
|
67
|
+
export function familyPrefix(family) {
|
|
68
|
+
const trimmed = family.trim().toUpperCase();
|
|
69
|
+
return trimmed === "" ? "STM32<族>xx" : "STM32" + trimmed + "xx";
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* 各系列的固件包实测体积(2026-10 本机 D:\app\STM32CubeMX\Repository 直接量的)。
|
|
73
|
+
*
|
|
74
|
+
* 写死一句话会被别的系列看笑话:F1 293 MB、G4 471 MB、F4 1.67 GB,差 6 倍。
|
|
75
|
+
* 表里没有的系列给区间,不给具体数字。
|
|
76
|
+
*/
|
|
77
|
+
const FIRMWARE_SIZE_HINTS = {
|
|
78
|
+
F0: "258 MB / 一万七千个文件(实测 L0 同级,F0 同量级);装完占盘约 260 MB。",
|
|
79
|
+
F1: "293 MB / 10,778 个文件(v1.8.7 实测);装完占盘约 293 MB。",
|
|
80
|
+
F3: "约 300 MB / 一万多个文件;装完占盘约 300 MB。",
|
|
81
|
+
F4: "1,674 MB / 43,397 个文件(v1.28.3 实测);装完占盘约 1.7 GB。",
|
|
82
|
+
G0: "约 400 MB / 两万个文件;装完占盘约 400 MB。",
|
|
83
|
+
G4: "471 MB / 23,089 个文件(v1.6.2 实测);装完占盘约 470 MB。",
|
|
84
|
+
L0: "258 MB / 17,504 个文件(v1.12.4 实测);装完占盘约 258 MB。",
|
|
85
|
+
L4: "约 300 MB / 两万个文件;装完占盘约 300 MB。",
|
|
86
|
+
};
|
|
87
|
+
const FIRMWARE_SIZE_FALLBACK = "一个系列通常 250 MB – 1.7 GB / 一万到四万个文件(不同系列差很多,最多差 6 倍);装完占盘同量级。";
|
|
88
|
+
/** 固件包体积提示:认识的系列精确、不认识给区间(别把 F1 的数字扣到 H7 头上)。 */
|
|
89
|
+
export function firmwareSizeHint(family) {
|
|
90
|
+
const key = family.trim().toUpperCase();
|
|
91
|
+
return FIRMWARE_SIZE_HINTS[key] ?? FIRMWARE_SIZE_FALLBACK;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* 固件包(HAL + CMSIS + startup)的安装指引。
|
|
95
|
+
*
|
|
96
|
+
* 为什么不做成自动下载(2026-10 取证):GitHub 上 STMicroelectronics/STM32CubeF1 有 v1.8.7 标签,
|
|
97
|
+
* 但主仓库挂了 22 个 git 子模块,tarball 里 Drivers/CMSIS/Device/ST/STM32F1xx 与
|
|
98
|
+
* Drivers/STM32F1xx_HAL_Driver 是**空目录**;拼出来的包 CubeMX 认不认还没验证。
|
|
99
|
+
* 所以现在归 manual:让 CubeMX 自己的包管理器装(它写的 package.xml / 包清单才是权威)。
|
|
100
|
+
*/
|
|
101
|
+
export function firmwareGuide(input) {
|
|
102
|
+
const prefix = familyPrefix(input.family);
|
|
103
|
+
// 用 Object.hasOwn 而不是 `in`:`in` 会命中原型链("constructor" / "__proto__" 之类会被当成有效族名,
|
|
104
|
+
// 于是给出一份"插件能代下"的错误承诺)。审计 A37。
|
|
105
|
+
const autoDownloadable = input.family !== "" && Object.hasOwn(FIRMWARE_FAMILIES, input.family.toUpperCase());
|
|
106
|
+
const name = input.packageName === "" ? "STM32Cube_FW_" + (input.family === "" ? "<族>" : input.family) + "_V<版本>" : input.packageName;
|
|
107
|
+
return {
|
|
108
|
+
component: "firmware",
|
|
109
|
+
label: "固件包 " + name,
|
|
110
|
+
installability: "manual",
|
|
111
|
+
why: "固件包不在 CubeMX 安装包里,而且不是单个压缩包:HAL 驱动、CMSIS 设备头、启动文件分在不同的 git 仓库里,"
|
|
112
|
+
+ "GitHub 的源码压缩包拿到的是空目录。可靠的来源只有 CubeMX 自己的包管理器(它写包清单与 package.xml)。",
|
|
113
|
+
sizeHint: firmwareSizeHint(input.family),
|
|
114
|
+
needsAccount: true,
|
|
115
|
+
steps: [
|
|
116
|
+
{
|
|
117
|
+
title: autoDownloadable
|
|
118
|
+
? "先试插件代下(这一代已接入)"
|
|
119
|
+
: "插件还不会代下这一代",
|
|
120
|
+
detail: autoDownloadable
|
|
121
|
+
? "调 stm32_firmware_install(family 给 " + input.family + ",dryRun:false + confirm:true):插件从 GitHub 拉 HAL 驱动与 CMSIS 设备两个子模块仓库 + 内核头,自己补 package.xml,实测 CubeMX 认;约 2 MB,几十秒。拉不到或想用官方包再走下面三步。"
|
|
122
|
+
: "目前只有 F1 接入自动下载(其余代按同样字段补一条即可);这一代请走下面的 CubeMX 包管理器。",
|
|
123
|
+
},
|
|
124
|
+
{
|
|
125
|
+
title: "在 CubeMX 里打开包管理器",
|
|
126
|
+
detail: "CubeMX → Help → Manage embedded software packages → STM32Cube MCU Package for STM32" + (input.family === "" ? "<族>" : input.family) + " 那一栏 → 勾选目标版本 → Install。",
|
|
127
|
+
},
|
|
128
|
+
{
|
|
129
|
+
title: "确认落到默认位置",
|
|
130
|
+
detail: "装完应在 " + input.repositoryDir + "\\" + name + ";换过仓库目录的话以 CubeMX 的 Preferences 为准。",
|
|
131
|
+
},
|
|
132
|
+
{
|
|
133
|
+
title: "离线机器:整目录拷贝",
|
|
134
|
+
detail: "从有网的机器把 " + name + " 整个目录(或整个 Repository 目录)拷到目标机同一位置即可,不需要重装 CubeMX。",
|
|
135
|
+
},
|
|
136
|
+
{
|
|
137
|
+
title: "自检",
|
|
138
|
+
detail: "目录里应同时有 Drivers\\" + prefix + "_HAL_Driver、Drivers\\CMSIS\\Include、Drivers\\CMSIS\\Device\\ST\\" + prefix + "\\Source\\Templates。",
|
|
139
|
+
},
|
|
140
|
+
],
|
|
141
|
+
verify: "stm32_generate 不再报「找不到 CubeMX 固件包」,或 stm32_route_plan 的 firmware.found 为 true。",
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* 组件 id → 指引;auto 组件没有指引(它们走 stm32_env_install)。cubemx 与 cubemx-java 共用一份。
|
|
146
|
+
*
|
|
147
|
+
* firmware 需要族名/包名/仓库目录才说得具体,所以第二个参数是可选的补充信息:
|
|
148
|
+
* 调用方(route_plan)手里有这些字段就传,只拿组件 id 的人(门禁、命令卡)也能拿到通用指引 ——
|
|
149
|
+
* 否则 firmware 在这里恒为 null,和 route_plan 实际能给的东西不一致(审计 A37)。
|
|
150
|
+
*/
|
|
151
|
+
export function guideFor(component, firmware = { family: "", packageName: "", repositoryDir: "" }) {
|
|
152
|
+
if (component === "cubemx" || component === "cubemx-java")
|
|
153
|
+
return cubeMxGuide();
|
|
154
|
+
if (component === "firmware")
|
|
155
|
+
return firmwareGuide(firmware);
|
|
156
|
+
return null;
|
|
157
|
+
}
|
|
158
|
+
/** 一批组件 → 去重后的指引(cubemx + cubemx-java 只留一份,顺序稳定)。 */
|
|
159
|
+
export function guidesFor(components) {
|
|
160
|
+
const seen = new Set();
|
|
161
|
+
const out = [];
|
|
162
|
+
for (const component of components) {
|
|
163
|
+
const guide = guideFor(component);
|
|
164
|
+
if (guide === null)
|
|
165
|
+
continue;
|
|
166
|
+
if (seen.has(guide.component))
|
|
167
|
+
continue;
|
|
168
|
+
seen.add(guide.component);
|
|
169
|
+
out.push(guide);
|
|
170
|
+
}
|
|
171
|
+
return out;
|
|
172
|
+
}
|
|
173
|
+
/** 指引压成报告里的几行(gate.detail / notes 用)。 */
|
|
174
|
+
export function guideLines(guide, maxSteps = 4) {
|
|
175
|
+
const lines = [];
|
|
176
|
+
lines.push("【" + guide.label + "】" + guide.why);
|
|
177
|
+
lines.push("体积:" + guide.sizeHint + (guide.needsAccount ? ";需要 ST 账号并同意许可。" : ""));
|
|
178
|
+
const steps = guide.steps.slice(0, maxSteps);
|
|
179
|
+
for (const [index, step] of steps.entries()) {
|
|
180
|
+
lines.push(" " + String(index + 1) + ". " + step.title + " —— " + step.detail);
|
|
181
|
+
if (step.command !== undefined && step.command !== "")
|
|
182
|
+
lines.push(" " + step.command);
|
|
183
|
+
}
|
|
184
|
+
if (guide.steps.length > steps.length)
|
|
185
|
+
lines.push(" …还有 " + String(guide.steps.length - steps.length) + " 步,见 guides[].steps");
|
|
186
|
+
lines.push(" 自检:" + guide.verify);
|
|
187
|
+
if (guide.portable !== undefined && guide.portable !== "")
|
|
188
|
+
lines.push(" 免安装:" + guide.portable);
|
|
189
|
+
return lines;
|
|
190
|
+
}
|