@smart-cabinet-packages/card-reader

智能柜读卡器模块，用于管理和控制读卡设备，支持多设备并行操作和自动重连功能。

功能特点

• 完整的设备生命周期管理（初始化、连接、断开、重连）
• 多设备并行支持
• 自动重连机制
• 丰富的事件通知
• 异常处理和日志
• 支持多种卡号格式（十六进制、十进制、ASCII）
• 设备健康检查
• 类型安全的API

安装

npm install @smart-cabinet-packages/card-reader
# 或使用 yarn
yarn add @smart-cabinet-packages/card-reader
# 或使用 pnpm
pnpm add @smart-cabinet-packages/card-reader

基本使用

单设备使用

import { CardReader, CardReaderState } from '@smart-cabinet-packages/card-reader'

async function init() {
  // 创建读卡器实例
  const reader = new CardReader({
    vid: 0x1A86, // 设备供应商ID
    pid: 0xE000, // 设备产品ID
    autoReconnect: true, // 自动重连
  })
  
  // 监听卡号数据
  reader.on('data', (cardNumber, rawData) => {
    console.log('读取到卡号:', cardNumber)
  })
  
  // 监听状态变化
  reader.on('stateChange', (state, previousState) => {
    console.log(`状态从 ${previousState} 变为 ${state}`)
  })
  
  // 监听错误
  reader.on('error', (error) => {
    console.error('设备错误:', error.message)
  })
  
  // 初始化设备
  await reader.initialize()
  
  // ... 业务逻辑 ...
  
  // 使用完毕后关闭设备
  await reader.close()
}

多设备管理

import { CardManager } from '@smart-cabinet-packages/card-reader'

async function manageMultipleDevices() {
  // 创建卡片管理器
  const manager = new CardManager()
  
  // 监听设备事件
  manager.on('deviceConnected', (deviceKey, reader) => {
    console.log(`设备连接: ${deviceKey}`)
  })
  
  manager.on('data', (deviceKey, cardNumber, raw) => {
    console.log(`设备 [${deviceKey}] 读取到卡号: ${cardNumber}`)
  })
  
  // 扫描并连接所有可用读卡器
  const connectedCount = await manager.scanAndConnect()
  console.log(`连接了 ${connectedCount} 个读卡器`)
  
  // 启动自动扫描模式
  manager.startAutoScan(5000) // 每5秒扫描一次
  
  // ... 业务逻辑 ...
  
  // 使用完毕后关闭所有设备
  await manager.closeAll()
}

静态设备发现

import { discover } from '@smart-cabinet-packages/card-reader'

// 发现所有可用读卡器
const devices = discover()
console.log('发现设备:', devices)

// 查找特定VID/PID的设备
const specificDevices = discover(0x1A86, 0xE000)
console.log('发现特定设备:', specificDevices)

API 参考

CardReader 类

主要读卡器类，用于控制单个读卡设备。

// 创建实例
const reader = new CardReader(options)

// 方法
await reader.initialize() // 初始化并连接设备
await reader.close()      // 关闭设备
reader.updateOptions(newOptions) // 更新配置
reader.isHealthy()        // 检查设备健康状态

// 事件
reader.on('data', (cardNumber, rawData) => {})
reader.on('error', (error) => {})
reader.on('stateChange', (state, previousState) => {})
reader.on('connect', () => {})
reader.on('disconnect', () => {})

// 属性
reader.state // 获取当前状态

CardManager 类

用于管理多个读卡器设备。

// 创建实例
const manager = new CardManager(debug)

// 方法
await manager.scanAndConnect(options) // 扫描并连接设备
manager.startAutoScan(intervalMs, options) // 启动自动扫描
manager.stopAutoScan() // 停止自动扫描
await manager.closeAll() // 关闭所有设备
manager.getReader(deviceKey) // 获取特定设备

// 事件
manager.on('deviceConnected', (deviceKey, reader) => {})
manager.on('deviceDisconnected', (deviceKey) => {})
manager.on('error', (deviceKey, error) => {})
manager.on('data', (deviceKey, cardNumber, rawData) => {})

// 属性
manager.connectedCount // 连接的设备数量
manager.connectedDevices // 连接的设备ID列表

错误处理

该模块提供了专门的错误类型，便于错误处理和调试：

import { 
  CardReaderError,         // 基础错误类
  DeviceConnectionError,   // 设备连接错误
  InitializationError,     // 初始化错误
  ReadError,               // 读取错误
  UnsupportedDeviceError,  // 不支持的设备
  ConfigurationError       // 配置错误
} from '@smart-cabinet-packages/card-reader'

try {
  await reader.initialize()
} catch (error) {
  if (error instanceof DeviceConnectionError) {
    console.error('无法连接到设备:', error.message)
  } else if (error instanceof InitializationError) {
    console.error('设备初始化失败:', error.message)
  } else {
    console.error('未知错误:', error)
  }
}

平台支持

• Windows
• Linux
• macOS (部分支持)

在Linux系统上，可能需要root权限才能访问USB设备，或者配置udev规则。

示例

查看 example 目录获取更多使用示例。

许可证

MIT