qpi-cli 0.2.1__tar.gz → 0.2.2__tar.gz

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.
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.1
1
+ Metadata-Version: 2.4
2
2
  Name: qpi-cli
3
- Version: 0.2.1
3
+ Version: 0.2.2
4
4
  Summary: QuecPi QCS6490 (PI H1) Yocto Linux SDK 命令行工具 (构建 / 打包 / 烧录)
5
5
  Author: Quectel Pi
6
6
  License: MIT
@@ -24,6 +24,7 @@ Classifier: Topic :: Software Development :: Build Tools
24
24
  Requires-Python: >=3.8
25
25
  Description-Content-Type: text/markdown
26
26
  License-File: LICENSE
27
+ Dynamic: license-file
27
28
 
28
29
  # qpi-cli 用户使用手册
29
30
 
@@ -125,7 +126,7 @@ qpi-cli flash ufs
125
126
  | `qpi-cli ls-versions` | 列出固件版本及状态(未构建 / 已构建未打包 / 已打包) |
126
127
  | `qpi-cli build` | `buildconfig` + `buildall`,完整构建 |
127
128
  | `qpi-cli package` | `a_key_generation`,生成可烧录固件包 |
128
- | `qpi-cli flash [ufs\|emmc]` | 烧录固件到开发板 |
129
+ | `qpi-cli flash [ufs\|emmc] [--fw-dir DIR]` | 烧录固件到开发板(可指定固件目录) |
129
130
  | `qpi-cli kernel` | 内核相关操作(重编内核 / DTB / menuconfig) |
130
131
  | `qpi-cli clean` | 清理已打包固件或 bitbake 临时目录 |
131
132
 
@@ -148,6 +149,10 @@ qpi-cli flash ufs
148
149
  qpi-cli build --os LINUX --ver STD --dry-run
149
150
  qpi-cli flash ufs --dry-run
150
151
 
152
+ # 烧录现成的固件包(不改 buildconfig)
153
+ qpi-cli ls-versions
154
+ qpi-cli flash ufs --fw-dir SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X
155
+
151
156
  # 调试版本(DBG)+ 安全启动
152
157
  qpi-cli build --os LINUX --ver DBG --sec
153
158
 
@@ -242,6 +247,10 @@ FLASH_ENTRY=scripts/flash.sh
242
247
  `qpi-cli flash` 最终仍然是通过 `source build.sh` 后调用 `flash <storage>` 完成,
243
248
  因此 SDK 里的烧录逻辑(自动识别 Linux/WSL 平台、选择 qdl 或 QFIL 等)完全保持不变。
244
249
 
250
+ 烧录前会先检查固件目录:当前 buildconfig 对应的版本未打包时直接给出提示,并列出
251
+ `quectel_build/` 下现成可烧录的包。用 `--fw-dir` 可以跳过 buildconfig,直接烧某个
252
+ 已打包目录(目录名或路径均可),该值通过 `QPI_FW_DIR` 传给 `flash.sh`。
253
+
245
254
  ---
246
255
 
247
256
  ## 8. 环境变量
@@ -250,6 +259,7 @@ FLASH_ENTRY=scripts/flash.sh
250
259
  |------|------|
251
260
  | `QPI_SDK_ROOT` | 指定 SDK 根目录 |
252
261
  | `QPI_CONFIG` | 指定配置文件路径(覆盖用户级默认路径) |
262
+ | `QPI_FW_DIR` | 指定烧录用的固件目录(`flash.sh` 直接读取,优先于 buildconfig) |
253
263
  | `NO_COLOR` | 设置后关闭彩色输出 |
254
264
 
255
265
  ---
@@ -98,7 +98,7 @@ qpi-cli flash ufs
98
98
  | `qpi-cli ls-versions` | 列出固件版本及状态(未构建 / 已构建未打包 / 已打包) |
99
99
  | `qpi-cli build` | `buildconfig` + `buildall`,完整构建 |
