epson-printer-status
Version:
EPSON打印机状态监控 - Node.js原生模块，支持实时状态回调和完整ASB状态解析
347 lines (253 loc) • 9.65 kB
Markdown
[](https://badge.fury.io/js/epson-printer-status)
[](https://github.com/yourusername/epson-printer-status/actions)
一个强大的Node.js原生模块，用于实时监控EPSON打印机状态，支持完整的ASB（Automatic Status Back）状态解析和事件回调。
- 🚀 **实时状态监控** - 通过回调函数实时接收打印机状态变化
- 📊 **完整ASB状态解析** - 支持所有官方ASB状态位的详细解析
- 🌐 **双语支持** - 提供中文和英文状态描述
- 💪 **TypeScript支持** - 完整的类型定义
- 🔧 **易于使用** - 简洁的API设计，支持Promise
- 🎯 **专为Windows优化** - 基于EPSON官方StatusAPI开发
支持所有兼容EPSON StatusAPI的热敏打印机，包括但不限于：
- EPSON TM系列（TM-T88、TM-T20、TM-T82、TM-T100等）
- EPSON TM-U系列
- 其他支持ASB协议的EPSON POS打印机
```bash
npm install epson-printer-status
```
- **操作系统**: Windows (x64, ia32)
- **Node.js**: >= 14.0.0
- **EPSON StatusAPI**: 需要安装EPSON Advanced Printer Driver
- **Visual Studio**: 编译时需要VS2019或VS2022 C++构建工具
```javascript
const { createMonitor } = require('epson-printer-status');
async function main() {
const monitor = createMonitor();
try {
// 连接打印机
const handle = await monitor.connect('EPSON TM-T100 Receipt6');
console.log(`连接成功！句柄: ${handle}`);
// 获取当前状态
const status = await monitor.getStatus();
console.log('当前状态:', status);
// 设置状态监控回调
await monitor.setStatusCallback((status) => {
console.log('状态变化:', {
value: status.value,
hex: status.hex,
timestamp: status.timestamp,
description: status.description.chinese
});
});
console.log('开始监控打印机状态...');
// 程序将持续运行，监控状态变化
process.on('SIGINT', async () => {
await monitor.disconnect();
console.log('已断开连接');
process.exit(0);
});
} catch (error) {
console.error('错误:', error.message);
}
}
main();
```
```typescript
import { EpsonPrinterMonitor, PrinterStatus, StatusCallback } from 'epson-printer-status';
class PrinterService {
private monitor: EpsonPrinterMonitor;
constructor() {
this.monitor = new EpsonPrinterMonitor();
}
async connectToPrinter(printerName: string): Promise<void> {
const statusCallback: StatusCallback = (status: PrinterStatus) => {
console.log('状态更新:', status.description.chinese);
// 检查关键状态
if (status.bits.ASB_RECEIPT_END) {
console.log('警告: 纸张用完！');
}
if (status.bits.ASB_COVER_OPEN) {
console.log('警告: 打印机盖板打开！');
}
};
try {
await this.monitor.connect(printerName);
await this.monitor.setStatusCallback(statusCallback);
console.log('打印机监控已启动');
} catch (error) {
console.error('连接失败:', error);
}
}
}
```
主要的打印机监控类。
连接到指定的打印机。
**参数:**
- `printerName` - 打印机名称（在Windows设备管理器中显示的名称）
**返回值:**
- `Promise<number>` - 成功时返回打印机句柄，失败时抛出异常
**示例:**
```javascript
const handle = await monitor.connect('EPSON TM-T100 Receipt6');
```
断开与打印机的连接。
**返回值:**
- `Promise<number>` - 操作结果码
设置状态变化回调函数。
**参数:**
- `callback` - 状态回调函数
**回调函数参数:**
```typescript
interface PrinterStatus {
result: number; // 操作结果码
value: number; // 状态值（数值）
hex: string; // 状态值（十六进制）
bits: ASBStatusBits; // ASB状态位
description: StatusDescription; // 状态描述
timestamp: string; // ISO时间戳
printer: string | null; // 打印机名称
}
```
获取当前打印机状态。
| 状态位 | 值 | 描述 |
|--------|----|----- |
| `ASB_NO_RESPONSE` | 0x00000001 | 无打印机回应 |
| `ASB_PRINT_SUCCESS` | 0x00000002 | 打印完成 |
| `ASB_DRAWER_KICK` | 0x00000004 | 货币纸盒连接器插针状态 |
| `ASB_OFF_LINE` | 0x00000008 | 脱机状态 |
| `ASB_COVER_OPEN` | 0x00000020 | 盖板打开 |
| `ASB_PAPER_FEED` | 0x00000040 | 进纸器开关状态 |
| `ASB_AUTOCUTTER_ERR` | 0x00000800 | 自动裁纸器错误 |
| `ASB_UNRECOVER_ERR` | 0x00002000 | 不可恢复的错误 |
| `ASB_AUTORECOVER_ERR` | 0x00004000 | 自动恢复的错误 |
| `ASB_RECEIPT_NEAR_END` | 0x00020000 | 接近卷纸末端 |
| `ASB_RECEIPT_END` | 0x00080000 | 卷纸末端（无纸） |
| `ASB_SPOOLER_IS_STOPPED` | 0x80000000 | 停止卷轴 |
常见错误码说明：
| 错误码 | 名称 | 描述 |
|--------|------|------|
| 0 | SUCCESS | 成功 |
| -30 | ERR_NO_PRINTER | 无打印机驱动 |
| -60 | ERR_HANDLE | 无效句柄 |
| -90 | ERR_PARAM | 参数错误 |
| -1000 | ERR_LOCKED | 打印机被锁定 |
```javascript
const { createMonitor, ASB_STATUS_BITS } = require('epson-printer-status');
async function setupPrinterMonitoring() {
const monitor = createMonitor();
await monitor.connect('EPSON TM-T100 Receipt6');
await monitor.setStatusCallback((status) => {
const { bits, description, timestamp } = status;
// 纸张状态检查
if (bits.ASB_RECEIPT_END) {
console.log(`[${timestamp}] ❌ 纸张用完 - 需要更换纸卷`);
// 触发补纸提醒
notifyPaperEmpty();
} else if (bits.ASB_RECEIPT_NEAR_END) {
console.log(`[${timestamp}] ⚠️ 纸张即将用完`);
// 预警通知
notifyPaperLow();
}
// 打印机状态检查
if (bits.ASB_COVER_OPEN) {
console.log(`[${timestamp}] 🔓 打印机盖板打开`);
pausePrinting();
}
if (bits.ASB_OFF_LINE) {
console.log(`[${timestamp}] 🔌 打印机脱机`);
handleOfflineError();
}
// 错误状态检查
if (bits.ASB_AUTOCUTTER_ERR) {
console.log(`[${timestamp}] ⚙️ 自动裁纸器错误`);
handleCutterError();
}
});
}
// 业务处理函数
function notifyPaperEmpty() {
// 发送通知、暂停打印队列等
}
function notifyPaperLow() {
// 预警通知
}
function pausePrinting() {
// 暂停打印作业
}
function handleOfflineError() {
// 处理脱机错误
}
function handleCutterError() {
// 处理裁纸器错误
}
```
```bash
git clone https://github.com/yourusername/epson-printer-status.git
cd epson-printer-status
npm install
npm run build
npm test
```
启用详细日志输出：
```bash
set DEBUG=epson-printer-status
npm test
process.env.DEBUG = 'epson-printer-status';
```
1. **权限要求**: 需要管理员权限才能访问某些打印机功能
2. **独占访问**: 同一时间只能有一个应用程序监控同一台打印机
3. **驱动依赖**: 必须安装EPSON官方驱动程序
4. **Windows限定**: 目前仅支持Windows平台
**Q: 连接失败，错误码-30**
A: 检查打印机名称是否正确，确认已安装EPSON驱动
**Q: 回调函数不触发**
A: 确认打印机支持ASB协议，检查USB/网络连接
**Q: 编译失败**
A: 确保安装了Visual Studio构建工具，设置正确的msvs_version
**Q: 模块加载失败**
A: 检查Node.js版本兼容性，确认系统架构匹配（x64/x86）
MIT License - 详见 [LICENSE](LICENSE) 文件
欢迎提交Issue和Pull Request！
- 初始发布
- 支持实时状态监控
- 完整ASB状态解析
- TypeScript类型定义
- 双语支持（中文/英文）
- [EPSON官方开发文档](https://www.epson.com/)
- [问题报告](https://github.com/yourusername/epson-printer-status/issues)
- [更新日志](https://github.com/yourusername/epson-printer-status/releases)