5分钟快速上手:epson_print_conf安装与首次连接教程(Windows/macOS/Linux/Nix)
5分钟快速上手:epson_print_conf安装与首次连接教程(Windows/macOS/Linux/Nix)
epson_print_conf 是一款免费的 Epson 打印机配置工具与废墨计数器(waste ink counter)重置工具,通过 Wi-Fi(SNMP/TCP-IP)或 USB 连接爱普生打印机,支持查看墨水余量、维护盒状态、喷头清洁、EEPROM 读写与访问密钥检测等功能。本教程带你 5 分钟完成安装并成功连接第一台打印机。
🧭 它能为你的打印机做什么
在动手安装前,先花 10 秒了解 epson_print_conf 的核心能力:
- 📶 SNMP 网络连接:通过 TCP/IP(SNMP 协议)管理 Wi-Fi 打印机,自动发现 IP 与型号
- 🔌 USB 直连:对固件锁定网络 EEPROM 访问的新机型,走 IEEE 1284.4(D4)
EPSON-CTRL通道,命令与功能完全一致 - 📊 详细状态报告:解码
@BDC ST2状态帧,读取墨量、纸张路径、维护盒信息、废墨水平等 - 🧪 高级维护:清洁/强力清洁喷头、打印测试图案、调整断电定时器、EEPROM 读写与转储
- ♻️ 废墨计数器重置:临时重置或永久重置(
--reset_waste_ink),解除"维护盒已满"锁定 - 🐍 三种接口:图形界面(GUI)、命令行工具(CLI)、Python API,各取所需
⚠️ 安全提示:废墨计数器重置只是"移除锁定",并不能替代物理更换废墨垫/维护盒。请同步安排维护,避免墨水溢出影响打印质量。
📦 3分钟安装:全平台一键步骤
所有平台都基于 Python,核心都是 3 条命令:
git clone https://gitcode.com/gh_mirrors/ep/epson_print_conf
cd epson_print_conf
pip install -r requirements.txt
依赖清单见 requirements.txt,核心包含 pysnmp、epson-usb(USB 通道库)、pyprintlpr 等。
Windows 🪟
- 安装 Python(勾选 "Add to PATH")后按上面 3 条命令执行即可
- Tkinter 在新版 Windows 的 Python 中默认自带,无需额外操作
- 不想装 Python?官方发布(Releases)提供预编译的
epson_print_conf.exe,解压双击即可运行,由 epson_print_conf.spec 定义打包规则
macOS(Docker 方式)🍎
macOS 上推荐官方提供的 Docker 方案(Dockerfile + start.sh 内置 Xvfb + VNC,图形界面通过远程桌面访问):
git clone https://gitcode.com/gh_mirrors/ep/epson_print_conf
cd epson_print_conf
sudo docker build -t epson_print_conf .
sudo docker run --name epson_print_conf -p 5990:5990 epson_print_conf
准备一个 VNC 客户端(如 TigerVNC、RealVNC、Remmina),连接 localhost:90,密码 1234,即可看到 GUI。
Linux 🐧
除 3 条通用命令外,Ubuntu/Debian 需补装 Tkinter 图形库:
sudo apt install python3-tk
Nix ❄️
仓库自带 Flake(flake.nix / package.nix),进入项目目录后:
nix run . # 运行命令行工具
nix run .#ui # 运行图形界面
安装到 flake 系统后可直接使用 4 个命令:epson_print_conf、epson_print_conf_ui、epson_print_conf_find_printers、epson_print_conf_parse_devices。
🔌 首次连接:GUI 图形界面(推荐新手)
安装完成后,启动图形界面(源码入口 ui.py):
python ui.py
GUI 基于 Tcl/Tk,Windows/macOS/Linux 均可运行。首次连接有两种方式:
方式一:一键自动发现打印机
- 在界面上点击 Detect Printers 按钮
- 工具会自动扫描局域网,列出发现的打印机 IP 地址与型号名称
- 选中目标打印机即可开始操作
自动发现功能由 find_printers.py 提供,输出类似:
[{'ip': '192.168.178.29', 'hostname': 'EPSONDEFD03.fritz.box', 'name': 'EPSON XP-205 207 Series'}]
方式二:手动填写型号 + IP
在 Printer Connection 区域手动输入:
- 型号(Model):例如
XP-205(不确定型号可先自动发现) - 地址(Address):打印机 IP,例如
192.168.1.87(在打印机控制面板或路由器 DHCP 列表中查看)
若打印机未被内置配置收录,或状态不可管理,可点击 Detect Access Keys 进行密钥检测(可能耗时数分钟,请保持打印机电源开启);也可以从"文件"菜单导入外部打印机配置库(XML/TOML/PICKLE 格式)。
💻 命令行快速连接:一行命令查看状态
习惯终端的用户可直接用 CLI 入口 epson_print_conf.py。查看完整状态报告:
python3 epson_print_conf.py -m XP-205 -a 192.168.1.87 -i
常用操作速查:
| 需求 | 命令 |
|---|---|
| 查看完整状态 | -i(默认选项) |
| 查看指定项 | -q printer_status、-q 'MAC Address' |
| 永久重置废墨计数器 | --reset_waste_ink |
| 临时重置废墨计数器 | --temp_reset_waste_ink |
| 修改断电定时器(分钟) | --write-poweroff-timer 15 |
| 暴力破解 read_key | --detect-key |
| 读写 EEPROM 地址 | -R 173,172 / -W 173:1,172:0xde |
例如一键重置废墨计数器:
python3 epson_print_conf.py -m XP-205 -a 192.168.1.87 --reset_waste_ink
🖨️ USB 模式连接:固件锁定机型的救星
部分新机型(以及更新过固件的旧机型)出于安全考虑关闭了 SNMP 的 EEPROM 访问(如 L3250、ET-2850、XP-7100 等)。此时改用 USB 线缆连接,功能完全相同:
- GUI:在 Printer Connection 下拉框选择 USB
- CLI:加
--usb参数(自动忽略-a地址):
python3 epson_print_conf.py -m XP-205 --usb -i
- 环境变量方式:设置
EPSON_USB
USB 通道实现位于 epson_usb_bridge.py,底层使用 epson-usb 库:Windows 直接调用 Epson 驱动已发布的 USBPRINT 接口,无需更换驱动;Linux/macOS 通过 libusb 临时接管厂商专属接口,关闭时自动归还内核驱动。
找不到设备?先运行诊断:
python3 epson_print_conf.py --list-usb
它会列出可用后端、候选设备及 USB 接口编号(打印机断电时也可运行)。
⚠️ 上手后必看的 3 条经验
- 改动前先抄 [NOTE]:GUI 在每次 EEPROM 改写前会在状态栏显示
[NOTE]行,记录改写前的值。把它复制保存下来,之后可直接粘回 "Write EEPROM" 文本框完成逆向恢复(详见 README 的 "How to revert a change performed through the GUI")。 - 写入有回读校验:每个写入字节都会被回读比对,防止部分固件"假 OK"(返回
:OK;但实际丢弃写入)。如确认固件可靠,可用--no-verify-writes跳过校验。 - 密钥扫描建议走 USB:
--detect-key暴力枚举最多 65536 个候选,SNMP 通道在数百次请求后可能失联,USB 上 961 个候选 10 秒内即可完成;扫描中可按 Ctrl+C 安全停止。
📁 相关文件速查
| 文件 | 说明 |
|---|---|
| ui.py | 图形界面入口(Tcl/Tk) |
| epson_print_conf.py | 命令行工具与核心实现 |
| epson_usb_bridge.py | USB 传输层 |
| find_printers.py | 局域网打印机自动发现 |
| parse_devices.py | 外部配置库(XML/TOML)转换器 |
| requirements.txt | Python 依赖清单 |
| flake.nix / package.nix | Nix 构建定义 |
| Dockerfile / start.sh | macOS Docker 方案 |
| epson_print_conf.spec | PyInstaller 打包配置 |
至此,epson_print_conf 的安装与首次连接就全部完成了。下一步建议先运行一次状态查询熟悉输出内容,再做任何重置操作——祝你的爱普生打印机"返老还童"!