qpi-cli 0.2.0__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,10 +1,13 @@
1
- Metadata-Version: 2.1
1
+ Metadata-Version: 2.4
2
2
  Name: qpi-cli
3
- Version: 0.2.0
3
+ Version: 0.2.2
4
4
  Summary: QuecPi QCS6490 (PI H1) Yocto Linux SDK 命令行工具 (构建 / 打包 / 烧录)
5
5
  Author: Quectel Pi
6
6
  License: MIT
7
- Project-URL: Homepage, https://github.com/Quectel-Pi/Pi-H1-Linux-SDK
7
+ Project-URL: Homepage, https://github.com/james-liu18/qpi-cli
8
+ Project-URL: Repository, https://github.com/james-liu18/qpi-cli
9
+ Project-URL: Bug Tracker, https://github.com/james-liu18/qpi-cli/issues
10
+ Project-URL: SDK (Pi-H1-Linux-SDK), https://github.com/Quectel-Pi/Pi-H1-Linux-SDK
8
11
  Keywords: quectel,quecpi,qpi,qcs6490,yocto,sdk,bitbake,cli
9
12
  Classifier: Development Status :: 4 - Beta
10
13
  Classifier: Environment :: Console
@@ -21,6 +24,7 @@ Classifier: Topic :: Software Development :: Build Tools
21
24
  Requires-Python: >=3.8
22
25
  Description-Content-Type: text/markdown
23
26
  License-File: LICENSE
27
+ Dynamic: license-file
24
28
 
25
29
  # qpi-cli 用户使用手册
26
30
 
@@ -122,7 +126,7 @@ qpi-cli flash ufs
122
126
  | `qpi-cli ls-versions` | 列出固件版本及状态(未构建 / 已构建未打包 / 已打包) |
123
127
  | `qpi-cli build` | `buildconfig` + `buildall`,完整构建 |
124
128
  | `qpi-cli package` | `a_key_generation`,生成可烧录固件包 |
125
- | `qpi-cli flash [ufs\|emmc]` | 烧录固件到开发板 |
129
+ | `qpi-cli flash [ufs\|emmc] [--fw-dir DIR]` | 烧录固件到开发板(可指定固件目录) |
126
130
  | `qpi-cli kernel` | 内核相关操作(重编内核 / DTB / menuconfig) |
127
131
  | `qpi-cli clean` | 清理已打包固件或 bitbake 临时目录 |
128
132
 
@@ -145,6 +149,10 @@ qpi-cli flash ufs
145
149
  qpi-cli build --os LINUX --ver STD --dry-run
146
150
  qpi-cli flash ufs --dry-run
147
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
+
148
156
  # 调试版本(DBG)+ 安全启动
149
157
  qpi-cli build --os LINUX --ver DBG --sec
150
158
 
@@ -239,6 +247,10 @@ FLASH_ENTRY=scripts/flash.sh
239
247
  `qpi-cli flash` 最终仍然是通过 `source build.sh` 后调用 `flash <storage>` 完成,
240
248
  因此 SDK 里的烧录逻辑(自动识别 Linux/WSL 平台、选择 qdl 或 QFIL 等)完全保持不变。
241
249
 
250
+ 烧录前会先检查固件目录:当前 buildconfig 对应的版本未打包时直接给出提示,并列出
251
+ `quectel_build/` 下现成可烧录的包。用 `--fw-dir` 可以跳过 buildconfig,直接烧某个
252
+ 已打包目录(目录名或路径均可),该值通过 `QPI_FW_DIR` 传给 `flash.sh`。
253
+
242
254
  ---
243
255
 
244
256
  ## 8. 环境变量
@@ -247,6 +259,7 @@ FLASH_ENTRY=scripts/flash.sh
247
259
  |------|------|
248
260
  | `QPI_SDK_ROOT` | 指定 SDK 根目录 |
249
261
  | `QPI_CONFIG` | 指定配置文件路径(覆盖用户级默认路径) |
