qpi-cli 0.2.0__py3-none-any.whl

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.
@@ -0,0 +1,307 @@
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
+ # qpi-cli 用户使用手册
26
+
27
+ **适用平台:** Linux 宿主(Ubuntu 22.04 LTS 为 SDK 验证环境)
28
+
29
+ qpi-cli 是 Quectel Pi H1(QCS6490)Yocto Linux SDK
30
+ ([Quectel-Pi/Pi-H1-Linux-SDK](https://github.com/Quectel-Pi/Pi-H1-Linux-SDK))的命令行工具。
31
+ 它对 SDK 自带的 `quectel_build/compile/build.sh` 做一层薄封装,完成**环境预检 → 环境安装 →
32
+ 配置 → 构建 → 打包 → 烧录**的完整流程,不改变 SDK 的任何构建逻辑。
33
+
34
+ ---
35
+
36
+ ## 1. 前提条件
37
+
38
+ | 工具 | 说明 | 最低版本 |
39
+ |------|------|----------|
40
+ | Python | 运行 CLI 工具本身(仅用标准库) | 3.8+ |
41
+ | Git | 拉取 SDK 源码 | 2.40+ |
42
+ | Bash / coreutils | SDK 构建脚本依赖 | — |
43
+
44
+ qpi-cli 自身**不依赖任何第三方 Python 包**;真正的编译依赖由 SDK 的
45
+ `install_build_env.sh` 安装(见 `qpi-cli setup`)。
46
+
47
+ 另外请确认宿主资源满足 SDK 构建要求(可用 `qpi-cli doctor` 逐项检查):
48
+
49
+ - 磁盘可用空间 ≥ 300 GB(BitBake 构建产物很大)
50
+ - Swap > 32 GB、内存 ≥ 16 GB
51
+ - Ubuntu 22.04 LTS(其他发行版可能因依赖版本导致构建失败)
52
+
53
+ ---
54
+
55
+ ## 2. 安装
56
+
57
+ ```bash
58
+ pip install qpi-cli
59
+ ```
60
+
61
+ 安装完成后 `qpi-cli` 命令即可在终端全局使用。
62
+
63
+ 升级到最新版:
64
+
65
+ ```bash
66
+ pip install --upgrade qpi-cli
67
+ ```
68
+
69
+ 推荐的隔离安装方式(不污染系统 Python):
70
+
71
+ ```bash
72
+ pipx install qpi-cli
73
+ ```
74
+
75
+ 验证安装:
76
+
77
+ ```bash
78
+ qpi-cli --version
79
+ qpi-cli --help
80
+ ```
81
+
82
+ ---
83
+
84
+ ## 3. 快速开始
85
+
86
+ ```bash
87
+ # 1. 拉取 SDK
88
+ git clone https://github.com/Quectel-Pi/Pi-H1-Linux-SDK.git
89
+ cd Pi-H1-Linux-SDK
90
+
91
+ # 2. 宿主环境预检(只读,不改动系统)
92
+ qpi-cli doctor
93
+
94
+ # 3. 安装宿主构建环境(调用仓库里的 install_build_env.sh)
95
+ qpi-cli setup
96
+
97
+ # 4. 确认 SDK 与当前 buildconfig
98
+ qpi-cli version
99
+
100
+ # 5. 完整构建(bitbake,耗时较长)
101
+ qpi-cli build --os LINUX --ver STD
102
+
103
+ # 6. 打包出可烧录固件
104
+ qpi-cli package
105
+
106
+ # 7. 烧录到开发板
107
+ qpi-cli flash ufs
108
+ ```
109
+
110
+ ---
111
+
112
+ ## 4. 命令一览
113
+
114
+ | 命令 | 作用 |
115
+ |------|------|
116
+ | `qpi-cli version` | 显示 CLI 版本与 SDK 元信息(平台 / buildconfig / 烧录入口) |
117
+ | `qpi-cli doctor` | 只读预检宿主环境,逐项 PASS/WARN/FAIL |
118
+ | `qpi-cli setup` | 安装宿主构建环境(执行 `install_build_env.sh`) |
119
+ | `qpi-cli config` | 显示 / 初始化 / 读写配置 |
120
+ | `qpi-cli new <app>` | 创建应用工程(含 `.code-workspace`) |
121
+ | `qpi-cli ls-projects` | 列出应用工程 |
122
+ | `qpi-cli ls-versions` | 列出固件版本及状态(未构建 / 已构建未打包 / 已打包) |
123
+ | `qpi-cli build` | `buildconfig` + `buildall`,完整构建 |
124
+ | `qpi-cli package` | `a_key_generation`,生成可烧录固件包 |
125
+ | `qpi-cli flash [ufs\|emmc]` | 烧录固件到开发板 |
126
+ | `qpi-cli kernel` | 内核相关操作(重编内核 / DTB / menuconfig) |
127
+ | `qpi-cli clean` | 清理已打包固件或 bitbake 临时目录 |
128
+
129
+ ### 全局参数
130
+
131
+ | 参数 | 说明 |
132
+ |------|------|
133
+ | `--sdk <path>` | 指定 SDK 根目录(默认自动探测,或读 `QPI_SDK_ROOT`) |
134
+ | `--dry-run` | 只打印将要执行的命令,不真正执行 |
135
+ | `--verbose` | 显示 SDK 环境脚本输出 |
136
+ | `--version` / `-h` | 打印版本 / 帮助 |
137
+
138
+ 全局参数既可以放在 `qpi-cli` 之后,也可以放在子命令之后,例如
139
+ `qpi-cli build --dry-run` 与 `qpi-cli --dry-run build` 等价。
140
+
141
+ ### 常用示例
142
+
143
+ ```bash
144
+ # 只想看看会执行什么,不真的动手
145
+ qpi-cli build --os LINUX --ver STD --dry-run
146
+ qpi-cli flash ufs --dry-run
147
+
148
+ # 调试版本(DBG)+ 安全启动
149
+ qpi-cli build --os LINUX --ver DBG --sec
150
+
151
+ # 只重编内核 / DTB
152
+ qpi-cli kernel
153
+ qpi-cli kernel --dtb
154
+ qpi-cli kernel --menuconfig
155
+
156
+ # 清理
157
+ qpi-cli clean --packages --yes # 删除已打包的固件目录
158
+ qpi-cli clean --build --yes # 删除 build-qcom-wayland/tmp-glibc
159
+
160
+ # 机器可读输出
161
+ qpi-cli ls-versions --json
162
+ ```
163
+
164
+ ---
165
+
166
+ ## 5. SDK 根目录的探测规则
167
+
168
+ `qpi-cli` 在每次执行时按以下顺序寻找 SDK 根目录:
169
+
170
+ 1. 命令行 `--sdk <path>`;
171
+ 2. 环境变量 `QPI_SDK_ROOT`;
172
+ 3. 当前工作目录及其各级父目录(向上最多 6 层)。
173
+
174
+ 判定条件是目录下存在 `quectel_build/compile/build.sh`;
175
+ 若该目录下同时存在 `install_build_env.sh`(对外仓库的首次环境安装入口),
176
+ 则优先采用。
177
+
178
+ 因此常见用法有两种:
179
+
180
+ ```bash
181
+ # A. 在 SDK 目录里直接用(自动探测)
182
+ cd Pi-H1-Linux-SDK && qpi-cli doctor
183
+
184
+ # B. 在任意目录指定 SDK
185
+ qpi-cli doctor --sdk ~/Pi-H1-Linux-SDK
186
+ ```
187
+
188
+ ---
189
+
190
+ ## 6. 配置文件
191
+
192
+ 配置的读取优先级:
193
+
194
+ 1. 环境变量 `QPI_CONFIG` 指向的文件(可读写);
195
+ 2. SDK 根目录下的 `.qpi_config.json`(**只读覆盖**,方便团队统一约定);
196
+ 3. 用户级默认路径 `~/.config/qpi-cli/config.json`(默认写到这里)。
197
+
198
+ 即:qpi-cli **不会**往你 clone 的 SDK 仓库里写文件,不会弄脏 git 工作区。
199
+
200
+ ```bash
201
+ qpi-cli config # 查看当前配置与来源
202
+ qpi-cli config --init # 写入默认配置
203
+ qpi-cli config --set build.os=DEBIAN
204
+ qpi-cli config --get build.rev
205
+ ```
206
+
207
+ 配置内容示例:
208
+
209
+ ```json
210
+ {
211
+ "schema": 1,
212
+ "sdk": { "name": "yocto-h1", "type": "yocto" },
213
+ "build": {
214
+ "project": "QSM565DWF",
215
+ "rev": "SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X",
216
+ "os": "LINUX",
217
+ "version": "STD"
218
+ }
219
+ }
220
+ ```
221
+
222
+ `qpi-cli build` 成功后会把你实际使用的 project / rev / OS / version 回写到配置中,
223
+ 下次不带参数执行 `qpi-cli build` 即沿用上次的选择。
224
+
225
+ ---
226
+
227
+ ## 7. 烧录入口
228
+
229
+ 烧录入口从 SDK 的 `tools/VERSION.txt` 读取:
230
+
231
+ ```
232
+ FLASH_ENTRY=scripts/flash.sh
233
+ ```
234
+
235
+ - `FLASH_ENTRY` 指向的文件存在时使用它;
236
+ - 键缺失或文件不存在时,回落到 `quectel_build/tools/flash.sh`;
237
+ - 当前版本**仅支持 Linux 宿主**:检测到 Windows 平台或 `.bat` 入口时会直接报错退出。
238
+
239
+ `qpi-cli flash` 最终仍然是通过 `source build.sh` 后调用 `flash <storage>` 完成,
240
+ 因此 SDK 里的烧录逻辑(自动识别 Linux/WSL 平台、选择 qdl 或 QFIL 等)完全保持不变。
241
+
242
+ ---
243
+
244
+ ## 8. 环境变量
245
+
246
+ | 变量 | 作用 |
247
+ |------|------|
248
+ | `QPI_SDK_ROOT` | 指定 SDK 根目录 |
249
+ | `QPI_CONFIG` | 指定配置文件路径(覆盖用户级默认路径) |
250
+ | `NO_COLOR` | 设置后关闭彩色输出 |
251
+
252
+ ---
253
+
254
+ ## 9. 版本状态说明
255
+
256
+ `qpi-cli ls-versions` 中每个固件目录有三种状态:
257
+
258
+ | 状态 | 含义 |
259
+ |------|------|
260
+ | 未构建 | `quectel_build/<rev>` 目录不存在 |
261
+ | 已构建未打包 | 目录存在,但没有 `rawprogram*.xml` / `prog_firehose*.elf` 等打包指纹 |
262
+ | 已打包(可烧录) | 目录内存在打包指纹文件,可直接用于烧录 |
263
+
264
+ `quectel_build/` 下的 `compile`、`tools`、`downloads`、`sstate-cache` 等基础设施目录
265
+ 不会被误认成固件版本。
266
+
267
+ ---
268
+
269
+ ## 10. 从源码安装与发布
270
+
271
+ ```bash
272
+ git clone <本仓库>
273
+ cd qpi-cli
274
+
275
+ # 本地开发安装(可编辑)
276
+ pip install -e .
277
+
278
+ # 构建发布产物
279
+ python -m pip install --upgrade build twine
280
+ python -m build
281
+ # 产物在 dist/:qpi_cli-<version>-py3-none-any.whl 与 qpi_cli-<version>.tar.gz
282
+
283
+ # 上传到 PyPI
284
+ twine check dist/*
285
+ twine upload dist/*
286
+ ```
287
+
288
+ 版本号唯一来源是 `src/qpi_cli/__init__.py` 中的 `__version__`,
289
+ `pyproject.toml` 通过 `dynamic = ["version"]` 自动读取,无需两处同步。
290
+
291
+ ---
292
+
293
+ ## 11. 常见问题
294
+
295
+ **Q:提示"未找到 SDK 根目录"?**
296
+ A:确认当前目录在 SDK 内,或显式指定 `--sdk ~/Pi-H1-Linux-SDK` / `QPI_SDK_ROOT`。
297
+
298
+ **Q:`qpi-cli doctor` 报磁盘 FAIL?**
299
+ A:BitBake 构建建议预留 ≥300 GB 可用空间,请换一个大分区或清理旧构建产物。
300
+
301
+ **Q:Ubuntu 23.10+ 上构建失败,提示用户命名空间?**
302
+ A:执行 `qpi-cli doctor` 会给出提示;构建前先让 SDK 的
303
+ `relax_userns_for_bitbake` 生效(`build.sh` 中已有该函数)。
304
+
305
+ **Q:`qpi-cli flash` 报"仅支持 Linux 宿主"?**
306
+ A:当前版本的烧录仅支持 Linux 宿主;Windows 下请直接使用 SDK 自带的
307
+ Windows 烧录流程。
@@ -0,0 +1,12 @@
1
+ qpi_cli/__init__.py,sha256=qSTpLygkkC6QfB-sY1RnRmLQJ1nsA9neV3H6UfhjAKI,651
2
+ qpi_cli/__main__.py,sha256=J01T5wj2yiKH1eYs7JDYIhMbX3hZnXU0VQmMmDJy_zQ,144
3
+ qpi_cli/cli.py,sha256=v1LzTf3ifxcq-Vr2qQbMa8pfnx7icj8_40uboK1N_MA,6247
4
+ qpi_cli/commands.py,sha256=SqqaHvppgMsJNuNid4Mj4hSqFgYOa-M4IDSsYp52Ioo,19568
5
+ qpi_cli/core.py,sha256=MCfrOT86sZUkjyN-Y7MASm8Mz7fuKsgHNXDOQh-gXmI,12837
6
+ qpi_cli/templates.py,sha256=pzshyJUZ7PVdm9348xo-8rDB7qH2WAhNDJ05pxKuth0,874
7
+ qpi_cli-0.2.0.dist-info/LICENSE,sha256=7eQeIG79qqLrhXZdRabyssfYdoLjfdENVXEqvtUnwpg,1067
8
+ qpi_cli-0.2.0.dist-info/METADATA,sha256=Y40Fh38p6zhi5YyTWfHDm2OG0jqYjt-kWx5B3VbZldU,9074
9
+ qpi_cli-0.2.0.dist-info/WHEEL,sha256=BNRMDyzLkkcmlv0J8ppDQkk2VED33SesJDynr9ED1gc,91
10
+ qpi_cli-0.2.0.dist-info/entry_points.txt,sha256=vN0tvzlQGlRg73AGXXp-DEWdONLYwGE5uJNWQZh2-eU,45
11
+ qpi_cli-0.2.0.dist-info/top_level.txt,sha256=XH2Ye6AO8e0LB4kVZqWSdF4swx9U0Cjv0rltCx0K9lg,8
12
+ qpi_cli-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (75.3.4)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ qpi-cli = qpi_cli.cli:main
@@ -0,0 +1 @@
1
+ qpi_cli