Printer Cleaner

可扩展的跨平台打印机自动维护框架，通过局域网发现打印机、读取黑白和彩色累计页数，并根据最近一周的打印活动决定是否执行打印头清洗。当前首先实现 Epson 支持，欢迎扩展 Canon、HP、Brother 及其他厂商。支持 Windows 11、macOS 和 Ubuntu。

Extensible cross-platform printer maintenance framework with network discovery, monochrome and color page counters, automatic print-head cleaning, nozzle checks, and scheduled background execution. Epson is the first implemented vendor; contributions for Canon, HP, Brother, and other printer vendors are welcome.

中文 · English

中文

功能

• 通过 mDNS/DNS-SD 自动发现局域网中的兼容 Epson 打印机。
• 通过 SNMP 动态读取打印机型号、出厂编号（SN）和累计页数。
• 分别统计打印总页数、黑白总页数和彩色总页数。
• 比较至少一周前的历史快照，判断最近一周是否同时打印过黑白和彩色内容。
• 如果黑白或彩色任意一项没有增长，可自动执行一次普通打印头清洗。
• 使用 --nozzle-check 控制自动清洗后是否打印喷嘴检查页。
• 多台匹配打印机可由 Tokio 并行检查和维护。
• 用户消息支持简体中文和英文，详细运行信息写入日志文件。
• 提供 Windows 11、macOS 和 Ubuntu 的定时安装与卸载脚本。

兼容性与原理

程序将通用打印机逻辑和厂商协议分离。Epson 实现使用以下网络协议：

• mDNS/DNS-SD：发现提供 RAW/AppSocket 服务的打印机。
• SNMP 和 Printer-MIB：读取型号、SN 及状态信息。Printer-MIB 参考 RFC 3805。
• TCP 9100：发送 Epson ESC/P2 REMOTE1 打印头清洗和喷嘴检查指令。

维护协议已在 Epson L6170 上实机验证。其他 Epson 喷墨型号即使能够被发现，也不代表维护命令一定兼容；在新型号上使用前建议先运行 stats 和 --dry-run 验证。

安全默认值

• 首次运行没有一周前的历史记录时，只建立计数基线，默认不清洗。
• 只有指定 --clean-first 才会在首次运行时执行维护。
• --dry-run 只读取和判断，不发送清洗或喷嘴检查任务。
• 自动维护在七天内最多执行一次，避免重复清洗。
• 默认不打印喷嘴检查页；需要时指定 --nozzle-check。
• 历史文件中的型号和 SN 必须与当前打印机完全一致。

命令行使用

显示中文帮助：

printer-cleaner --lang cn --help

显示英文帮助：

printer-cleaner --lang en --help

自动发现打印机并执行每周检查：

printer-cleaner check

指定打印机地址：

printer-cleaner check --host 192.168.1.100

只查看累计页数：

printer-cleaner stats --host 192.168.1.100

预览维护判断，不执行清洗或打印：

printer-cleaner check --dry-run

自动清洗后打印喷嘴检查页：

printer-cleaner check --nozzle-check

立即清洗或打印喷嘴检查页：

printer-cleaner clean --host 192.168.1.100
printer-cleaner nozzle-check --host 192.168.1.100

历史和日志

程序在当前用户的 home 目录中使用以下隐藏目录：

~/.printer_cleaner/
├── history.csv
└── printer-cleaner.log

自动发现多台打印机时，每台打印机会使用独立的历史文件。日志使用 INFO 级别，包含用户消息和供开发人员排查问题的详细信息。

安装为定时任务

从 GitHub Releases 下载对应平台的压缩包，解压到一个长期保留的目录。二进制、安装脚本和卸载脚本必须放在同一目录；安装程序不会复制二进制。

Ubuntu 或 macOS：

chmod +x printer-cleaner install.sh uninstall.sh
./install.sh

Windows 11 PowerShell：

powershell -ExecutionPolicy Bypass -File .\install.ps1

安装脚本会先删除同名旧任务，创建 ~/.printer_cleaner，然后注册每天 10:00 左右运行的用户级任务：

printer-cleaner check --lang cn

移动解压目录后，请在新目录重新运行安装脚本，使定时任务使用新的二进制绝对路径。

卸载

Ubuntu 或 macOS：

./uninstall.sh

Windows 11 PowerShell：

powershell -ExecutionPolicy Bypass -File .\uninstall.ps1

卸载会删除定时任务，并删除整个 ~/.printer_cleaner 目录，包括历史记录和日志。

从源码构建

需要稳定版 Rust 工具链：

cargo test --locked
cargo build --release --locked

生成的二进制位于 target/release/。项目中的 GitHub Actions 工作流可自动生成 Ubuntu x86_64、macOS ARM64、macOS Intel x86_64 和 Windows x86_64 发布包。

参与贡献