100
100
  | `qpi-cli package` | `a_key_generation`,生成可烧录固件包 |
101
- | `qpi-cli flash [ufs\|emmc]` | 烧录固件到开发板 |
101
+ | `qpi-cli flash [ufs\|emmc] [--fw-dir DIR]` | 烧录固件到开发板(可指定固件目录) |
102
102
  | `qpi-cli kernel` | 内核相关操作(重编内核 / DTB / menuconfig) |
103
103
  | `qpi-cli clean` | 清理已打包固件或 bitbake 临时目录 |
104
104
 
@@ -121,6 +121,10 @@ qpi-cli flash ufs
121
121
  qpi-cli build --os LINUX --ver STD --dry-run
122
122
  qpi-cli flash ufs --dry-run
123
123
 
124
+ # 烧录现成的固件包(不改 buildconfig)
125
+ qpi-cli ls-versions
126
+ qpi-cli flash ufs --fw-dir SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X
127
+
124
128
  # 调试版本(DBG)+ 安全启动
125
129
  qpi-cli build --os LINUX --ver DBG --sec
126
130
 
@@ -215,6 +219,10 @@ FLASH_ENTRY=scripts/flash.sh
215
219
  `qpi-cli flash` 最终仍然是通过 `source build.sh` 后调用 `flash <storage>` 完成,
216
220
  因此 SDK 里的烧录逻辑(自动识别 Linux/WSL 平台、选择 qdl 或 QFIL 等)完全保持不变。
217
221
 
222
+ 烧录前会先检查固件目录:当前 buildconfig 对应的版本未打包时直接给出提示,并列出
223
+ `quectel_build/` 下现成可烧录的包。用 `--fw-dir` 可以跳过 buildconfig,直接烧某个
224
+ 已打包目录(目录名或路径均可),该值通过 `QPI_FW_DIR` 传给 `flash.sh`。
225
+
218
226
  ---
219
227
 
220
228
  ## 8. 环境变量
@@ -223,6 +231,7 @@ FLASH_ENTRY=scripts/flash.sh
223
231
  |------|------|
224
232
  | `QPI_SDK_ROOT` | 指定 SDK 根目录 |
225
233
  | `QPI_CONFIG` | 指定配置文件路径(覆盖用户级默认路径) |
234
+ | `QPI_FW_DIR` | 指定烧录用的固件目录(`flash.sh` 直接读取,优先于 buildconfig) |
226
235
  | `NO_COLOR` | 设置后关闭彩色输出 |
227
236
 
228
237
  ---
@@ -8,7 +8,7 @@
8
8
  只依赖 Python 3 标准库, 不引入任何第三方包。
