aqasemi / pyzkfp

A Python wrapper library for ZKFinger. This library supports ZKTeco fingerprint scanners, SLK20R and ZK series, including ZK9500, ZK6500, ZK8500R.

pyzkfp

Overview

This is a python wrapper library of the ZKTeco SDK.

Compatibility

This library can connect to SLK20R and ZK series, including ZK9500, ZK6500, ZK8500R devices.

Installation

• On linux and MacOS: you should have a .NET runtime (or Mono) installed.
• You have to first install the ZKFinger SDK from the offical website here
• Then install this library via pip:

  pip install pyzkfp

Features

• Initialize and interact with ZKFinger Reader devices.
• Capture fingerprint images.
• Perform fingerprint 1:1 comparisons.
• Perform fingerprint 1:N comparisons.
• Show captured fingerprints (reuqires Pillow).
• Register/Delete fingerprints to and from the device's DB.
• Identify users' fingerprints.
• Light & Beep control functions.

Usage

Here's a simple example of how to use this library:

Initialize the ZKFP2 class and open the device

from pyzkfp import ZKFP2


zkfp2 = ZKFP2()
zkfp2.Init() # Initialize the ZKFP2 class

# Get device count and open first device
device_count = zkfp2.GetDeviceCount()
print(f"{device_count} devices found")
zkfp2.OpenDevice(0) # connect to the first device

Capture a fingerprint

while True:
    capture = zkfp2.AcquireFingerprint()
    if capture:
        # Implement your logic here
        break

Perform a 1:N comparison

tmp, img = capture
fingerprint_id, score = zkfp2.DBIdentify(tmp)

Perform a 1:1 comparison

Usually used to make sure the same finger is scanned throughout the fingerprint registration process.

res = zkfp2.DBMatch(template1, template2) # returns 1 if match, 0 if not

Register a fingerprint

In order to register a fingerprint, we must collect a bunch of (ideally 3) fingerprints of the same finger. And then we can merge them into one template and store it in the device's database.

templates = []
for i in range(3):
    while True:
        capture = zkfp2.AcquireFingerprint()
        if capture:
            print('fingerprint captured')
            tmp, img = capture
            templates.append(tmp)
            break
regTemp, regTempLen = zkfp2.DBMerge(*templates)

# Store the template in the device's database
finger_id = 1 # The id of the finger to be registered
zkfp2.DBAdd(finger_id, regTemp)

Storing and Loading Templates from an External Database for Future Use

Given that the device's memory clears upon shutdown, this step is crucial for preserving data. You have the option to store regTemp (the final result of the the three merged templates) in your preferred database to retrieve them for later use. The segment of code responsible for loading the registered templates from the database to the device's memory should be run after the device's initialization. Here is a simple way to do it.

members = ... # load members' regTemp and their corresponding fingerprint_id from your database.

for member in members:
    fid, temp = member
    zkfp2.DBAdd(fid, temp)
    ...  

To display a fingerprint

tmp, img = capture
zkfp2.show_image(img) # requires Pillow lib

To turn on/off the light

zkfp2.Light('green') # green/red/white

Terminate the device and release resources

zkfp2.Terminate()

For more detailed usage instructions, please refer to the example folder (WIP).

Support My Work

If you found this project useful, please hire a private investigator to legally blackmail ZKTeco's dev team, as this would really help spread the good word of this repository.

pyzkfp's Issues

failed to use the pyzkfp library

hello thank you for the pyzkfp library but I am facing a few issues. When I tried using the library i get this error --Failed to create a default .NET runtime, which would
have been "mono" on this system. Either install a
compatible runtime or configure it explicitly via
set_runtime or the PYTHONNET_* environment variables
(see set_runtime_from_env)--
Am I supposed to first install some dependencies before installing pyzkfp if so please state them in the documentation. Am running python 3.11
thank you

Storing data

Hello! sorry to ask but could you help me on how to store the regtemp data for later use? I am having issues on how handle it.

Thanks in advance!

Code to identify finger prints ?

First of all great work ! Do you have any code samples to idenitfy existing fingerprints and validate against them ?

pyinstaller issues

Hello! I hope you are doing great. I write to you through this issue to know if you have used your library alongside pyinstaller?
I have my source code running without issues but I need to make it distributable. Pyinstaller has been my goto for some time but I cant make it work with pyzkfp.
When I run the exe file I get the issue System.IO.FileNotFoundException. File or assembly could not be loaded 'libzkfpcsharp'...

work with external databases

Hello dear developer

How can I use this library in external databases like PostgreSql, SQLite? I am going to save the temp and identify it in an external database. Could you give me an example?

Odoo integrate fingerprint scanner ZK9500

Hello esteemed developer,

I am integrating a fingerprint scanner with Odoo 16. Since Odoo 16 itself cannot interact directly with the fingerprint scanner, I have decided to implement a Flask application that listens to HTTP requests. In the scenario where I want to compare two fingerprints, one fingerprint is captured from the scanner, while the other is received along with an HTTP request in base64 format. However, when I start comparing them, I always receive a message that the fingerprints do not match. Here is my code:

@app.route('/identify', methods=['POST'])
def identify():
try:
device_count = zkfp2.GetDeviceCount()
if device_count > 0:
zkfp2.OpenDevice(0)
start_time = time.time()
while True:
zkfp2.Light('green')
time.sleep(0.09)
capture = zkfp2.AcquireFingerprint()
if capture:
fingerprint_captured_template = capture[0]
data = request.json
fingerprint_to_compare_base64 = data.get('fingerprint_base64')
fingerprint_to_compare = base64.b64decode(fingerprint_to_compare_base64)
match_score = zkfp2.DBMatch(fingerprint_captured_template, fingerprint_to_compare)
if match_score > 0:
return jsonify({"message": "Fingerprint matched", "score": match_score})
else:
return jsonify({"message": "Fingerprint did not match", "score": match_score})
break
if time.time() - start_time > 10:
zkfp2.CloseDevice()
return jsonify({"message": "Fingerprint scanning timeout"})
break
zkfp2.CloseDevice()
else:
return jsonify({"message": "No device found"}), 500
except Exception as e:
return jsonify({"message": str(e)}), 500
Could you please advise on how to properly compare them and why my comparison is not working correctly?

DBmatch not working for me

Hi! I have a zk9500 device and I work with python, so I came across your library. I need to save my fingerprints in the database and get them back. I register the fingerprint through DBmerge and put it in my database (for emulation, I just use writing bytes next to it in a file). Next, I want to compare the fingerprint in the database with the attached finger and the DBmatch function shows that the fingerprint in the database does not match the attached one. I am attaching a simple code of my actions for understanding. What am I doing wrong? simple_example

DBmatch returning something like score, not 1 or 0

Hi, I spent a lot of time to understand why my application does not recognize my finger through DBmatch, it turned out that DBmatch does not return 1 or 0. But something similar to the comparison score from 0 to 1000, as I understood. But this score behaves quite randomly and sometimes gives out 300, sometimes 800, if i apply the same finger in the same way

Image display

Hello!
I am trying to use the img obtained after the capture whih is a bytes object. But I can't manage to transform it into an image. I am trying with io.BytesIO and keep getting the following error.
UnidentifiedImageError: cannot identify image file

If you can help me with this I would appreciate it enormously.

Thank you in advance!