# @pos-360/touch-id A Node.js native module to interface with SecuGen fingerprint readers on Windows. This module provides an intuitive API for interacting with the SecuGen Hamster SDK (sgfplib.dll). ## Features - **Device Management:** Open, close, and retrieve device information (image dimensions, contrast, brightness, etc.) from connected SecuGen fingerprint readers. - **Capture & Template Creation:** Capture fingerprint images and create fingerprint templates for matching. - **Template Matching:** Compare two fingerprint templates to determine a match. - **Auto-On Mode:** Enable convenient "auto-on" mode to capture fingerprints as soon as a finger is placed on the reader. - **Asynchronous Operations:** Fingerprint capture and template creation are asynchronous, allowing for non-blocking behavior. ## Installation ```bash npm install @pos-360/touch-id ``` ## Usage ### Import the module ```typescript import { SecugenHandler, AutoOnEvent, SecugenErrors } from '@pos-360/touch-id'; ``` ### Create a new instance of the SecugenHandler class ```typescript const secugen = new SecugenHandler(); ``` ### Open the device ```typescript const openResult = secugen.open(); if (openResult.ok === false) { console.error(openResult.message); process.exit(1); } console.log("Opened device."); ``` ### Get device information ```typescript const deviceInfoResult = secugen.getDeviceInfo(); if (deviceInfoResult.ok === false) { console.error(deviceInfoResult.message); } else { console.log("Device info:", deviceInfoResult); } ``` ### Capture a fingerprint and create a template ```typescript const captureResult = await secugen.captureAndCreateTemplate(); if (captureResult.ok === false) { console.error(captureResult.message); } else { console.log("Captured template:", captureResult); } ``` ### Compare two templates ```typescript const compareResult = await secugen.compareTemplates(template1, template2); if (compareResult.ok === false) { console.error(compareResult.message); } else { console.log("Templates match:", compareResult.isMatch); } ``` ### Start auto-on mode ```typescript const startAutoOnResult = await secugen.startAutoOn(); if (startAutoOnResult.ok === false) { console.error(startAutoOnResult.message); } else { console.log("Started auto-on mode."); secugen.subscribeToAutoOnEvent(AutoOnEvent.Capture, (payload) => { if (payload.ok === false) { console.error(payload.message); } else { console.log("Auto-on capture:", payload); } }); } ``` ### Stop auto-on mode ```typescript const stopAutoOnResult = secugen.stopAutoOn(); if (stopAutoOnResult.ok === false) { console.error(stopAutoOnResult.message); } else { console.log("Stopped auto-on mode."); } ``` ### Capture a fingerprint from auto-on mode ```typescript const captureResult = await secugen.captureFromAutoOn(5_000); if (captureResult.ok === false) { if (captureResult.code === SecugenErrors.CAPTURE_TIMEOUT) { console.log("Capture timeout."); } else { console.error(captureResult.message); } } else { console.log("Captured from auto-on:", captureResult); } ``` ### Cancel capture from auto-on mode ```typescript const cancelResult = await secugen.cancelCaptureFromAutoOn(); if (cancelResult.ok === false) { console.error(cancelResult.message); } else { console.log("Cancelled capture."); } ``` ### Close the device ```typescript const closeResult = await secugen.close(); if (closeResult.ok === false) { console.error(closeResult.message); } else { console.log("Closed device."); } ``` ## Error handling The `SecugenHandler` methods return objects with the following structure: ```typescript type GoodResult = { ok: true; // ... other properties }; type BadResult = { ok: false; code: SecugenErrorCodes; message: SecugenErrorMessages; }; ``` You can use the `ok` property to check if the operation was successful. If it was not, you can use the `code` and `message` properties to get more information about the error. The `SecugenErrors` object contains a list of all possible error codes and messages. ## Example ```typescript import { SecugenHandler, AutoOnEvent, SecugenErrors, } from "@pos-360/touch-id"; const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)); (async () => { const secugen = new SecugenHandler(); const openResult = secugen.open(); if (openResult.ok === false) { console.error(openResult.message); process.exit(1); } console.log("Opened device."); try { await secugen.startAutoOn(); console.log("Started auto-on mode."); const autoTemplateData = await secugen.captureFromAutoOn(); if (autoTemplateData.ok === false) { if (autoTemplateData.code === SecugenErrors.CAPTURE_TIMEOUT) { console.log("Capture timeout."); } else { console.error(autoTemplateData.message); } } else { console.log("Auto-on template data:", autoTemplateData); } } catch (err) { console.error(err); } finally { await secugen.close(); console.log("Closed device."); } })(); ``` ## API Reference ### `SecugenHandler` Class - `new SecugenHandler()`: Creates a new `SecugenHandler` instance. #### Methods - `open(): DefaultResponse`: Opens the connected SecuGen device. Returns a `DefaultResponse` object indicating success or failure. - `close(): Promise`: Closes the SecuGen device. Returns a Promise that resolves with a `DefaultResponse` object indicating success or failure. - `getDeviceInfo(): DeviceInfoResult`: Returns a `DeviceInfoResult` object with device information including `DeviceID`, `ImageWidth`, `ImageHeight`, `Contrast`, `Brightness`, `Gain`, and `ImageDPI`, or an error object if the device is not opened. - `captureAndCreateTemplate(): Promise`: Asynchronously captures a fingerprint image and creates a template. Returns a Promise that resolves with a `CaptureResult` object containing the raw image data and the base64-encoded template, or an error object if the device is not opened or auto-on mode is active. - `startAutoOn(): Promise`: Starts the "auto-on" mode. The provided callback function will be invoked with events when fingers are placed/removed from the reader and when captures are made. Returns a Promise that resolves with a `DefaultResponse` object indicating success or failure. - `stopAutoOn(): DefaultResponse`: Stops the "auto-on" mode. Returns a `DefaultResponse` object indicating success or failure. - `captureFromAutoOn(timeout?: number): Promise`: Asynchronously captures a fingerprint in "auto-on" mode. Returns a Promise that resolves with a `CaptureResult` object containing the raw image data and the base64-encoded template, or an error object if auto-on mode is not active or a timeout occurs. An optional `timeout` parameter in milliseconds can be provided. - `cancelCaptureFromAutoOn(): Promise`: Cancels the capture operation initiated by `captureFromAutoOn`. Returns a Promise that resolves with a `DefaultResponse` object indicating success or failure. - `compareTemplates(template1: string, template2: string): CompareResult`: Compares two base64-encoded fingerprint templates. Returns a `CompareResult` object indicating whether a match was found, or an error object if the device is not opened. - `isAutoOnActive(): boolean`: Returns a boolean indicating whether "auto-on" mode is active. - `subscribeToAutoOnEvent(event: T, listener: (payload: AutoOnEventPayload) => void): DefaultResponse`: Subscribes to an event in auto-on mode. Returns a `DefaultResponse` object indicating success or failure. Available events are `fingerOn`, `fingerOff`, `capture`, and `error`. - `unsubscribeFromAutoOnEvent(event: T, listener: (payload: AutoOnEventPayload) => void): DefaultResponse`: Unsubscribes from an event in auto-on mode. Returns a `DefaultResponse` object indicating success or failure. ## Troubleshooting ### Module not initialized If you get the error `Module not initialized` or the method calls return `{ ok: false, code: 'FAILURE_TO_INIT', message: 'Module not initialized' }`, then make sure that you have called `open()` before any other methods and that the SecuGen device is connected to your computer. ### Device not found If you get the error `Device not found`, make sure that the SecuGen device is connected to your computer and that the driver is installed. ### USB Bandwidth is not sufficient If you get the error `USB Bandwidth is not sufficient for image transfer`, try using a different USB port or a USB hub with its own power supply. ## Building ### Troubleshooting on Windows If you have a problem building on Windows due to a `openssl != ''` error, make the following edit to `/gyp/pylib/gyp/input.py`: ``` diff --git a/gyp/pylib/gyp/input.py b/gyp/pylib/gyp/input.py index 354958b..bb982eb 100644 --- a/gyp/pylib/gyp/input.py +++ b/gyp/pylib/gyp/input.py @@ -1190,7 +1190,7 @@ def EvalSingleCondition(cond_expr, true_dict, false_dict, phase, variables, buil else: ast_code = compile(cond_expr_expanded, "", "eval") cached_conditions_asts[cond_expr_expanded] = ast_code - env = {"__builtins__": {}, "v": StrictVersion} + env = {"__builtins__": {"openssl_fips": ""}, "v": StrictVersion} if eval(ast_code, env, variables): return true_dict return false_dict ``` ## License MIT