Skip to main content

qpi-cli 用户使用手册

适用平台: Linux 宿主(Ubuntu 22.04 LTS 为 SDK 验证环境)

qpi-cli 是 Quectel Pi H1(QCS6490)Yocto Linux SDK (Quectel-Pi/Pi-H1-Linux-SDK)的命令行工具。 它对 SDK 自带的 quectel_build/compile/build.sh 做一层薄封装,完成环境预检 → 环境安装 → 配置 → 构建 → 打包 → 烧录的完整流程,不改变 SDK 的任何构建逻辑。


1. 前提条件

工具 说明 最低版本
Python 运行 CLI 工具本身(仅用标准库) 3.8+
Git 拉取 SDK 源码 2.40+
Bash / coreutils SDK 构建脚本依赖 —

qpi-cli 自身不依赖任何第三方 Python 包;真正的编译依赖由 SDK 的 install_build_env.sh 安装(见 qpi-cli setup)。

另外请确认宿主资源满足 SDK 构建要求(可用 qpi-cli doctor 逐项检查):

  • 磁盘可用空间 ≥ 300 GB(BitBake 构建产物很大)
  • Swap > 32 GB、内存 ≥ 16 GB
  • Ubuntu 22.04 LTS(其他发行版可能因依赖版本导致构建失败)

2. 安装

pip install qpi-cli

安装完成后 qpi-cli 命令即可在终端全局使用。

升级到最新版:

pip install --upgrade qpi-cli

推荐的隔离安装方式(不污染系统 Python):

pipx install qpi-cli

验证安装:

qpi-cli --version
qpi-cli --help

3. 快速开始

# 1. 拉取 SDK
git clone https://github.com/Quectel-Pi/Pi-H1-Linux-SDK.git
cd Pi-H1-Linux-SDK

# 2. 宿主环境预检(只读,不改动系统)
qpi-cli doctor

# 3. 安装宿主构建环境(调用仓库里的 install_build_env.sh)
qpi-cli setup

# 4. 确认 SDK 与当前 buildconfig
qpi-cli version

# 5. 完整构建(bitbake,耗时较长)
qpi-cli build --os LINUX --ver STD

# 6. 打包出可烧录固件
qpi-cli package

# 7. 烧录到开发板
qpi-cli flash ufs

4. 命令一览

命令 作用
qpi-cli version 显示 CLI 版本与 SDK 元信息(平台 / buildconfig / 烧录入口)
qpi-cli doctor 只读预检宿主环境,逐项 PASS/WARN/FAIL
qpi-cli setup 安装宿主构建环境(执行 install_build_env.sh)
qpi-cli config 显示 / 初始化 / 读写配置
qpi-cli new <app> 创建应用工程(含 .code-workspace)
qpi-cli ls-projects 列出应用工程
qpi-cli ls-versions 列出固件版本及状态(未构建 / 已构建未打包 / 已打包)
qpi-cli build buildconfig + buildall,完整构建
qpi-cli package a_key_generation,生成可烧录固件包
qpi-cli flash [ufs|emmc] 烧录固件到开发板
qpi-cli kernel 内核相关操作(重编内核 / DTB / menuconfig)
qpi-cli clean 清理已打包固件或 bitbake 临时目录

全局参数

参数 说明
--sdk <path> 指定 SDK 根目录(默认自动探测,或读 QPI_SDK_ROOT)
--dry-run 只打印将要执行的命令,不真正执行
--verbose 显示 SDK 环境脚本输出
--version / -h 打印版本 / 帮助

全局参数既可以放在 qpi-cli 之后,也可以放在子命令之后,例如 qpi-cli build --dry-run 与 qpi-cli --dry-run build 等价。

常用示例

# 只想看看会执行什么,不真的动手
qpi-cli build --os LINUX --ver STD --dry-run
qpi-cli flash ufs --dry-run

# 调试版本(DBG)+ 安全启动
qpi-cli build --os LINUX --ver DBG --sec

# 只重编内核 / DTB
qpi-cli kernel
qpi-cli kernel --dtb
qpi-cli kernel --menuconfig

# 清理
qpi-cli clean --packages --yes     # 删除已打包的固件目录
qpi-cli clean --build --yes        # 删除 build-qcom-wayland/tmp-glibc

# 机器可读输出
qpi-cli ls-versions --json

5. SDK 根目录的探测规则

qpi-cli 在每次执行时按以下顺序寻找 SDK 根目录:

  1. 命令行 --sdk <path>;
  2. 环境变量 QPI_SDK_ROOT;
  3. 当前工作目录及其各级父目录(向上最多 6 层)。

判定条件是目录下存在 quectel_build/compile/build.sh; 若该目录下同时存在 install_build_env.sh(对外仓库的首次环境安装入口), 则优先采用。

因此常见用法有两种:

# A. 在 SDK 目录里直接用(自动探测)
cd Pi-H1-Linux-SDK && qpi-cli doctor

# B. 在任意目录指定 SDK
qpi-cli doctor --sdk ~/Pi-H1-Linux-SDK

6. 配置文件

