Biometric Fetch 🚀

The ultimate universal wrapper for fetching attendance & user data from 50+ biometric devices.
(ZKTeco, eSSL, SecureEye, Hikvision, Suprema, IDEMIA, Nitgen, and more!)

What is Biometric Fetch?

Historically, interacting with biometric machines requires downloading confusing vendor SDKs, dealing with messy DLL segmentation faults, studying raw Socket connections, or writing massive API XML wrappers.

biometric-fetch solves this by acting as a universal "Factory Pattern". You write 3 lines of Python code using one standard interface, and we automatically handle the underlying protocol (TCP/IP, REST API, or SDK Binding) securely under the hood.

We even natively convert all raw device logs directly into beautiful Pandas DataFrames! 📊

⚙️ Installation

Install effortlessly via PyPI:

pip install biometric-fetch

(This automatically installs our dependencies: pyzk, pandas, requests, and openpyxl)

⚡ Quick Start

1. Connecting via TCP/IP (ZKTeco, eSSL, Secureye, etc)

The most common biometric devices run on port 4370.

from biometric_fetch import BiometricDevice

# The factory seamlessly invokes the TCP/IP backend
device = BiometricDevice(brand="zkteco", ip="192.168.1.201")
device.connect()

# Fetch array of User Objects
users = device.get_users()
print(users)

2. Outputting as Pandas DataFrames! 🐼

Stop looping through messy strings. Enable as_dataframe=True to immediately deploy data analytics.

df = device.get_attendance(as_dataframe=True)

# You now have a clean, formatted table of all punches
print(df.head())
# df.to_csv("attendance_logs.csv") # One-line export!

🔌 Advanced Protocols Supported

The wrapper natively understands completely different networking protocols under the exact same class commands!

Accessing REST APIs (Hikvision, Suprema)

Many modern IP access control panels require complex HTTP Digest Auth and Token sessions. We map that directly:

# Hikvision uses ISAPI JSON structures under the hood
hik_device = BiometricDevice(brand="hikvision", ip="192.168.1.100", api_key="admin_password123!")
hik_device.connect()

attendance_df = hik_device.get_attendance(as_dataframe=True)

Accessing C-SDK DLLs (Nitgen, IDEMIA)

Requires physical .dll loading? We use ctypes.WinDLL to bind memory safely without Segment Faulting your Python instance.

# Natively looks for C:\Windows\System32\NBioBSP.dll or SecuAPI.dll
sdk_device = BiometricDevice(brand="nitgen", ip="192.168.1.50")

💾 Offline USB Extraction

If a network cable breaks, staff pull the data via Pen Drive. biometric-fetch parses raw machine outputs natively:

from biometric_fetch import usb

# Point it to your USB folder. It automatically hunts for .csv and .dat logs!
usb_logs = usb.read_usb("D:/Biometric_Exports", as_dataframe=True)
print(usb_logs)

Enterprise Ready (Zero-Crash Guarantee)

This library is built for stable deployment in HR environments.

• Fail-Safe: If a device IP unexpectedly goes offline, your application won't suffer a stack-trace crash. The library safely catches the timeout and returns a standard Empty DataFrame!
• Semantic Logging: No messy print() statements. Customize the silent logging module so you can record device drops behind the scenes.

🤝 Supported Brands Roadmap

License: MIT Authors: Rishabh & Shreya