DigitalPersona U.are.U SDK — Fingerprint Microservice for Linux

Enterprise-grade Linux driver integration and a lightweight C-based HTTP microservice for DigitalPersona / Crossmatch U.are.U biometric fingerprint readers. The microservice exposes a fully standards-compliant RESTful API enabling web-based kiosk terminals, single-page applications (Angular, React, Vue), and desktop frontends to communicate directly with USB fingerprint hardware on Linux.

Overview

This repository provides all required packages, runtime libraries, udev rules, systemd unit files, and an embedded HTTP microservice that bridges USB fingerprint hardware to any HTTP client over localhost.

Key Capabilities

Capability	Description
Direct Hardware Bridge	Communicates with DigitalPersona hardware via the low-level C SDK (`libdpfpdd`, `libdpfj`)
Full SDK Utilisation	Image capture, FMD template extraction (ISO/IEC 19794-2), quality assessment, BMP serialization
RESTful HTTP API v1	Single-port server powered by GNU libmicrohttpd; versioned under `/api/v1`
Enrollment Sessions	Multi-sample capture in one request (`POST /api/v1/enrollment`)
Uniform JSON Envelope	All responses follow a consistent `{ "success": bool, "data"/"error": {...} }` schema
Correct HTTP Semantics	Proper status codes (200, 204, 404, 405, 500, 503) and HTTP verb routing
CORS Support	Pre-flight OPTIONS handling for browser-based clients
Systemd Integration	Production-ready service unit with automatic restart and journal logging

Supported Hardware

Family	Models
U.are.U Series	4500, 5100, 5200, 5300
Eikon Series	Eikon 510, 710, Eikon2
Architecture	Linux x86_64 (x64); ARM/ARMHF via SDK redist tarballs

Repository Structure

.
├── Crossmatch/                        # DigitalPersona runtime libraries
│   └── urusdk-linux/Linux/lib/
│       ├── java/                      # Java bindings (dpuareu.jar)
│       └── x64/                       # Core shared libraries (*.so)
│
├── finger/                            # C HTTP Microservice source
│   ├── Makefile                       # GCC build script; links libmicrohttpd + SDK
│   ├── fingerprint_capture.h          # Capture API declarations and FingerprintCaptureResult
│   ├── fingerprint_capture.c          # Image capture, FMD extraction, quality, BMP, Base64
│   ├── fingerprint_selection.h        # Device enumeration and serial query declarations
│   ├── fingerprint_selection.c        # dpfpdd_query_devices / dpfpdd_open implementation
│   ├── fingerprint_server.c           # RESTful HTTP server (libmicrohttpd dispatcher)
│   ├── execute_fingerprint.sh         # Startup wrapper for tmux/systemd
│   └── restart-service.sh             # Session restart script
│
├── sdk/                               # Official vendor SDK distribution
│   ├── README.txt                     # Vendor release notes
│   └── sdk/                           # Installer binaries and scripts
│       ├── docs/                      # PDF developer and platform guides
│       ├── install                    # Vendor installation script
│       └── installers/                # Binary setup archives (32/64-bit)
│
├── systemd/
│   └── digitalpersona-fingerprint.service  # Systemd unit file
│
├── INSTALLATION.md                    # Detailed installation and configuration manual
└── README.md                          # This document

Quick Start

Prerequisites

sudo apt update
sudo apt install -y build-essential libmicrohttpd-dev tmux

Configure Libraries and Udev Rules

Full instructions: INSTALLATION.md

# Copy runtime libraries
sudo cp -r Crossmatch /usr/lib/
sudo bash -c 'printf "/usr/lib/Crossmatch/urusdk-linux/Linux/lib/java\n/usr/lib/Crossmatch/urusdk-linux/Linux/lib/x64\n" > /etc/ld.so.conf.d/digitalpersona.conf'
sudo ldconfig

