How Horilla HRMS Connects with ZKTeco Devices Using the ZK (pyzk) Package

In every HR system, biometric attendance devices play a crucial role in automating employee tracking. Applications like Horilla HRMS integrate with ZKTeco biometric devices to fetch attendance logs and process them into meaningful workforce data, such as check-in, check-out, and working hours.

In this blog, we’ll walk through a simple technical overview of how Horilla HRMS connects with ZKTeco devices using the Python-based ZK package (commonly known as pyzk).

Understanding the ZKTeco Device Communication

ZKTeco biometric devices (fingerprint, face recognition, RFID, etc.) typically communicate over a network using a proprietary protocol. Most devices expose connectivity via:

• IP Address (LAN connection)
• Port (default: 4370)
• Communication password (optional)

Instead of using official SDKs, developers often rely on open-source libraries like pyzk, which simplify communication with these devices. The pyzk library is an unofficial Python library that allows direct interaction with ZKTeco devices without needing to understand the underlying protocol.

Installing the ZK (pyzk) Package

To start integrating Horilla with a biometric device, the first step is installing the package:

pip install pyzk

This package provides a simple API to connect, read users, and fetch attendance logs from the device.

Basic Connection Flow

At a high level, Horilla follows this workflow:

• Connect to the device
• Disable the device temporarily
• Fetch attendance logs
• Process and store data
• Enable the device again

Here is a minimal example of connecting to a ZKTeco device:

from zk import ZK

zk = ZK('<ip_address>', port=4370, timeout=5)

conn = zk.connect()
conn.disable_device()

logs = conn.get_attendance()

for log in logs:
    print(log.user_id, log.timestamp)

conn.enable_device()
conn.disconnect()

The ZK class acts as the main interface to the device, allowing operations like connecting, fetching users, and reading attendance records.

How Horilla Uses This Integration

In Horilla HRMS, this process is extended into a structured workflow.

1. Device Configuration

In the admin panel, the device details are stored:

• Device IP
• Port
• Timeout
• Password (if any)

This allows multiple devices across locations to be configured.

2. Scheduled Data Sync

Horilla typically uses background jobs to periodically fetch logs from devices.

This ensures:

• Real-time or near real-time attendance tracking
• No manual data import

3. Attendance Data Processing

Raw logs from ZKTeco devices usually contain:

• User ID
• Timestamp
• Punch type (optional)

Horilla processes this data into:

• Check-in (IN)
• Check-out (OUT)
• Total working hours
• Attendance status (Present, Absent, Missing, etc.)

This transformation is essential because devices only store raw punch events.

4. Employee Mapping

Each device user ID is mapped to an employee in Horilla.

Example:

Device employee code: 101 → Employee: John Doe with badge ID 101

This mapping ensures that logs are correctly assigned.

5. Data Storage

Processed data is stored in models such as:

• Attendance records
• Daily paired activities

This enables reporting, payroll integration, and analytics.

Important Technical Considerations

• Network Configuration
• The device and server must be on the same network
• Port 4370 must be accessible
• Firewall rules should allow communication
• Device Compatibility

Not all ZKTeco devices behave the same way. Some use different protocols (UDP/TCP), and compatibility with pyzk may vary.

Integrating ZKTeco devices with Horilla HRMS using the ZK (pyzk) package is a practical and efficient way to automate attendance tracking. The library abstracts complex device communication and provides a simple Python interface to fetch and manage biometric data.

By combining this with Django-based backend logic, Horilla transforms raw biometric logs into meaningful HR insights such as attendance, working hours, and employee productivity.

This integration forms the backbone of modern HR automation systems, reducing manual effort and improving accuracy across organizations.