9
9
  """
10
10
 
11
- __version__ = "0.2.1"
11
+ __version__ = "0.2.2"
12
12
  CLI_NAME = "qpi-cli"
13
13
 
14
14
  __all__ = ["__version__", "CLI_NAME", "main"]
@@ -131,6 +131,11 @@ def build_parser():
131
131
 
132
132
  p_flash = sub.add_parser("flash", parents=[common], help="烧录固件到开发板")
133
133
  p_flash.add_argument("storage", nargs="?", choices=["ufs", "emmc"], default="ufs")
134
+ p_flash.add_argument(
135
+ "--fw-dir",
136
+ metavar="DIR",
137
+ help="指定固件目录 (绝对/相对路径, 或 quectel_build/ 下的目录名)",
138
+ )
134
139
 
135
140
  p_kern = sub.add_parser("kernel", parents=[common], help="内核相关操作")
136
141
  p_kern.add_argument("--dtb", action="store_true", help="仅重编 DTB")
@@ -14,6 +14,7 @@ from .core import (
14
14
  BUILD_DIR,
15
15
  BUILD_SH,
16
16
  FLASH_SH,
17
+ GEN_HEADER,
17
18
  INSTALL_ENV_SH,
18
19
  VERSION_TXT,
19
20
  banner,
@@ -23,6 +24,9 @@ from .core import (
23
24
  default_config,
24
25
  error,
25
26
  flash_entry_error,
27
+ fw_dir_name,
28
+ fw_dir_problem,
29
+ has_fw_fingerprint,
26
30
  info,
27
31
  resolve_flash_entry,
28
32
  run_sdk,
@@ -185,9 +189,7 @@ def _dir_size_mb(path):
185
189
  def cmd_ls_versions(args):
186
190
  ctx = args.ctx
187
191
  dirs = ctx.rev_dirs()
188
- cur_rev = ctx.current_rev()
189
- cur_custom = ctx.current_custom()
190
- cur_dir = cur_rev + ("_DBG" if "DBG" in cur_custom.split("/") else "")
192
+ cur_dir = ctx.current_fw_name()
191
193
 
192
194
  rows = []
193
195
  for name, path, state in dirs:
@@ -522,16 +524,71 @@ def cmd_build(args):
522
524
 
523
525
  def cmd_package(args):
524
526
  ctx = args.ctx
525
- info("打包固件 (a_key_generation + deb-publish)")
526
- rc = run_sdk("buildpackage", ctx.root, verbose=args.verbose, dry_run=args.dry_run)
527
+ # buildpackage 依赖 QUECTEL_PROJECT_* 环境变量, 而 source build.sh 并不会设置
528
+ # 它们 (只有 buildconfig/buildenv 才会)。这里直接从 header 读出并显式导出,
529
+ # 避免版本号为空导致 a_key_generation 把产物落到 quectel_build/ 根目录。
530
+ hdr = ctx.current_header()
531
+ project = hdr.get("QUECTEL_PROJECT_NAME") or dget(
532
+ ctx.config, "build.project", "QSM565DWF"
533
+ )
534
+ rev = hdr.get("QUECTEL_PROJECT_REV", "")
535
+ custom = hdr.get("QUECTEL_CUSTOM_NAME") or dget(
536
+ ctx.config, "build.version", "STD"
537
+ )
538
+ if not rev:
539
+ error("无法从 %s 读取 QUECTEL_PROJECT_REV" % ctx.p(GEN_HEADER))
540
+ warn("请先执行 qpi-cli build, 或在 SDK 环境里执行 buildconfig")
541
+ return 1
542
+
543
+ body = "\n".join(
544
+ [
545
+ "export QUECTEL_PROJECT_NAME=%s" % shlex.quote(project),
546
+ "export QUECTEL_PROJECT_REV=%s" % shlex.quote(rev),
547
+ "export QUECTEL_CUSTOM_NAME=%s" % shlex.quote(custom),
548
+ "buildpackage",
549
+ ]
550
+ )
551
+
552
+ info("打包固件 (project=%s rev=%s custom=%s)" % (project, rev, custom))
553
+ rc = run_sdk(body, ctx.root, verbose=args.verbose, dry_run=args.dry_run)
527
554
  if rc == 0 and not args.dry_run:
528
- rev = ctx.current_rev()
529
- custom = ctx.current_custom()
530
- out = rev + ("_DBG" if "DBG" in custom.split("/") else "")
531
- info("固件输出目录: %s" % ctx.p("quectel_build", out))
555
+ name = fw_dir_name(rev, custom)
556
+ out = ctx.p("quectel_build", name)
557
+ if os.path.isdir(out) and has_fw_fingerprint(out):
558
+ info("固件输出目录: %s" % out)
559
+ info("烧录: qpi-cli flash ufs")
560
+ else:
561
+ warn("打包命令已返回, 但未检测到可烧录固件: %s" % out)
532
562
  return rc
533
563
 
534
564
 
565
+ def _resolve_fw_dir(ctx, value):
566
+ """--fw-dir 支持绝对/相对路径, 也支持 quectel_build/ 下的目录名。"""
567
+ expanded = os.path.abspath(os.path.expanduser(value))
568
+ if os.path.isdir(expanded):
569
+ return expanded
570
+ cand = ctx.p("quectel_build", value)
571
+ if os.path.isdir(cand):
572
+ return cand
573
+ return expanded
574
+
575
+
576
+ def _report_available_fw(ctx, storage):
577
+ """固件不可烧录时, 列出 quectel_build/ 下现成可烧录的包。"""
578
+ name, _path = ctx.current_fw_dir()
579
+ info("当前 buildconfig 对应目录: %s" % (name or "<header 不可解析>"))
580
+ dirs = ctx.packaged_fw_dirs()
581
+ if not dirs:
582
+ warn("quectel_build/ 下没有已打包的固件")
583
+ info("先打包: qpi-cli package")
584
+ return
585
+ info("已打包可烧录的固件:")
586
+ for n, _p in dirs:
587
+ print(" %s%s" % (n, " (当前)" if n == name else ""))
588
+ print()
589
+ print(" 烧录现成固件: qpi-cli flash %s --fw-dir %s" % (storage, dirs[0][0]))
590
+
591
+
535
592
  def cmd_flash(args):
536
593
  ctx = args.ctx
537
594
  storage = args.storage or "ufs"
@@ -547,11 +604,29 @@ def cmd_flash(args):
547
604
  warn("检查 tools/VERSION.txt 的 FLASH_ENTRY 或回落路径 %s" % FLASH_SH)
548
605
  return 1
549
606
 
607
+ # 固件目录预检: 提前给出可执行的建议, 而不是让 flash.sh 在末尾报难懂的错。
608
+ fw_name, fw_path = ctx.current_fw_dir()
609
+ if getattr(args, "fw_dir", None):
610
+ fw_path = _resolve_fw_dir(ctx, args.fw_dir)
611
+ fw_name = os.path.basename(fw_path.rstrip(os.sep))
612
+ problem = fw_dir_problem(fw_path)
613
+ if problem:
614
+ error("固件目录不可烧录: %s (%s)" % (fw_path or "<空>", problem))
615
+ _report_available_fw(ctx, storage)
616
+ if getattr(args, "fw_dir", None):
617
+ return 1
618
+ info("或先打包当前 buildconfig: qpi-cli package")
619
+ if not args.dry_run:
620
+ return 1
621
+ warn("dry-run: 继续打印烧录计划; 实际执行会在此退出")
622
+
550
623
  info("烧录固件 (storage=%s)" % storage)
551
- print(" entry : %s" % entry_abs)
624
+ print(" entry : %s" % entry_abs)
625
+ print(" firmware: %s (%s)" % (fw_path, fw_name))
552
626
  if args.dry_run:
553
627
  banner("dry-run: 将要执行的烧录命令")
554
628
  print(" cd %s" % shlex.quote(ctx.root))
629
+ print(" QPI_FW_DIR=%s" % shlex.quote(fw_path))
555
630
  print(" source %s" % shlex.quote(BUILD_SH))
556
631
  print(" flash %s" % shlex.quote(storage))
557
632
  print(" # FLASH_ENTRY 已解析为: %s" % entry_abs)
@@ -561,6 +636,7 @@ def cmd_flash(args):
561
636
  ctx.root,
562
637
  verbose=args.verbose,
563
638
  dry_run=False,
639
+ extra_env={"QPI_FW_DIR": fw_path},
564
640
  )
565
641
 
566
642
 
@@ -57,6 +57,32 @@ def has_fw_fingerprint(path):
57
57
  return False
58
58
 
59
59
 
60
+ def fw_dir_name(rev, custom):
61
+ """按 buildpackage / flash.sh 的规则拼固件目录名 (DBG 版本带 _DBG 后缀)。"""
62
+ if not rev:
63
+ return ""
64
+ return rev + ("_DBG" if "DBG" in (custom or "").split("/") else "")
65
+
66
+
67
+ def fw_dir_problem(path):
68
+ """检查固件目录是否具备烧录条件, 返回问题描述 (None 表示可烧录)。"""
69
+ if not os.path.isdir(path):
70
+ return "目录不存在"
71
+ try:
72
+ names = os.listdir(path)
73
+ except OSError as exc:
74
+ return "无法读取目录 (%s)" % exc
75
+ has_elf = any(fnmatch.fnmatch(n, "prog_firehose*.elf") for n in names)
76
+ has_xml = any(fnmatch.fnmatch(n, "rawprogram*.xml") for n in names)
77
+ if not has_elf and not has_xml:
78
+ return "目录内没有打包产物 (未执行 buildpackage)"
79
+ if not has_elf:
80
+ return "缺少 prog_firehose*.elf"
81
+ if not has_xml:
82
+ return "缺少 rawprogram*.xml"
83
+ return None
84
+
85
+
60
86
  # ---------------------------------------------------------------- 输出辅助 ---
61
87
  def _color(code, text):
62
88
  if sys.stdout.isatty() and os.environ.get("NO_COLOR") is None:
@@ -282,11 +308,28 @@ class Ctx:
282
308
  )
283
309
 
284
310
  # ---- 固件版本目录 (三态) ----
311
+ def current_fw_name(self):
312
+ """当前 buildconfig 对应的固件目录名 (含 DBG 后缀)。"""
313
+ return fw_dir_name(self.current_rev(), self.current_custom())
314
+
315
+ def current_fw_dir(self):
316
+ """返回 (目录名, 绝对路径); header 不可解析时名称为空。"""
317
+ name = self.current_fw_name()
318
+ return name, (self.p("quectel_build", name) if name else "")
319
+
285
320
  def rev_candidate_names(self):
286
321
  """当前 buildconfig 对应的候选版本目录名 (rev 与 rev_DBG)。"""
287
322
  rev = self.current_rev()
288
323
  return {rev, rev + "_DBG"}
289
324
 
325
+ def packaged_fw_dirs(self):
326
+ """已打包可烧录的固件目录 [(name, path)]。"""
327
+ return [
328
+ (name, path)
329
+ for name, path, state in self.rev_dirs()
330
+ if state == "已打包(可烧录)"
331
+ ]
332
+
290
333
  def rev_dirs(self):
291
334
  """枚举 quectel_build/ 下的固件版本目录及其状态。
292
335
 
@@ -338,22 +381,30 @@ class Ctx:
338
381
 
339
382
 
340
383
  # ------------------------------------------------------- SDK 环境内执行 -----
341
- def run_sdk(cmd_body, sdk_root, verbose=False, dry_run=False):
384
+ def run_sdk(cmd_body, sdk_root, verbose=False, dry_run=False, extra_env=None):
342
385
  """在 source 过 build.sh 的 bash 环境里执行 cmd_body。
343
386
 
344
387
  build.sh 是 source 型脚本: 它会设置 TOPDIR/BUILDDIR 等变量、定义
345
388
  buildconfig/buildall/buildpackage/flash 等函数。所以这里生成一段临时
346
389
  bash, 先 source 再把调用体接在后面。
390
+
391
+ extra_env 会叠加到子进程环境 (例如 flash 的 QPI_FW_DIR)。
347
392
  """
393
+ env_prefix = ""
394
+ if extra_env:
395
+ env_prefix = "".join(
396
+ "export %s=%s\n" % (k, shlex.quote(str(v)))
397
+ for k, v in sorted(extra_env.items())
398
+ )
399
+
348
400
  lines = [
349
401
  "#!/bin/bash",
350
402
  "cd %s || exit 1" % shlex.quote(sdk_root),
351
403
  "source %s %s || { echo '[qpi-cli] ERROR: source build.sh failed' >&2; exit 1; }"
352
404
  % (shlex.quote(BUILD_SH), ">/dev/null" if not verbose else ""),
353
405
  "set -e",
354
- cmd_body,
355
406
  ]