# Install udev rules
sudo cp /opt/Crossmatch/urusdk-linux/redist/*.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger

Build and Run

cd finger
make
./finger

The microservice starts listening on http://127.0.0.1:5050/api/v1.

REST API Reference

Base URL: http://127.0.0.1:5050/api/v1

All responses use the JSON envelope described in Response Envelope.

Endpoint Summary

Method	Endpoint	Description
`GET`	`/api/v1/device`	Reader connection status
`GET`	`/api/v1/device/info`	Reader metadata (name, DPI, serial)
`POST`	`/api/v1/capture`	Single capture: Base64 BMP image + FMD template
`POST`	`/api/v1/enrollment`	Multi-sample enrollment session (N captures)
`DELETE`	`/api/v1/capture`	Cancel an in-progress capture session

GET /api/v1/device

Check whether a fingerprint reader is connected.

Response 200 — Reader present:

{
  "success": true,
  "data": {
    "connected": true
  }
}

Response 503 — No reader detected:

{
  "success": false,
  "error": {
    "code": 503,
    "message": "No fingerprint reader detected. Verify USB connection and udev rules."
  }
}

GET /api/v1/device/info

Retrieve metadata about the connected fingerprint reader.

Response 200:

{
  "success": true,
  "data": {
    "connected": true,
    "device_name": "\\?\usb#vid_05ba&pid_000a#...",
    "serial_number": "5000216000000000",
    "resolution_dpi": 500
  }
}

POST /api/v1/capture

Perform a single fingerprint acquisition cycle. Blocks until the user places a finger on the sensor.

Acquisition pipeline:

Opens the USB reader via dpfpdd_open()
Acquires a raw FID image via dpfpdd_capture() (ISO/IEC 19794-4 format)
Scores image quality via dpfj_get_fid_quality() (0–100 scale)
Extracts an FMD minutiae template via dpfj_create_fmd_from_fid() (ISO/IEC 19794-2:2005)
Serializes the image to a cropped 24-bit BMP and encodes it as Base64

Request body: (none required)

Response 200:

{
  "success": true,
  "data": {
    "image_base64": "<base64-encoded BMP>",
    "fmd_base64": "<base64-encoded ISO/IEC 19794-2 FMD template>",
    "fmd_format": "ISO_19794_2_2005",
    "quality": 87,
    "serial_number": "5000216000000000"
  }
}

Response 500 — Capture or extraction error:

{
  "success": false,
  "error": {
    "code": 500,
    "message": "dpfpdd_capture() failed (rc=-2147483624)"
  }
}

POST /api/v1/enrollment

Perform a multi-sample fingerprint enrollment session. The server captures each sample sequentially, blocking between captures until the user places and removes their finger. Use this endpoint for biometric registration workflows requiring N consistent samples.

Request body:

{
  "count": 4,
  "finger_index": 2,
  "session_id": "enroll-nip-123456"
}

Field	Type	Required	Description
`count`	integer (1–10)	Yes	Number of capture samples
`finger_index`	integer	No	NIST finger position code (see table below)
`session_id`	string	No	Caller-supplied session identifier; auto-generated if omitted

NIST Finger Position Codes (ISO/IEC 19794-2):

Code	Finger	Code	Finger
`0`	Unknown	`6`	Left Thumb
`1`	Right Thumb	`7`	Left Index
`2`	Right Index	`8`	Left Middle
`3`	Right Middle	`9`	Left Ring
`4`	Right Ring	`10`	Left Little
`5`	Right Little

Response 200:

{
  "success": true,
  "data": {
    "session_id": "enroll-nip-123456",
    "finger_index": 2,
    "fmd_format": "ISO_19794_2_2005",
    "serial_number": "5000216000000000",
    "samples_requested": 4,
    "samples_captured": 4,
    "samples": [
      { "index": 0, "fmd_base64": "Rk1SAA...", "quality": 87 },
      { "index": 1, "fmd_base64": "Rk1SAB...", "quality": 91 },
      { "index": 2, "fmd_base64": "Rk1SAC...", "quality": 82 },
      { "index": 3, "fmd_base64": "Rk1SAD...", "quality": 89 }
    ]
  }
}

Response 500 — Sample capture failed:

{
  "success": false,
  "error": {
    "code": 500,
    "message": "Sample 2 capture failed: Capture was cancelled."
  }
}

DELETE /api/v1/capture

Cancel an in-progress fingerprint capture session. Sends SIGINT to the active tmux session, which triggers dpfpdd_cancel() via the registered signal handler and unblocks the capture call. Works for both single-capture and enrollment sessions.

Request body: (none required)

Response 200:

{
  "success": true,
  "data": {
    "message": "Capture session cancelled."
  }
}

Response Envelope

All API responses conform to the following uniform JSON schema:

Success

{
  "success": true,
  "data": { }
}

Error

{
  "success": false,
  "error": {
    "code": 503,
    "message": "Human-readable error description."
  }
}

HTTP Status Codes

Code	Meaning
`200 OK`	Request succeeded; response body contains a `data` object
`204 No Content`	CORS OPTIONS preflight acknowledged
`404 Not Found`	Unknown or misspelled endpoint URL
`405 Method Not Allowed`	HTTP verb not supported by this endpoint
`500 Internal Server Error`	SDK error or unexpected system failure
`503 Service Unavailable`	No fingerprint reader detected

Enrollment Session Flow

Example: enroll 4 samples of the right index finger from an Angular/React frontend.

1. Check reader availability
   GET /api/v1/device
   ← { "success": true, "data": { "connected": true } }

2. Start enrollment session (4 samples, right index finger)
   POST /api/v1/enrollment
   → { "count": 4, "finger_index": 2, "session_id": "enroll-nip-198501012010011001" }

   ⏳ Server blocks — user must place and lift finger 4 times sequentially

   ← {
       "success": true,
       "data": {
         "session_id": "enroll-nip-198501012010011001",
         "samples_captured": 4,
         "samples": [ ...4 FMD entries... ]
       }
     }

3. Forward result to backend application server
   POST https://app.internal/api/biometric/enroll
   → {
       "employee_id": "198501012010011001",
       "finger_index": 2,
       "fmd_format": "ISO_19794_2_2005",
       "samples": [
         { "fmd_base64": "Rk1SAA...", "quality": 87 },
         { "fmd_base64": "Rk1SAB...", "quality": 91 },
         { "fmd_base64": "Rk1SAC...", "quality": 82 },
         { "fmd_base64": "Rk1SAD...", "quality": 89 }
       ]
     }

4. To cancel at any point during capture:
   DELETE /api/v1/capture
   ← { "success": true, "data": { "message": "Capture session cancelled." } }

SDK Feature Coverage

SDK Function	Module	Purpose
`dpfpdd_init()`	`fingerprint_server.c`	Initialise the DPFPDD subsystem
`dpfpdd_query_devices()`	`fingerprint_selection.c`	Enumerate all connected readers
`dpfpdd_open()`	`fingerprint_selection.c`	Open a reader device handle
`dpfpdd_get_device_capabilities()`	`fingerprint_selection.c`	Retrieve DPI and supported formats
`dpfpdd_capture()`	`fingerprint_capture.c`	Acquire a raw FID image from the sensor
`dpfpdd_cancel()`	`fingerprint_capture.c`	Abort an in-progress capture via signal
`dpfpdd_close()`	`fingerprint_server.c`	Close an open reader handle
`dpfpdd_exit()`	`fingerprint_server.c`	Shut down the DPFPDD subsystem
`dpfj_create_fmd_from_fid()`	`fingerprint_capture.c`	Extract ISO/IEC 19794-2 FMD template
`dpfj_get_fid_quality()`	`fingerprint_capture.c`	Score image quality (0–100)

Production Deployment

To run the microservice as a managed system service:

# Install the compiled binary
sudo cp -r finger /opt/Crossmatch/urusdk-linux/Linux/

# Install and enable the systemd unit
sudo cp systemd/digitalpersona-fingerprint.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable digitalpersona-fingerprint.service
sudo systemctl start digitalpersona-fingerprint.service

# Verify status
sudo systemctl status digitalpersona-fingerprint.service

# Stream live logs
sudo journalctl -u digitalpersona-fingerprint.service -f

License and Compliance

The DigitalPersona / Crossmatch U.are.U SDK binaries, shared objects, and associated headers are proprietary software owned by Crossmatch Technologies, Inc. and HID Global Corporation. All SDK components are subject to the terms of the End-User License Agreement included at sdk/sdk/docs/EULA_SDK.txt.

The microservice source code (finger/) is the work of project contributors and is governed by the terms agreed upon within the host organisation.

Navigation Menu

Repository navigation

About

Repository files navigation

DigitalPersona U.are.U SDK — Fingerprint Microservice for Linux

Table of Contents

Overview

Key Capabilities

Supported Hardware

Repository Structure

Quick Start

Prerequisites

Configure Libraries and Udev Rules

Build and Run

REST API Reference

Endpoint Summary

GET /api/v1/device

GET /api/v1/device/info

POST /api/v1/capture

POST /api/v1/enrollment

DELETE /api/v1/capture

Response Envelope

Success

Error

HTTP Status Codes

Enrollment Session Flow

SDK Feature Coverage

Production Deployment

License and Compliance

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Crossmatch/urusdk-linux		Crossmatch/urusdk-linux
finger		finger
sdk		sdk
systemd		systemd
.gitignore		.gitignore
INSTALLATION.md		INSTALLATION.md
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

DigitalPersona U.are.U SDK — Fingerprint Microservice for Linux

Table of Contents

Overview

Key Capabilities

Supported Hardware

Repository Structure

Quick Start

Prerequisites

Configure Libraries and Udev Rules

Build and Run

REST API Reference

Endpoint Summary

GET /api/v1/device

GET /api/v1/device/info

POST /api/v1/capture

POST /api/v1/enrollment

DELETE /api/v1/capture

Response Envelope

Success

Error

HTTP Status Codes

Enrollment Session Flow

SDK Feature Coverage

Production Deployment

License and Compliance

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages