EPSON打印机状态监控 Node.js原生模块

一个强大的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打印机

安装

npm install epson-printer-status

系统要求

• 操作系统: Windows (x64, ia32)
• Node.js: >= 14.0.0
• EPSON StatusAPI: 需要安装EPSON Advanced Printer Driver
• Visual Studio: 编译时需要VS2019或VS2022 C++构建工具

快速开始

基础使用

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);
        }
    }
}

API文档

EpsonPrinterMonitor

主要的打印机监控类。

方法

connect(printerName: string): Promise<number>

连接到指定的打印机。

参数:

• printerName - 打印机名称（在Windows设备管理器中显示的名称）

返回值:

• Promise<number> - 成功时返回打印机句柄，失败时抛出异常

示例:

const handle = await monitor.connect('EPSON TM-T100 Receipt6');

disconnect(): Promise<number>

断开与打印机的连接。

返回值:

• Promise<number> - 操作结果码

setStatusCallback(callback: StatusCallback): Promise<number>

设置状态变化回调函数。

参数:

• callback - 状态回调函数

回调函数参数:

interface PrinterStatus {
    result: number;           // 操作结果码
    value: number;           // 状态值（数值）
    hex: string;             // 状态值（十六进制）
    bits: ASBStatusBits;     // ASB状态位
    description: StatusDescription; // 状态描述
    timestamp: string;       // ISO时间戳
    printer: string | null;  // 打印机名称
}

getStatus(): Promise<PrinterStatus>

获取当前打印机状态。

ASB状态位说明

| 状态位 | 值 | 描述 | |--------|----|----- | | 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 | 打印机被锁定 |

实际应用示例

监控多个状态并处理事件

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() {
    // 处理裁纸器错误
}

开发指南

构建源码

# 克隆代码
git clone https://github.com/yourusername/epson-printer-status.git
cd epson-printer-status

# 安装依赖
npm install

# 编译原生模块
npm run build

# 运行测试
npm test

调试

启用详细日志输出：

# Windows
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 文件

贡献

欢迎提交Issue和Pull Request！

更新日志

v1.0.0

• 初始发布
• 支持实时状态监控
• 完整ASB状态解析
• TypeScript类型定义
• 双语支持（中文/英文）

相关链接

• EPSON官方开发文档
• 问题报告
• 更新日志