EpsonCleanerQt

面向 Windows 的 Epson 打印机识别与喷嘴清洗工具，基于 PyQt5 开发，包含客户端激活流程和内部发卡工具。

这个项目的核心目标是：

• 自动扫描系统中的本地和已连接打印机
• 标记并识别 Epson 品牌打印机
• 为支持的打印机提供喷嘴清洗入口
• 在无法直接调用厂商命令时，优先走驱动界面自动化流程
• 提供激活码校验机制，便于交付给客户使用

功能概览

• 启动后自动扫描打印机，显示名称、端口、在线状态
• 识别 Epson 相关打印机并开放“清洗”按钮
• 支持逐台加入队列，按顺序执行喷嘴清洗
• 支持两种清洗方式：
  • 外部维护命令
  • 驱动界面自动化
• 支持清洗过程状态提示和失败提示
• 源码运行时默认显示维护自动化追踪窗口
• 提供客户端激活弹窗、机器码生成与卡密校验
• 提供内部使用的图形化发卡器和命令行发卡脚本

运行环境

• Windows 10 / 11
• Python 3.10+
• 已安装 Epson 打印机驱动

项目依赖：

• PyQt5
• pywin32
• PyInstaller
• pytest

安装依赖

推荐先创建本地虚拟环境：

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt

如果你已经处于虚拟环境中，也可以直接执行：

pip install -r requirements.txt

启动客户端

python app.py

启动后程序会先检查本机授权信息。

• 如果本机尚未激活，会弹出激活窗口
• 激活窗口会显示机器码
• 将机器码发给内部人员生成卡密后，输入卡密即可完成激活
• 激活成功后进入主界面

激活与发卡

客户端激活流程

1. 客户端运行 python app.py 或打包后的 PrinterTool.exe
2. 程序显示机器码
3. 内部人员根据机器码和到期日生成卡密
4. 客户输入卡密并激活

授权文件默认保存在：

%LOCALAPPDATA%\PrinterTool\license.dat

命令行生成卡密

python generate_license.py --machine-code ABCDEF1234567890 --expiry-date 2030-01-01

图形化发卡器

开发环境启动：

python license_generator_app.py

打包后可使用 LicenseGenerator.exe。这个工具建议仅内部保留，不要发给客户。

清洗逻辑说明

程序会优先按下面的顺序尝试清洗：

1. 如果设置了 EPSON_CLEAN_COMMAND，优先执行外部维护命令
2. 如果未设置外部命令，且识别为 Epson 打印机，则尝试驱动界面自动化
3. 如果前两者都不可用，并且允许模拟，则返回模拟清洗结果

当前 Epson 识别依据主要来自打印机名称和驱动名称中的关键字匹配。

可选环境变量

EPSON_CLEAN_COMMAND

用于配置外部清洗命令模板，可使用 {printer_name} 占位。

示例：

set EPSON_CLEAN_COMMAND=clean-tool --printer "{printer_name}"

SIMULATE_CLEANING

控制在没有可用真实清洗命令时，是否允许使用模拟流程。

• 1：允许，默认值
• 0：不允许

PRINTER_TOOL_SHOW_MAINTENANCE_UI

控制是否显示内置维护追踪窗口。

• 源码直接运行时默认显示
• 打包后的默认版本默认隐藏
• 设置为 1 时强制显示
• 设置为 0 时强制隐藏

打包

打包客户端

默认打包：

python build_exe.py

输出文件位于：

dist\PrinterTool.exe

显示维护追踪窗口的版本：

python build_exe.py --show-maintenance-ui

输出文件位于：

dist\PrinterToolMaintenanceVisible.exe

一次打包两个版本：

python build_exe.py --both

打包发卡器

python build_license_exe.py

输出文件位于：

dist\LicenseGenerator.exe

打包注意事项

• 项目已适配 PyInstaller 单文件模式
• printer_tool/scripts/driver_cleaning.ps1 会被自动打包进可执行文件
• 如果项目路径或本地 .venv 路径包含中文，打包脚本会自动使用临时 ASCII 盘符重新执行，尽量规避 PyInstaller 在 Windows 中文路径下的兼容问题

测试

运行全部测试：

pytest -q

当前仓库包含：

• 单元测试
• UI 辅助逻辑测试
• 打包命令测试
• 驱动自动化脚本约束测试

项目结构

.
├─ app.py                         # 客户端入口
├─ app_maintenance_visible.py     # 强制显示维护追踪窗口的入口
├─ license_generator_app.py       # 图形化发卡器入口
├─ generate_license.py            # 命令行发卡脚本
├─ build_exe.py                   # 客户端打包脚本
├─ build_license_exe.py           # 发卡器打包脚本
├─ printer_tool/
│  ├─ ui.py                       # 主界面
│  ├─ services.py                 # 打印机扫描与清洗服务
│  ├─ registration.py             # 机器码、卡密、授权存储
│  ├─ registration_ui.py          # 激活窗口
│  ├─ license_generator_ui.py     # 发卡器界面
│  ├─ maintenance_automation.py   # 驱动维护自动化封装
│  └─ scripts/
│     ├─ driver_cleaning.ps1      # 驱动界面自动化脚本
│     └─ priority_right_hold.py   # 优先级调整辅助脚本
└─ tests/                         # 自动化测试

说明

• 这个项目主要面向 Epson 打印机维护场景
• 驱动界面自动化依赖实际驱动窗口结构，驱动版本变化可能影响稳定性
• 如果后续拿到更稳定的官方维护命令行接口，可以优先接入 EPSON_CLEAN_COMMAND
• LicenseGenerator.exe 和生成卡密的能力建议仅内部保留