qpi-cli 0.2.0__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.
qpi_cli-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Quectel Pi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
qpi_cli-0.2.0/PKG-INFO ADDED
@@ -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,283 @@
1
+ # qpi-cli 用户使用手册
2
+
3
+ **适用平台:** Linux 宿主(Ubuntu 22.04 LTS 为 SDK 验证环境)
4
+
5
+ qpi-cli 是 Quectel Pi H1(QCS6490)Yocto Linux SDK
6
+ ([Quectel-Pi/Pi-H1-Linux-SDK](https://github.com/Quectel-Pi/Pi-H1-Linux-SDK))的命令行工具。
7
+ 它对 SDK 自带的 `quectel_build/compile/build.sh` 做一层薄封装,完成**环境预检 → 环境安装 →
8
+ 配置 → 构建 → 打包 → 烧录**的完整流程,不改变 SDK 的任何构建逻辑。
9
+
10
+ ---
11
+
12
+ ## 1. 前提条件
13
+
14
+ | 工具 | 说明 | 最低版本 |
15
+ |------|------|----------|
16
+ | Python | 运行 CLI 工具本身(仅用标准库) | 3.8+ |
17
+ | Git | 拉取 SDK 源码 | 2.40+ |
18
+ | Bash / coreutils | SDK 构建脚本依赖 | — |
19
+
20
+ qpi-cli 自身**不依赖任何第三方 Python 包**;真正的编译依赖由 SDK 的
21
+ `install_build_env.sh` 安装(见 `qpi-cli setup`)。
22
+
23
+ 另外请确认宿主资源满足 SDK 构建要求(可用 `qpi-cli doctor` 逐项检查):
24
+
25
+ - 磁盘可用空间 ≥ 300 GB(BitBake 构建产物很大)
26
+ - Swap > 32 GB、内存 ≥ 16 GB
27
+ - Ubuntu 22.04 LTS(其他发行版可能因依赖版本导致构建失败)
28
+
29
+ ---
30
+
31
+ ## 2. 安装
32
+
33
+ ```bash
34
+ pip install qpi-cli
35
+ ```
36
+
37
+ 安装完成后 `qpi-cli` 命令即可在终端全局使用。
38
+
39
+ 升级到最新版:
40
+
41
+ ```bash
42
+ pip install --upgrade qpi-cli
43
+ ```
44
+
45
+ 推荐的隔离安装方式(不污染系统 Python):
46
+
47
+ ```bash
48
+ pipx install qpi-cli
49
+ ```
50
+
51
+ 验证安装:
52
+
53
+ ```bash
54
+ qpi-cli --version
55
+ qpi-cli --help
56
+ ```
57
+
58
+ ---
59
+
60
+ ## 3. 快速开始
61
+
62
+ ```bash
63
+ # 1. 拉取 SDK
64
+ git clone https://github.com/Quectel-Pi/Pi-H1-Linux-SDK.git
65
+ cd Pi-H1-Linux-SDK
66
+
67
+ # 2. 宿主环境预检(只读,不改动系统)
68
+ qpi-cli doctor
69
+
70
+ # 3. 安装宿主构建环境(调用仓库里的 install_build_env.sh)
71
+ qpi-cli setup
72
+
73
+ # 4. 确认 SDK 与当前 buildconfig
74
+ qpi-cli version
75
+
76
+ # 5. 完整构建(bitbake,耗时较长)
77
+ qpi-cli build --os LINUX --ver STD
78
+
79
+ # 6. 打包出可烧录固件
80
+ qpi-cli package
81
+
82
+ # 7. 烧录到开发板
83
+ qpi-cli flash ufs
84
+ ```
85
+
86
+ ---
87
+
88
+ ## 4. 命令一览
89
+
90
+ | 命令 | 作用 |
91
+ |------|------|
92
+ | `qpi-cli version` | 显示 CLI 版本与 SDK 元信息(平台 / buildconfig / 烧录入口) |
93
+ | `qpi-cli doctor` | 只读预检宿主环境,逐项 PASS/WARN/FAIL |
94
+ | `qpi-cli setup` | 安装宿主构建环境(执行 `install_build_env.sh`) |
95
+ | `qpi-cli config` | 显示 / 初始化 / 读写配置 |
96
+ | `qpi-cli new <app>` | 创建应用工程(含 `.code-workspace`) |
97
+ | `qpi-cli ls-projects` | 列出应用工程 |
98
+ | `qpi-cli ls-versions` | 列出固件版本及状态(未构建 / 已构建未打包 / 已打包) |
99
+ | `qpi-cli build` | `buildconfig` + `buildall`,完整构建 |
100
+ | `qpi-cli package` | `a_key_generation`,生成可烧录固件包 |
101
+ | `qpi-cli flash [ufs\|emmc]` | 烧录固件到开发板 |
102
+ | `qpi-cli kernel` | 内核相关操作(重编内核 / DTB / menuconfig) |
103
+ | `qpi-cli clean` | 清理已打包固件或 bitbake 临时目录 |
104
+
105
+ ### 全局参数
106
+
107
+ | 参数 | 说明 |
108
+ |------|------|
109
+ | `--sdk <path>` | 指定 SDK 根目录(默认自动探测,或读 `QPI_SDK_ROOT`) |
110
+ | `--dry-run` | 只打印将要执行的命令,不真正执行 |
111
+ | `--verbose` | 显示 SDK 环境脚本输出 |
112
+ | `--version` / `-h` | 打印版本 / 帮助 |
113
+
114
+ 全局参数既可以放在 `qpi-cli` 之后,也可以放在子命令之后,例如
115
+ `qpi-cli build --dry-run` 与 `qpi-cli --dry-run build` 等价。
116
+
117
+ ### 常用示例
118
+
119
+ ```bash
120
+ # 只想看看会执行什么,不真的动手
121
+ qpi-cli build --os LINUX --ver STD --dry-run
122
+ qpi-cli flash ufs --dry-run
123
+
124
+ # 调试版本(DBG)+ 安全启动
125
+ qpi-cli build --os LINUX --ver DBG --sec
126
+
127
+ # 只重编内核 / DTB
128
+ qpi-cli kernel
129
+ qpi-cli kernel --dtb
130
+ qpi-cli kernel --menuconfig
131
+
132
+ # 清理
133
+ qpi-cli clean --packages --yes # 删除已打包的固件目录
134
+ qpi-cli clean --build --yes # 删除 build-qcom-wayland/tmp-glibc
135
+
136
+ # 机器可读输出
137
+ qpi-cli ls-versions --json
138
+ ```
139
+
140
+ ---
141
+
142
+ ## 5. SDK 根目录的探测规则
143
+
144
+ `qpi-cli` 在每次执行时按以下顺序寻找 SDK 根目录:
145
+
146
+ 1. 命令行 `--sdk <path>`;
147
+ 2. 环境变量 `QPI_SDK_ROOT`;
148
+ 3. 当前工作目录及其各级父目录(向上最多 6 层)。
149
+
150
+ 判定条件是目录下存在 `quectel_build/compile/build.sh`;
151
+ 若该目录下同时存在 `install_build_env.sh`(对外仓库的首次环境安装入口),
152
+ 则优先采用。
153
+
154
+ 因此常见用法有两种:
155
+
156
+ ```bash
157
+ # A. 在 SDK 目录里直接用(自动探测)
158
+ cd Pi-H1-Linux-SDK && qpi-cli doctor
159
+
160
+ # B. 在任意目录指定 SDK
161
+ qpi-cli doctor --sdk ~/Pi-H1-Linux-SDK
162
+ ```
163
+
164
+ ---
165
+
166
+ ## 6. 配置文件
167
+
168
+ 配置的读取优先级:
169
+
170
+ 1. 环境变量 `QPI_CONFIG` 指向的文件(可读写);
171
+ 2. SDK 根目录下的 `.qpi_config.json`(**只读覆盖**,方便团队统一约定);
172
+ 3. 用户级默认路径 `~/.config/qpi-cli/config.json`(默认写到这里)。
173
+
174
+ 即:qpi-cli **不会**往你 clone 的 SDK 仓库里写文件,不会弄脏 git 工作区。
175
+
176
+ ```bash
177
+ qpi-cli config # 查看当前配置与来源
178
+ qpi-cli config --init # 写入默认配置
179
+ qpi-cli config --set build.os=DEBIAN
180
+ qpi-cli config --get build.rev
181
+ ```
182
+
183
+ 配置内容示例:
184
+
185
+ ```json
186
+ {
187
+ "schema": 1,
188
+ "sdk": { "name": "yocto-h1", "type": "yocto" },
189
+ "build": {
190
+ "project": "QSM565DWF",
191
+ "rev": "SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X",
192
+ "os": "LINUX",
193
+ "version": "STD"
194
+ }
195
+ }
196
+ ```
197
+
198
+ `qpi-cli build` 成功后会把你实际使用的 project / rev / OS / version 回写到配置中,
199
+ 下次不带参数执行 `qpi-cli build` 即沿用上次的选择。
200
+
201
+ ---
202
+
203
+ ## 7. 烧录入口
204
+
205
+ 烧录入口从 SDK 的 `tools/VERSION.txt` 读取:
206
+
207
+ ```
208
+ FLASH_ENTRY=scripts/flash.sh
209
+ ```
210
+
211
+ - `FLASH_ENTRY` 指向的文件存在时使用它;
212
+ - 键缺失或文件不存在时,回落到 `quectel_build/tools/flash.sh`;
213
+ - 当前版本**仅支持 Linux 宿主**:检测到 Windows 平台或 `.bat` 入口时会直接报错退出。
214
+
215
+ `qpi-cli flash` 最终仍然是通过 `source build.sh` 后调用 `flash <storage>` 完成,
216
+ 因此 SDK 里的烧录逻辑(自动识别 Linux/WSL 平台、选择 qdl 或 QFIL 等)完全保持不变。
217
+
218
+ ---
219
+
220
+ ## 8. 环境变量
221
+
222
+ | 变量 | 作用 |
223
+ |------|------|
224
+ | `QPI_SDK_ROOT` | 指定 SDK 根目录 |
225
+ | `QPI_CONFIG` | 指定配置文件路径(覆盖用户级默认路径) |
226
+ | `NO_COLOR` | 设置后关闭彩色输出 |
227
+
228
+ ---
229
+
230
+ ## 9. 版本状态说明
231
+
232
+ `qpi-cli ls-versions` 中每个固件目录有三种状态:
233
+
234
+ | 状态 | 含义 |
235
+ |------|------|
236
+ | 未构建 | `quectel_build/<rev>` 目录不存在 |
237
+ | 已构建未打包 | 目录存在,但没有 `rawprogram*.xml` / `prog_firehose*.elf` 等打包指纹 |
238
+ | 已打包(可烧录) | 目录内存在打包指纹文件,可直接用于烧录 |
239
+
240
+ `quectel_build/` 下的 `compile`、`tools`、`downloads`、`sstate-cache` 等基础设施目录
241
+ 不会被误认成固件版本。
242
+
243
+ ---
244
+
245
+ ## 10. 从源码安装与发布
246
+
247
+ ```bash
248
+ git clone <本仓库>
249
+ cd qpi-cli
250
+
251
+ # 本地开发安装(可编辑)
252
+ pip install -e .
253
+
254
+ # 构建发布产物
255
+ python -m pip install --upgrade build twine
256
+ python -m build
257
+ # 产物在 dist/:qpi_cli-<version>-py3-none-any.whl 与 qpi_cli-<version>.tar.gz
258
+
259
+ # 上传到 PyPI
260
+ twine check dist/*
261
+ twine upload dist/*
262
+ ```
263
+
264
+ 版本号唯一来源是 `src/qpi_cli/__init__.py` 中的 `__version__`,
265
+ `pyproject.toml` 通过 `dynamic = ["version"]` 自动读取,无需两处同步。
266
+
267
+ ---
268
+
269
+ ## 11. 常见问题
270
+
271
+ **Q:提示"未找到 SDK 根目录"?**
272
+ A:确认当前目录在 SDK 内,或显式指定 `--sdk ~/Pi-H1-Linux-SDK` / `QPI_SDK_ROOT`。
273
+
274
+ **Q:`qpi-cli doctor` 报磁盘 FAIL?**
275
+ A:BitBake 构建建议预留 ≥300 GB 可用空间,请换一个大分区或清理旧构建产物。
276
+
277
+ **Q:Ubuntu 23.10+ 上构建失败,提示用户命名空间?**
278
+ A:执行 `qpi-cli doctor` 会给出提示;构建前先让 SDK 的
279
+ `relax_userns_for_bitbake` 生效(`build.sh` 中已有该函数)。
280
+
281
+ **Q:`qpi-cli flash` 报"仅支持 Linux 宿主"?**
282
+ A:当前版本的烧录仅支持 Linux 宿主;Windows 下请直接使用 SDK 自带的
283
+ Windows 烧录流程。
@@ -0,0 +1,42 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "qpi-cli"
7
+ dynamic = ["version"]
8
+ description = "QuecPi QCS6490 (PI H1) Yocto Linux SDK 命令行工具 (构建 / 打包 / 烧录)"
9
+ readme = "README.md"
10
+ requires-python = ">=3.8"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "Quectel Pi" }]
13
+ keywords = ["quectel", "quecpi", "qpi", "qcs6490", "yocto", "sdk", "bitbake", "cli"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Environment :: Console",
17
+ "Intended Audience :: Developers",
18
+ "License :: OSI Approved :: MIT License",
19
+ "Operating System :: POSIX :: Linux",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.8",
22
+ "Programming Language :: Python :: 3.9",
23
+ "Programming Language :: Python :: 3.10",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Programming Language :: Python :: 3.12",
26
+ "Topic :: Software Development :: Build Tools",
27
+ ]
28
+
29
+ [project.urls]
30
+ Homepage = "https://github.com/Quectel-Pi/Pi-H1-Linux-SDK"
31
+
32
+ [project.scripts]
33
+ qpi-cli = "qpi_cli.cli:main"
34
+
35
+ [tool.setuptools]
36
+ package-dir = { "" = "src" }
37
+
38
+ [tool.setuptools.packages.find]
39
+ where = ["src"]
40
+
41
+ [tool.setuptools.dynamic]
42
+ version = { attr = "qpi_cli.__version__" }
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,21 @@
1
+ # -*- coding: utf-8 -*-
2
+ """qpi-cli — QuecPi QCS6490 (PI H1) Yocto Linux SDK 命令行。
3
+
4
+ 对 Quectel-Pi/Pi-H1-Linux-SDK 仓库做一层薄封装, 不改变任何构建逻辑。
5
+ 真正的构建/打包/烧录仍由 quectel_build/compile/build.sh 里的函数完成:
6
+ buildconfig / buildall / buildpackage / flash / buildenv / buildkernel / builddtb
7
+
8
+ 只依赖 Python 3 标准库, 不引入任何第三方包。
9
+ """
10
+
11
+ __version__ = "0.2.0"
12
+ CLI_NAME = "qpi-cli"
13
+
14
+ __all__ = ["__version__", "CLI_NAME", "main"]
15
+
16
+
17
+ def main(argv=None):
18
+ """控制台入口 (qpi-cli / python -m qpi_cli)。"""
19
+ from .cli import main as _main
20
+
21
+ return _main(argv)
@@ -0,0 +1,9 @@
1
+ # -*- coding: utf-8 -*-
2
+ """支持 `python -m qpi_cli`。"""
3
+
4
+ import sys
5
+
6
+ from .cli import main
7
+
8
+ if __name__ == "__main__":
9
+ sys.exit(main())