项目并不限于 Epson。厂商相关操作通过 PrinterVendor trait 抽象，每个厂商使用独立的 src/vendor/<vendor>/ 目录。欢迎提交 Canon、HP、Brother 等打印机的发现、身份识别、页数读取和维护协议实现，也欢迎补充已实机验证的型号和协议文档。

GitHub：github.com/bistack/printer-cleaner

许可证

Copyright 2026 Sun Zhenyuan. 本项目使用 Apache License 2.0。

---

English

Features

• Discovers compatible Epson printers on the local network using mDNS/DNS-SD.
• Reads the printer model, serial number, and lifetime counters dynamically over SNMP.
• Reports total, monochrome, and color page counts separately.
• Compares the current counters with a snapshot at least seven days old.
• Runs one normal print-head cleaning when either monochrome or color pages did not increase during the weekly window.
• Optionally prints a nozzle-check page after automatic cleaning with --nozzle-check.
• Checks and maintains multiple discovered printers concurrently with Tokio.
• Provides Simplified Chinese and English user messages plus detailed file logging.
• Includes scheduled installation and uninstallation scripts for Windows 11, macOS, and Ubuntu.

Compatibility and protocols

The application separates generic printer logic from vendor-specific operations. The Epson implementation uses:

• mDNS/DNS-SD to discover printers offering a RAW/AppSocket service.
• SNMP and Printer-MIB to read identity and status information. See RFC 3805 for Printer-MIB.
• TCP port 9100 to submit Epson ESC/P2 REMOTE1 head-cleaning and nozzle-check commands.

The maintenance protocol has been verified on an Epson L6170. Discovery of another Epson inkjet model does not guarantee that its maintenance commands are compatible. Use stats and --dry-run before enabling maintenance on an unverified model.

Safe defaults

• On the first run, the program creates a counter baseline and does not clean by default.
• First-run maintenance requires --clean-first.
• --dry-run reads and evaluates data without submitting cleaning or nozzle-check jobs.
• Automatic maintenance has a seven-day cooldown to prevent repeated cleaning.
• No nozzle-check page is printed unless --nozzle-check is specified.
• A history file is accepted only when both its model and serial number match the current printer.

Command-line usage

Show English help:

printer-cleaner --lang en --help

Discover printers and run the weekly check:

printer-cleaner check

Use a specific printer:

printer-cleaner check --host 192.168.1.100

Show lifetime page counters only:

printer-cleaner stats --host 192.168.1.100

Evaluate without cleaning or printing:

printer-cleaner check --dry-run

Print a nozzle-check page after automatic cleaning:

printer-cleaner check --nozzle-check

Run maintenance immediately:

printer-cleaner clean --host 192.168.1.100
printer-cleaner nozzle-check --host 192.168.1.100

History and logs

Runtime data is stored under the current user's home directory:

~/.printer_cleaner/
├── history.csv
└── printer-cleaner.log

When multiple printers are discovered, each printer receives a separate history file. INFO-level logs contain user messages and detailed diagnostic information for developers.

Scheduled installation

Download the archive for your platform from GitHub Releases and extract it to a permanent directory. Keep the executable, installer, and uninstaller together; the installer does not copy the executable.

Ubuntu or macOS:

chmod +x printer-cleaner install.sh uninstall.sh
./install.sh

Windows 11 PowerShell:

powershell -ExecutionPolicy Bypass -File .\install.ps1

The installer removes any previous task with the same name, creates ~/.printer_cleaner, and registers a user-level task that runs at approximately 10:00 every day:

printer-cleaner check --lang cn

If the extracted directory is moved, run the installer again from its new location so that the scheduled task receives the new absolute executable path.

Uninstallation

Ubuntu or macOS:

./uninstall.sh

Windows 11 PowerShell:

powershell -ExecutionPolicy Bypass -File .\uninstall.ps1

Uninstallation removes the scheduled task and the entire ~/.printer_cleaner directory, including history and log files.

Build from source

A stable Rust toolchain is required:

cargo test --locked
cargo build --release --locked

The binary is written to target/release/. The included GitHub Actions workflow builds release archives for Ubuntu x86_64, macOS ARM64, macOS Intel x86_64, and Windows x86_64.

Contributing

This project is not limited to Epson printers. Vendor-specific operations are abstracted by the PrinterVendor trait, with each implementation living under src/vendor/<vendor>/. Contributions implementing discovery, identity, page counters, and maintenance protocols for Canon, HP, Brother, and other vendors are welcome. Verified model information and protocol documentation are also valuable contributions.

GitHub: github.com/bistack/printer-cleaner

License

Copyright 2026 Sun Zhenyuan. Licensed under the Apache License 2.0.

Search keywords

Epson printer maintenance, printer cleaner, print-head cleaning, nozzle check, ESC/P2, SNMP Printer-MIB, mDNS printer discovery, Rust printer utility, automatic inkjet maintenance, Windows printer maintenance, macOS printer utility, Ubuntu printer service.