356
- script = "\n".join(lines) + "\n"
407
+ script = "\n".join(lines) + "\n" + env_prefix + cmd_body + "\n"
357
408
 
358
409
  if dry_run:
359
410
  banner("dry-run: 将要执行的 SDK 环境脚本")
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.1
1
+ Metadata-Version: 2.4
2
2
  Name: qpi-cli
3
- Version: 0.2.1
3
+ Version: 0.2.2
4
4
  Summary: QuecPi QCS6490 (PI H1) Yocto Linux SDK 命令行工具 (构建 / 打包 / 烧录)
5
5
  Author: Quectel Pi
6
6
  License: MIT
@@ -24,6 +24,7 @@ Classifier: Topic :: Software Development :: Build Tools
24
24
  Requires-Python: >=3.8
25
25
  Description-Content-Type: text/markdown
26
26
  License-File: LICENSE
27
+ Dynamic: license-file
27
28
 
28
29
  # qpi-cli 用户使用手册
29
30
 
@@ -125,7 +126,7 @@ qpi-cli flash ufs
125
126
  | `qpi-cli ls-versions` | 列出固件版本及状态(未构建 / 已构建未打包 / 已打包) |
126
127
  | `qpi-cli build` | `buildconfig` + `buildall`,完整构建 |
127
128
  | `qpi-cli package` | `a_key_generation`,生成可烧录固件包 |
