Crate zkteco 

zkteco

A pure-Rust, synchronous client for ZKTeco biometric attendance and access-control terminals (fingerprint / RFID / face devices that speak the ZK TCP/UDP protocol on port 4370).

This crate is a faithful port of the Python library pyzk. It supports connecting and authenticating, reading and writing users, reading attendance logs, fingerprint templates, enrollment, live capture, and device control.

Quick start

use zkteco::Zk;

fn main() -> zkteco::ZkResult<()> {
    // Build and connect (TCP by default, port 4370).
    let mut zk = Zk::builder("192.168.1.201").build();
    zk.connect()?;

    // Best practice: disable the device during bulk reads, then re-enable.
    zk.disable_device()?;
    let users = zk.get_users()?;
    let logs = zk.get_attendance()?;
    zk.enable_device()?;

    println!("{} users, {} attendance records", users.len(), logs.len());
    zk.disconnect()?;
    Ok(())
}

Live capture

Zk::live_capture returns an iterator of attendance punches as they happen. Timeout “ticks” (Ok(None)) let you check a stop flag:

use std::time::Duration;
use zkteco::Zk;

let mut zk = Zk::builder("192.168.1.201").build();
zk.connect()?;
let mut capture = zk.live_capture(Duration::from_secs(10))?;
let stop = capture.stop_handle();
for event in &mut capture {
    match event? {
        Some(att) => println!("punch: {att}"),
        None => { /* timeout tick — poll your own stop condition here */ }
    }
}

Using from async code

All calls block. Inside an async runtime, run them on a blocking thread, e.g. tokio::task::spawn_blocking(move || { zk.connect()?; zk.get_users() }).

Compatibility & notes

• Works over TCP (default) and UDP (force_udp). The newer 72-byte (“ZK8”) and older 28-byte (“ZK6”) user record layouts are auto-detected.
• Strings are encoded/decoded as UTF-8 (lossy). Legacy code pages are not supported, keeping the dependency footprint to just chrono.
• Timestamps are returned as chrono::NaiveDateTime in the device’s local time (the device has no timezone concept).

Modules

constants

Protocol command codes and flags used by ZKTeco terminals.

Structs

Attendance

A single attendance punch read from the device.

DeviceSizes

Memory / record counters reported by the device (see Zk::read_sizes).

Finger

A fingerprint template belonging to a user.

LiveCapture

Real-time attendance capture session (see Zk::live_capture).

NetworkParams

Network parameters reported by the device (see Zk::get_network_params).

User

A user enrolled on the device.

Zk

A connection to a single ZKTeco terminal.

ZkBuilder

Builder for Zk. Created via Zk::builder.

ZkHelper

Lightweight reachability helper for a device address.

Enums

ZkError

Errors that can occur while talking to a ZKTeco device.

Constants

USER_ADMIN

Administrator privilege level.

USER_DEFAULT

Standard (non-admin) privilege level.

Type Aliases

ZkResult

Convenience alias for results returned by this crate.