@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

npm install @pos-360/touch-id

Usage

Import the module

import { SecugenHandler, AutoOnEvent, SecugenErrors } from '@pos-360/touch-id';

Create a new instance of the SecugenHandler class

const secugen = new SecugenHandler();

Open the device

const openResult = secugen.open();

if (openResult.ok === false) {
  console.error(openResult.message);
  process.exit(1);
}

console.log("Opened device.");

Get device information

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

const captureResult = await secugen.captureAndCreateTemplate();

if (captureResult.ok === false) {
  console.error(captureResult.message);
} else {
  console.log("Captured template:", captureResult);
}

Compare two templates

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

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

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

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

const cancelResult = await secugen.cancelCaptureFromAutoOn();

if (cancelResult.ok === false) {
  console.error(cancelResult.message);
} else {
  console.log("Cancelled capture.");
}

Close the device

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:

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

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<DefaultResponse>: 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<CaptureResult>: 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<DefaultResponse>: 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<CaptureResult>: 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<DefaultResponse>: 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<T extends AutoOnEvent>(event: T, listener: (payload: AutoOnEventPayload<T>) => 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<T extends AutoOnEvent>(event: T, listener: (payload: AutoOnEventPayload<T>) => 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 <node-gyp path>/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, "<string>", "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