配置的读取优先级:

  1. 环境变量 QPI_CONFIG 指向的文件(可读写);
  2. SDK 根目录下的 .qpi_config.json(只读覆盖,方便团队统一约定);
  3. 用户级默认路径 ~/.config/qpi-cli/config.json(默认写到这里)。

即:qpi-cli 不会往你 clone 的 SDK 仓库里写文件,不会弄脏 git 工作区。

qpi-cli config                      # 查看当前配置与来源
qpi-cli config --init               # 写入默认配置
qpi-cli config --set build.os=DEBIAN
qpi-cli config --get build.rev

配置内容示例:

{
  "schema": 1,
  "sdk": { "name": "yocto-h1", "type": "yocto" },
  "build": {
    "project": "QSM565DWF",
    "rev": "SG565DWFPARL1A01_BL01BP01K0M01_QDP_LP6.6.0XX.01.00X_V0X",
    "os": "LINUX",
    "version": "STD"
  }
}

qpi-cli build 成功后会把你实际使用的 project / rev / OS / version 回写到配置中, 下次不带参数执行 qpi-cli build 即沿用上次的选择。


7. 烧录入口

烧录入口从 SDK 的 tools/VERSION.txt 读取:

FLASH_ENTRY=scripts/flash.sh
  • FLASH_ENTRY 指向的文件存在时使用它;
  • 键缺失或文件不存在时,回落到 quectel_build/tools/flash.sh;
  • 当前版本仅支持 Linux 宿主:检测到 Windows 平台或 .bat 入口时会直接报错退出。

qpi-cli flash 最终仍然是通过 source build.sh 后调用 flash <storage> 完成, 因此 SDK 里的烧录逻辑(自动识别 Linux/WSL 平台、选择 qdl 或 QFIL 等)完全保持不变。


8. 环境变量

变量 作用
QPI_SDK_ROOT 指定 SDK 根目录
QPI_CONFIG 指定配置文件路径(覆盖用户级默认路径)
NO_COLOR 设置后关闭彩色输出

9. 版本状态说明

qpi-cli ls-versions 中每个固件目录有三种状态:

状态 含义
未构建 quectel_build/<rev> 目录不存在
已构建未打包 目录存在,但没有 rawprogram*.xml / prog_firehose*.elf 等打包指纹
已打包(可烧录) 目录内存在打包指纹文件,可直接用于烧录

quectel_build/ 下的 compile、tools、downloads、sstate-cache 等基础设施目录 不会被误认成固件版本。


10. 从源码安装与发布

git clone <本仓库>
cd qpi-cli

# 本地开发安装(可编辑)
pip install -e .

# 构建发布产物
python -m pip install --upgrade build twine
python -m build
# 产物在 dist/:qpi_cli-<version>-py3-none-any.whl 与 qpi_cli-<version>.tar.gz

# 上传到 PyPI
twine check dist/*
twine upload dist/*

版本号唯一来源是 src/qpi_cli/__init__.py 中的 __version__, pyproject.toml 通过 dynamic = ["version"] 自动读取,无需两处同步。


11. 常见问题

Q:提示"未找到 SDK 根目录"? A:确认当前目录在 SDK 内,或显式指定 --sdk ~/Pi-H1-Linux-SDK / QPI_SDK_ROOT。

Q:qpi-cli doctor 报磁盘 FAIL? A:BitBake 构建建议预留 ≥300 GB 可用空间,请换一个大分区或清理旧构建产物。

Q:Ubuntu 23.10+ 上构建失败,提示用户命名空间? A:执行 qpi-cli doctor 会给出提示;构建前先让 SDK 的 relax_userns_for_bitbake 生效(build.sh 中已有该函数)。

Q:qpi-cli flash 报"仅支持 Linux 宿主"? A:当前版本的烧录仅支持 Linux 宿主;Windows 下请直接使用 SDK 自带的 Windows 烧录流程。

Metadata

Release files for qpi-cli 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qpi-cli 0.2.0
File Size Uploaded Provenance Actions
qpi_cli-0.2.0.tar.gz 21.9 kB Without provenance Details for qpi_cli-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qpi-cli 0.2.0
File Interpreter ABI Platform Actions
qpi_cli-0.2.0-py3-none-any.whl Python 3 none any Details for qpi_cli-0.2.0-py3-none-any.whl

Total release size: 43.2 kB

Release files / qpi_cli-0.2.0.tar.gz

Download URL qpi_cli-0.2.0.tar.gz
Size 21.9 kB
Tags Source
SHA-256 checksum
How to use checksums
26ac26dc0d2bb8fb3b6b021d8180bc752d0c5a350688f04c1da8780482436996
BLAKE2b-256 checksum
How to use checksums
cdbbbafc3dde233b5174b0db5b451145f1c6aa4c9b053889b4027d95142a5076
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.8.10

Release files / qpi_cli-0.2.0-py3-none-any.whl

Download URL qpi_cli-0.2.0-py3-none-any.whl
Size 21.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f575dca47516691458f1626fd20b32ade47cd6a615731bdb8b2af25893eba9f7
BLAKE2b-256 checksum
How to use checksums
67aab2cd8a05280b980ba87c7a74da7e248cb568ef62816cb116efa5de7f4ebc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.8.10

Security for qpi-cli 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page