128
- | `qpi-cli flash [ufs\|emmc]` | 烧录固件到开发板 |
129
+ | `qpi-cli flash [ufs\|emmc] [--fw-dir DIR]` | 烧录固件到开发板(可指定固件目录) |
129
130
  | `qpi-cli kernel` | 内核相关操作(重编内核 / DTB / menuconfig) |
130
131
  | `qpi-cli clean` | 清理已打包固件或 bitbake 临时目录 |
131
132
 
@@ -148,6 +149,10 @@ qpi-cli flash ufs
148
149
  qpi-cli build --os LINUX --ver STD --dry-run
149
150
  qpi-cli flash ufs --dry-run
150
151
 
152
+ # 烧录现成的固件包(不改 buildconfig)
153
+ qpi-cli ls-versions
154
+ qpi-cli flash ufs --fw-dir SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X
155
+
151
156
  # 调试版本(DBG)+ 安全启动
152
157
  qpi-cli build --os LINUX --ver DBG --sec
153
158
 
@@ -242,6 +247,10 @@ FLASH_ENTRY=scripts/flash.sh
242
247
  `qpi-cli flash` 最终仍然是通过 `source build.sh` 后调用 `flash <storage>` 完成,
243
248
  因此 SDK 里的烧录逻辑(自动识别 Linux/WSL 平台、选择 qdl 或 QFIL 等)完全保持不变。
244
249
 
250
+ 烧录前会先检查固件目录:当前 buildconfig 对应的版本未打包时直接给出提示,并列出
251
+ `quectel_build/` 下现成可烧录的包。用 `--fw-dir` 可以跳过 buildconfig,直接烧某个
252
+ 已打包目录(目录名或路径均可),该值通过 `QPI_FW_DIR` 传给 `flash.sh`。
253
+
245
254
  ---
246
255
 
247
256
  ## 8. 环境变量
@@ -250,6 +259,7 @@ FLASH_ENTRY=scripts/flash.sh
250
259
  |------|------|
251
260
  | `QPI_SDK_ROOT` | 指定 SDK 根目录 |
252
261
  | `QPI_CONFIG` | 指定配置文件路径(覆盖用户级默认路径) |
262
+ | `QPI_FW_DIR` | 指定烧录用的固件目录(`flash.sh` 直接读取,优先于 buildconfig) |
253
263
  | `NO_COLOR` | 设置后关闭彩色输出 |
254
264
 
255
265
  ---
File without changes
File without changes
File without changes
File without changes