Scanner Driver
The SDK communicates with fingerprint scanners through a local WebSocket driver. The DriverSocket class manages the connection, automatic reconnection, and event dispatching.
Architecture
The local driver runs as a local service on the user's machine and exposes a WebSocket endpoint at ws://127.0.0.1:2794/hk-reader. The SDK connects to this endpoint automatically when the client is created.
Connection lifecycle
On construction, DriverSocket attempts to connect. If the connection drops, it reconnects with exponential backoff. Calling destroy() terminates the connection permanently.
Exponential backoff
When the connection drops, the driver reconnects with exponential backoff:
| Attempt | Delay |
|---|---|
| 1 | 2s |
| 2 | 4s |
| 3 | 8s |
| 4 | 16s |
| 5+ | 32s (capped at 60s) |
Events
The DriverSocket emits the following events via its internal EventEmitter:
| Event | Payload | Description |
|---|---|---|
connected | — | WebSocket connection established |
disconnected | — | WebSocket connection lost |
sensorConnected | DeviceDescription.data | Scanner device detected and described |
sensorDisconnected | deviceId?: number | Scanner device lost |
fingerprintPreview | base64Image: string | Preview frame from scanner (BMP) |
fingerprintResult | base64Image: string, score?: number, deviceId?: number | Final result with quality score |