262
+ | `QPI_FW_DIR` | 指定烧录用的固件目录(`flash.sh` 直接读取,优先于 buildconfig) |
250
263
  | `NO_COLOR` | 设置后关闭彩色输出 |
251
264
 
252
265
  ---
@@ -269,7 +282,7 @@ FLASH_ENTRY=scripts/flash.sh
269
282
  ## 10. 从源码安装与发布
270
283
 
271
284
  ```bash
272
- git clone <本仓库>
285
+ git clone https://github.com/james-liu18/qpi-cli.git
273
286
  cd qpi-cli
274
287
 
275
288
  # 本地开发安装(可编辑)
@@ -288,6 +301,36 @@ twine upload dist/*
288
301
  版本号唯一来源是 `src/qpi_cli/__init__.py` 中的 `__version__`,
289
302
  `pyproject.toml` 通过 `dynamic = ["version"]` 自动读取,无需两处同步。
290
303
 
304
+ ### 自动发布(GitHub Actions)
305
+
306
+ 仓库内的 `.github/workflows/release.yml` 实现打 tag 自动发布:
307
+
308
+ ```bash
309
+ # 发布 0.2.1:先把 __version__ 改成 0.2.1 并提交,再打 tag
310
+ git tag v0.2.1
311
+ git push origin v0.2.1
312
+ ```
313
+
314
+ 工作流依次做三件事:
315
+
316
+ 1. 校验 tag 与包内 `__version__` 一致(不一致直接失败,避免发错版本);
317
+ 2. `python -m build` + `twine check`,并在干净 venv 里
318
+ `pip install --no-deps dist/*.whl` 后跑 `qpi-cli --version` / `--help` 自检;
319
+ 3. 用 PyPI **Trusted Publishing(OIDC)** 上传,无需在仓库里存 API token。
320
+
321
+ 首次发布前需在 PyPI 配置一次性授权(<https://pypi.org/manage/account/publishing/>
322
+ 的 "pending publisher",项目已存在则在 Project → Publishing 里加):
323
+
324
+ | 字段 | 值 |
325
+ |------|-----|
326
+ | PyPI Project Name | `qpi-cli` |
327
+ | Owner | GitHub 账号或组织(例如 `james-liu18`) |
328
+ | Repository name | `qpi-cli` |
329
+ | Workflow name | `release.yml` |
330
+ | Environment name | `pypi` |
331
+
332
+ 也支持手动触发(Actions → release → Run workflow):只构建与自检,不会上传。
333
+
291
334
  ---
292
335
 
293
336
  ## 11. 常见问题
@@ -1,27 +1,3 @@
1
- Metadata-Version: 2.1
2
- Name: qpi-cli
3
- Version: 0.2.0
4
- Summary: QuecPi QCS6490 (PI H1) Yocto Linux SDK 命令行工具 (构建 / 打包 / 烧录)
5
- Author: Quectel Pi
6
- License: MIT
7
- Project-URL: Homepage, https://github.com/Quectel-Pi/Pi-H1-Linux-SDK
8
- Keywords: quectel,quecpi,qpi,qcs6490,yocto,sdk,bitbake,cli
9
- Classifier: Development Status :: 4 - Beta
10
- Classifier: Environment :: Console
11
- Classifier: Intended Audience :: Developers
12
- Classifier: License :: OSI Approved :: MIT License
13
- Classifier: Operating System :: POSIX :: Linux
14
- Classifier: Programming Language :: Python :: 3
15
- Classifier: Programming Language :: Python :: 3.8
16
- Classifier: Programming Language :: Python :: 3.9
17
- Classifier: Programming Language :: Python :: 3.10
18
- Classifier: Programming Language :: Python :: 3.11
19
- Classifier: Programming Language :: Python :: 3.12
20
- Classifier: Topic :: Software Development :: Build Tools
21
- Requires-Python: >=3.8
22
- Description-Content-Type: text/markdown
23
- License-File: LICENSE
24
-
25
1
  # qpi-cli 用户使用手册
26
2
 
27
3
  **适用平台:** Linux 宿主(Ubuntu 22.04 LTS 为 SDK 验证环境)
@@ -122,7 +98,7 @@ qpi-cli flash ufs
122
98
  | `qpi-cli ls-versions` | 列出固件版本及状态(未构建 / 已构建未打包 / 已打包) |
123
99
  | `qpi-cli build` | `buildconfig` + `buildall`,完整构建 |
124
100
  | `qpi-cli package` | `a_key_generation`,生成可烧录固件包 |
125
- | `qpi-cli flash [ufs\|emmc]` | 烧录固件到开发板 |
101
+ | `qpi-cli flash [ufs\|emmc] [--fw-dir DIR]` | 烧录固件到开发板(可指定固件目录) |
126
102
  | `qpi-cli kernel` | 内核相关操作(重编内核 / DTB / menuconfig) |
127
103
  | `qpi-cli clean` | 清理已打包固件或 bitbake 临时目录 |
128
104
 
@@ -145,6 +121,10 @@ qpi-cli flash ufs
145
121
  qpi-cli build --os LINUX --ver STD --dry-run
146
122
  qpi-cli flash ufs --dry-run
147
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
+
148
128
  # 调试版本(DBG)+ 安全启动
149
129
  qpi-cli build --os LINUX --ver DBG --sec
150
130
 
@@ -239,6 +219,10 @@ FLASH_ENTRY=scripts/flash.sh
239
219
  `qpi-cli flash` 最终仍然是通过 `source build.sh` 后调用 `flash <storage>` 完成,
240
220
  因此 SDK 里的烧录逻辑(自动识别 Linux/WSL 平台、选择 qdl 或 QFIL 等)完全保持不变。
241
221
 
222
+ 烧录前会先检查固件目录:当前 buildconfig 对应的版本未打包时直接给出提示,并列出
223
+ `quectel_build/` 下现成可烧录的包。用 `--fw-dir` 可以跳过 buildconfig,直接烧某个
224
+ 已打包目录(目录名或路径均可),该值通过 `QPI_FW_DIR` 传给 `flash.sh`。
225
+
242
226
  ---
243
227
 
244
228
  ## 8. 环境变量
@@ -247,6 +231,7 @@ FLASH_ENTRY=scripts/flash.sh
247
231
  |------|------|
248
232
  | `QPI_SDK_ROOT` | 指定 SDK 根目录 |
249
233
  | `QPI_CONFIG` | 指定配置文件路径(覆盖用户级默认路径) |
234
+ | `QPI_FW_DIR` | 指定烧录用的固件目录(`flash.sh` 直接读取,优先于 buildconfig) |
250
235
  | `NO_COLOR` | 设置后关闭彩色输出 |
251
236
 
252
237
  ---
@@ -269,7 +254,7 @@ FLASH_ENTRY=scripts/flash.sh
269
254
  ## 10. 从源码安装与发布
270
255
 
271
256
  ```bash
272
- git clone <本仓库>
257
+ git clone https://github.com/james-liu18/qpi-cli.git
273
258
  cd qpi-cli
274
259
 
275
260
  # 本地开发安装(可编辑)
@@ -288,6 +273,36 @@ twine upload dist/*
288
273
  版本号唯一来源是 `src/qpi_cli/__init__.py` 中的 `__version__`,
289
274
  `pyproject.toml` 通过 `dynamic = ["version"]` 自动读取,无需两处同步。
290
275
 
276
+ ### 自动发布(GitHub Actions)
277
+
278
+ 仓库内的 `.github/workflows/release.yml` 实现打 tag 自动发布:
279
+
280
+ ```bash
281
+ # 发布 0.2.1:先把 __version__ 改成 0.2.1 并提交,再打 tag
282
+ git tag v0.2.1
283
+ git push origin v0.2.1
284
+ ```
285
+
286
+ 工作流依次做三件事:
287
+
288
+ 1. 校验 tag 与包内 `__version__` 一致(不一致直接失败,避免发错版本);
289
+ 2. `python -m build` + `twine check`,并在干净 venv 里
290
+ `pip install --no-deps dist/*.whl` 后跑 `qpi-cli --version` / `--help` 自检;
291
+ 3. 用 PyPI **Trusted Publishing(OIDC)** 上传,无需在仓库里存 API token。
292
+
293
+ 首次发布前需在 PyPI 配置一次性授权(<https://pypi.org/manage/account/publishing/>
294
+ 的 "pending publisher",项目已存在则在 Project → Publishing 里加):
295
+
296
+ | 字段 | 值 |
297
+ |------|-----|
298
+ | PyPI Project Name | `qpi-cli` |
299
+ | Owner | GitHub 账号或组织(例如 `james-liu18`) |
300
+ | Repository name | `qpi-cli` |
301
+ | Workflow name | `release.yml` |
302
+ | Environment name | `pypi` |
303
+
304
+ 也支持手动触发(Actions → release → Run workflow):只构建与自检,不会上传。
305
+
291
306
  ---
292
307
 
293
308
  ## 11. 常见问题
@@ -27,7 +27,10 @@ classifiers = [
27
27
  ]
28
28
 
29
29
  [project.urls]
30
- Homepage = "https://github.com/Quectel-Pi/Pi-H1-Linux-SDK"
30
+ Homepage = "https://github.com/james-liu18/qpi-cli"
31
+ Repository = "https://github.com/james-liu18/qpi-cli"
32
+ "Bug Tracker" = "https://github.com/james-liu18/qpi-cli/issues"
33
+ "SDK (Pi-H1-Linux-SDK)" = "https://github.com/Quectel-Pi/Pi-H1-Linux-SDK"
31
34
 
32
35
  [project.scripts]
33
36
  qpi-cli = "qpi_cli.cli:main"
@@ -8,7 +8,7 @@
8
8
  只依赖 Python 3 标准库, 不引入任何第三方包。
9
9
  """
10
10
 
11
- __version__ = "0.2.0"
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,3 +1,31 @@
1
+ Metadata-Version: 2.4
2
+ Name: qpi-cli
3
+ Version: 0.2.2
4
+ Summary: QuecPi QCS6490 (PI H1) Yocto Linux SDK 命令行工具 (构建 / 打包 / 烧录)
5
+ Author: Quectel Pi
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/james-liu18/qpi-cli
8
+ Project-URL: Repository, https://github.com/james-liu18/qpi-cli
9
+ Project-URL: Bug Tracker, https://github.com/james-liu18/qpi-cli/issues
10
+ Project-URL: SDK (Pi-H1-Linux-SDK), https://github.com/Quectel-Pi/Pi-H1-Linux-SDK
11
+ Keywords: quectel,quecpi,qpi,qcs6490,yocto,sdk,bitbake,cli
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.8
19
+ Classifier: Programming Language :: Python :: 3.9
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Topic :: Software Development :: Build Tools
24
+ Requires-Python: >=3.8
25
+ Description-Content-Type: text/markdown
26
+ License-File: LICENSE
27
+ Dynamic: license-file
28
+
1
29
  # qpi-cli 用户使用手册
2
30
 
3
31
  **适用平台:** Linux 宿主(Ubuntu 22.04 LTS 为 SDK 验证环境)
@@ -98,7 +126,7 @@ qpi-cli flash ufs
98
126
  | `qpi-cli ls-versions` | 列出固件版本及状态(未构建 / 已构建未打包 / 已打包) |
99
127
  | `qpi-cli build` | `buildconfig` + `buildall`,完整构建 |
100
128
  | `qpi-cli package` | `a_key_generation`,生成可烧录固件包 |
101
- | `qpi-cli flash [ufs\|emmc]` | 烧录固件到开发板 |
129
+ | `qpi-cli flash [ufs\|emmc] [--fw-dir DIR]` | 烧录固件到开发板(可指定固件目录) |
102
130
  | `qpi-cli kernel` | 内核相关操作(重编内核 / DTB / menuconfig) |
103
131
  | `qpi-cli clean` | 清理已打包固件或 bitbake 临时目录 |
104
132
 
@@ -121,6 +149,10 @@ qpi-cli flash ufs
121
149
  qpi-cli build --os LINUX --ver STD --dry-run
122
150
  qpi-cli flash ufs --dry-run
123
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
+
124
156
  # 调试版本(DBG)+ 安全启动
125
157
  qpi-cli build --os LINUX --ver DBG --sec
126
158
 
@@ -215,6 +247,10 @@ FLASH_ENTRY=scripts/flash.sh
215
247
  `qpi-cli flash` 最终仍然是通过 `source build.sh` 后调用 `flash <storage>` 完成,
216
248
  因此 SDK 里的烧录逻辑(自动识别 Linux/WSL 平台、选择 qdl 或 QFIL 等)完全保持不变。
217
249
 
250
+ 烧录前会先检查固件目录:当前 buildconfig 对应的版本未打包时直接给出提示,并列出
251
+ `quectel_build/` 下现成可烧录的包。用 `--fw-dir` 可以跳过 buildconfig,直接烧某个
252
+ 已打包目录(目录名或路径均可),该值通过 `QPI_FW_DIR` 传给 `flash.sh`。
253
+
218
254
  ---
219
255
 
220
256
  ## 8. 环境变量
@@ -223,6 +259,7 @@ FLASH_ENTRY=scripts/flash.sh
223
259
  |------|------|
224
260
  | `QPI_SDK_ROOT` | 指定 SDK 根目录 |
225
261
  | `QPI_CONFIG` | 指定配置文件路径(覆盖用户级默认路径) |
262
+ | `QPI_FW_DIR` | 指定烧录用的固件目录(`flash.sh` 直接读取,优先于 buildconfig) |
226
263
  | `NO_COLOR` | 设置后关闭彩色输出 |
227
264
 
228
265
  ---
@@ -245,7 +282,7 @@ FLASH_ENTRY=scripts/flash.sh
245
282
  ## 10. 从源码安装与发布
246
283
 
247
284
  ```bash
248
- git clone <本仓库>
285
+ git clone https://github.com/james-liu18/qpi-cli.git
249
286
  cd qpi-cli
250
287
 
251
288
  # 本地开发安装(可编辑)
@@ -264,6 +301,36 @@ twine upload dist/*
264
301
  版本号唯一来源是 `src/qpi_cli/__init__.py` 中的 `__version__`,
265
302
  `pyproject.toml` 通过 `dynamic = ["version"]` 自动读取,无需两处同步。
266
303
 
304
+ ### 自动发布(GitHub Actions)
305
+
306
+ 仓库内的 `.github/workflows/release.yml` 实现打 tag 自动发布:
307
+
308
+ ```bash
309
+ # 发布 0.2.1:先把 __version__ 改成 0.2.1 并提交,再打 tag
310
+ git tag v0.2.1
311
+ git push origin v0.2.1
312
+ ```
313
+
314
+ 工作流依次做三件事:
315
+
316
+ 1. 校验 tag 与包内 `__version__` 一致(不一致直接失败,避免发错版本);
317
+ 2. `python -m build` + `twine check`,并在干净 venv 里
318
+ `pip install --no-deps dist/*.whl` 后跑 `qpi-cli --version` / `--help` 自检;
319
+ 3. 用 PyPI **Trusted Publishing(OIDC)** 上传,无需在仓库里存 API token。
320
+
321
+ 首次发布前需在 PyPI 配置一次性授权(<https://pypi.org/manage/account/publishing/>
322
+ 的 "pending publisher",项目已存在则在 Project → Publishing 里加):
323
+
324
+ | 字段 | 值 |
325
+ |------|-----|
326
+ | PyPI Project Name | `qpi-cli` |
327
+ | Owner | GitHub 账号或组织(例如 `james-liu18`) |
328
+ | Repository name | `qpi-cli` |
329
+ | Workflow name | `release.yml` |
330
+ | Environment name | `pypi` |
331
+
332
+ 也支持手动触发(Actions → release → Run workflow):只构建与自检,不会上传。
333
+
267
334
  ---
268
335
 
269
336
  ## 11. 常见问题
File without changes
File without changes
File without changes