@cutos/device-id-card-reader

CUTOS 4.0 Device Capability SDK for ID card readers.

This package provides the LWA-facing TypeScript API. A compatible CUTOS Device Provider, such as device-id-card-reader-provider-ghc825 or device-id-card-reader-provider-cvr100, must be installed on the target device.

Installation

npm install @cutos/device-id-card-reader

Requires @cutos/core 4.0.8 or later.

Usage

import { DeviceCapabilityIdCardReader } from '@cutos/device-id-card-reader'

const reader = new DeviceCapabilityIdCardReader()

await reader.init()

const unsubscribeData = reader.onData(event => {
  if (event.type === 'read-card') {
    console.log(event.values.code, event.values.name)
    if (event.values.base64BMPData) {
      console.log('Portrait received')
    }
  }
})

const unsubscribeStatus = reader.onStatus(status => {
  console.log(status.status)
})

const unsubscribeError = reader.onError(error => {
  console.error(error)
})

await reader.connect()
console.log(await reader.readDeviceInfo())

// Portrait reading is optional and disabled by default.
await reader.startRead({ image: false })

// Later: stop continuous reading and disconnect.
await reader.stopRead()
await reader.disconnect()

unsubscribeData()
unsubscribeStatus()
unsubscribeError()
reader.dispose()

Reading lifecycle

startRead() returns immediately and starts continuous reading. Each successful card is delivered through onData() as a read-card event. A Provider may enter a hardware recovery cooldown before returning automatically to reading.

idle -> reading -> cooldown -> reading
           |                      |
           +------ stopRead() ----+-> idle

Call stopRead() before changing read options. Call disconnect() when the reader is no longer needed.

API

• connect() / disconnect() — open or close the physical reader.
• readDeviceInfo() — read the manufacturer, model, Provider version, device type, and hardware-specific fields such as SAMID.
• startRead({ image? }) — begin continuous reading; image requests an optional portrait data URL.
• stopRead() — stop reading and return the Provider to idle.
• onData(listener) — receive IdCardReadEvent values.
• onStatus(listener) — observe states such as online, reading, cooldown, and offline.
• onError(listener) — receive Provider and hardware errors.

IdCardData.code is always a string. When available, base64BMPData is a browser-ready image data URL.