Metadata-Version: 2.4
Name: cpdevice-flash
Version: 0.1.1
Summary: 全志和高通刷机工具的独立 Python 接口
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# cpdevice-flash

全志和高通刷机工具的独立 Python 包。无需 Qt、ADB 库或测试框架，安装对应平台的 wheel 后即可调用包内原生工具。

```python
from cpdevice_flash import Flasher

flasher = Flasher("allwinner", log_callback=print, progress_callback=print)
devices = flasher.scan()  # 设备需已处于 FEL/FES；高通为 EDL。
# 明确选择扫描结果中的目标，再调用：
# result = flasher.flash("firmware.img", device=selected_device)
```

平台名称为 `allwinner` 或 `qualcomm`。全志接受本地 `.img/.fex`；高通接受 flat build 目录或 ZIP，支持 `flash_config.json`，刷写前执行 dry-run 检查镜像依赖。`preflight(path)` 可单独检查输入。

`FlashDevice` 明确指定 USB bus/port 或 EDL serial，不自动选择第一台设备。`cancel()` 可以从其他线程取消任务；取消后的实例不再复用。`FlashError` 是调用失败的公共基类，子类区分工具缺失、进程失败、超时、取消、固件错误和设备选择错误。进程失败异常提供 `command`、`returncode`、`output` 日志尾部。

进度回调接收 `FlashProgress(platform, stage, percent, message)`。原生工具的分区进度不会被当作整包进度；未知完成率的 `percent` 为 `None`。`complete` 表示原生工具成功退出，实际系统启动及 ADB 版本校验仍需上层执行。

```bash
python -m cpdevice_flash info
python -m cpdevice_flash scan --platform allwinner
python -m cpdevice_flash preflight --platform qualcomm /path/to/firmware.zip
```

工具查找顺序：显式 `tool_path`，环境变量 `ALLWINNER_FLASH_TOOL`/`QUALCOMM_FLASH_TOOL`，wheel 内附带工具，系统 PATH。显式路径无效时直接失败。当前包不执行 ADB 重启，不下载远程固件，也不安装系统 USB 驱动；测试框架负责这些步骤。

每个操作系统和 CPU 架构独立构建 wheel。构建命令为仓库中的 `tools/build_flash_wheel.py`；详见项目 `docs/python-flash-package.md`。Linux 使用 auditwheel 打包依赖库，macOS 修正动态库路径并签名，Windows 收集非系统 DLL。wheel 不保证跨系统运行。

0.1.1 包含全志 FEL/FES 握手等待、高通无序列号设备的 USB 端口路径定位、ZIP 类型预检查和失败日志保留等修复。macOS ARM64 和 x86_64 已通过隔离安装、原生工具启动及高通模拟预检查（x86_64 通过 Rosetta 运行）；Windows x64 产物使用 MinGW-w64 交叉构建并检查 PE 架构、DLL 依赖和包完整性，原生 Windows 运行及 USB 实机刷写尚待验证。
