Struct Zk 

pub struct Zk { /* private fields */ }

A connection to a single ZKTeco terminal.

Construct one with Zk::builder, then connect:

use zkteco::Zk;
let mut zk = Zk::builder("192.168.1.201").build();
zk.connect()?;
for user in zk.get_users()? {
    println!("{user}");
}
zk.disconnect()?;

Implementations

impl Zk

pub fn builder(ip: impl Into<String>) -> ZkBuilder

Begin configuring a connection to ip.

Examples found in repository

examples/get_attendance.rs (line 13)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_attendance <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(15))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;
    let logs = zk.get_attendance()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} records", logs.len());
    for a in logs {
        println!(
            "  {} user={} status={} {}",
            a.timestamp,
            a.user_id,
            a.status,
            a.punch_label()
        );
    }
    Ok(())
}

examples/get_users.rs (line 13)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_users <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    // Disable user interaction while we read in bulk, then restore it.
    zk.disable_device()?;
    let users = zk.get_users()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} users", users.len());
    for u in users {
        println!(
            "  uid={:<4} id={:<10} name={:<20} priv={} card={}",
            u.uid, u.user_id, u.name, u.privilege, u.card
        );
    }
    Ok(())
}

examples/device_info.rs (line 11)

fn main() -> zkteco::ZkResult<()> {
    let (ip, port) = parse_args();

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        // Many devices live on networks that block ICMP; skip the ping probe.
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("connected: {zk}");

    println!("firmware:    {}", zk.get_firmware_version()?);
    println!("serial:      {}", zk.get_serialnumber()?);
    println!("platform:    {}", zk.get_platform()?);
    println!("device name: {}", zk.get_device_name()?);
    println!("mac:         {}", zk.get_mac().unwrap_or_default());
    println!("time:        {}", zk.get_time()?);

    let sizes = zk.read_sizes()?;
    println!("sizes:       {sizes:?}");

    zk.disconnect()?;
    Ok(())
}

examples/live_capture.rs (line 14)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: live_capture <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(30))
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("listening for punches (Ctrl-C to stop)...");

    let mut capture = zk.live_capture(Duration::from_secs(10))?;

    // Stop the loop on Ctrl-C by flipping the shared stop flag.
    let stop = capture.stop_handle();
    ctrlc_set(move || stop.store(true, Ordering::SeqCst));

    for event in &mut capture {
        match event? {
            Some(att) => println!("punch: {att}"),
            None => println!("(tick — no punch in the last interval)"),
        }
    }
    println!("stopped.");
    Ok(())
}

examples/set_delete_user.rs (line 15)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: set_delete_user <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;

    // Populate next_uid / next_user_id by reading current users first.
    let _ = zk.get_users()?;

    // uid = 0 asks the crate to assign the next free uid / user_id.
    let user = User::new(0, "Test User", USER_DEFAULT, "1234", "", "", 0);
    zk.set_user(&user)?;
    println!("created a user; uid counter now {}", zk.next_uid());

    // Delete by user_id (uid = 0 triggers a lookup).
    let created = zk.get_users()?;
    if let Some(last) = created.iter().max_by_key(|u| u.uid) {
        println!("deleting uid={} id={}", last.uid, last.user_id);
        zk.delete_user(last.uid, &last.user_id)?;
    }

    zk.enable_device()?;
    zk.disconnect()?;
    Ok(())
}

pub fn is_connected(&self) -> bool

true while a session is open.

pub fn is_enabled(&self) -> bool

true while the device is enabled (accepting user interaction).

pub fn next_uid(&self) -> u16

The next user index this crate would auto-assign (populated by get_users).

Examples found in repository

examples/set_delete_user.rs (line 30)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: set_delete_user <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;

    // Populate next_uid / next_user_id by reading current users first.
    let _ = zk.get_users()?;

    // uid = 0 asks the crate to assign the next free uid / user_id.
    let user = User::new(0, "Test User", USER_DEFAULT, "1234", "", "", 0);
    zk.set_user(&user)?;
    println!("created a user; uid counter now {}", zk.next_uid());

    // Delete by user_id (uid = 0 triggers a lookup).
    let created = zk.get_users()?;
    if let Some(last) = created.iter().max_by_key(|u| u.uid) {
        println!("deleting uid={} id={}", last.uid, last.user_id);
        zk.delete_user(last.uid, &last.user_id)?;
    }

    zk.enable_device()?;
    zk.disconnect()?;
    Ok(())
}

pub fn next_user_id(&self) -> &str

The next free user-id string (populated by get_users).

pub fn sizes(&self) -> DeviceSizes

The most recent capacity snapshot (see read_sizes).

pub fn connect(&mut self) -> ZkResult<()>

Open the socket, start a session, and authenticate if required.

Examples found in repository

examples/get_attendance.rs (line 19)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_attendance <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(15))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;
    let logs = zk.get_attendance()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} records", logs.len());
    for a in logs {
        println!(
            "  {} user={} status={} {}",
            a.timestamp,
            a.user_id,
            a.status,
            a.punch_label()
        );
    }
    Ok(())
}

examples/get_users.rs (line 19)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_users <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    // Disable user interaction while we read in bulk, then restore it.
    zk.disable_device()?;
    let users = zk.get_users()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} users", users.len());
    for u in users {
        println!(
            "  uid={:<4} id={:<10} name={:<20} priv={} card={}",
            u.uid, u.user_id, u.name, u.privilege, u.card
        );
    }
    Ok(())
}

examples/device_info.rs (line 18)

fn main() -> zkteco::ZkResult<()> {
    let (ip, port) = parse_args();

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        // Many devices live on networks that block ICMP; skip the ping probe.
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("connected: {zk}");

    println!("firmware:    {}", zk.get_firmware_version()?);
    println!("serial:      {}", zk.get_serialnumber()?);
    println!("platform:    {}", zk.get_platform()?);
    println!("device name: {}", zk.get_device_name()?);
    println!("mac:         {}", zk.get_mac().unwrap_or_default());
    println!("time:        {}", zk.get_time()?);

    let sizes = zk.read_sizes()?;
    println!("sizes:       {sizes:?}");

    zk.disconnect()?;
    Ok(())
}

examples/live_capture.rs (line 20)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: live_capture <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(30))
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("listening for punches (Ctrl-C to stop)...");

    let mut capture = zk.live_capture(Duration::from_secs(10))?;

    // Stop the loop on Ctrl-C by flipping the shared stop flag.
    let stop = capture.stop_handle();
    ctrlc_set(move || stop.store(true, Ordering::SeqCst));

    for event in &mut capture {
        match event? {
            Some(att) => println!("punch: {att}"),
            None => println!("(tick — no punch in the last interval)"),
        }
    }
    println!("stopped.");
    Ok(())
}

examples/set_delete_user.rs (line 21)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: set_delete_user <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;

    // Populate next_uid / next_user_id by reading current users first.
    let _ = zk.get_users()?;

    // uid = 0 asks the crate to assign the next free uid / user_id.
    let user = User::new(0, "Test User", USER_DEFAULT, "1234", "", "", 0);
    zk.set_user(&user)?;
    println!("created a user; uid counter now {}", zk.next_uid());

    // Delete by user_id (uid = 0 triggers a lookup).
    let created = zk.get_users()?;
    if let Some(last) = created.iter().max_by_key(|u| u.uid) {
        println!("deleting uid={} id={}", last.uid, last.user_id);
        zk.delete_user(last.uid, &last.user_id)?;
    }

    zk.enable_device()?;
    zk.disconnect()?;
    Ok(())
}

pub fn disconnect(&mut self) -> ZkResult<()>

Close the session and the socket.

Examples found in repository

examples/get_attendance.rs (line 23)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_attendance <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(15))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;
    let logs = zk.get_attendance()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} records", logs.len());
    for a in logs {
        println!(
            "  {} user={} status={} {}",
            a.timestamp,
            a.user_id,
            a.status,
            a.punch_label()
        );
    }
    Ok(())
}

examples/get_users.rs (line 24)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_users <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    // Disable user interaction while we read in bulk, then restore it.
    zk.disable_device()?;
    let users = zk.get_users()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} users", users.len());
    for u in users {
        println!(
            "  uid={:<4} id={:<10} name={:<20} priv={} card={}",
            u.uid, u.user_id, u.name, u.privilege, u.card
        );
    }
    Ok(())
}

examples/device_info.rs (line 31)

fn main() -> zkteco::ZkResult<()> {
    let (ip, port) = parse_args();

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        // Many devices live on networks that block ICMP; skip the ping probe.
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("connected: {zk}");

    println!("firmware:    {}", zk.get_firmware_version()?);
    println!("serial:      {}", zk.get_serialnumber()?);
    println!("platform:    {}", zk.get_platform()?);
    println!("device name: {}", zk.get_device_name()?);
    println!("mac:         {}", zk.get_mac().unwrap_or_default());
    println!("time:        {}", zk.get_time()?);

    let sizes = zk.read_sizes()?;
    println!("sizes:       {sizes:?}");

    zk.disconnect()?;
    Ok(())
}

examples/set_delete_user.rs (line 40)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: set_delete_user <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;

    // Populate next_uid / next_user_id by reading current users first.
    let _ = zk.get_users()?;

    // uid = 0 asks the crate to assign the next free uid / user_id.
    let user = User::new(0, "Test User", USER_DEFAULT, "1234", "", "", 0);
    zk.set_user(&user)?;
    println!("created a user; uid counter now {}", zk.next_uid());

    // Delete by user_id (uid = 0 triggers a lookup).
    let created = zk.get_users()?;
    if let Some(last) = created.iter().max_by_key(|u| u.uid) {
        println!("deleting uid={} id={}", last.uid, last.user_id);
        zk.delete_user(last.uid, &last.user_id)?;
    }

    zk.enable_device()?;
    zk.disconnect()?;
    Ok(())
}

pub fn enable_device(&mut self) -> ZkResult<()>

Re-enable the device (allow user interaction).

Examples found in repository

examples/get_attendance.rs (line 22)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_attendance <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(15))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;
    let logs = zk.get_attendance()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} records", logs.len());
    for a in logs {
        println!(
            "  {} user={} status={} {}",
            a.timestamp,
            a.user_id,
            a.status,
            a.punch_label()
        );
    }
    Ok(())
}

examples/get_users.rs (line 23)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_users <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    // Disable user interaction while we read in bulk, then restore it.
    zk.disable_device()?;
    let users = zk.get_users()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} users", users.len());
    for u in users {
        println!(
            "  uid={:<4} id={:<10} name={:<20} priv={} card={}",
            u.uid, u.user_id, u.name, u.privilege, u.card
        );
    }
    Ok(())
}

examples/set_delete_user.rs (line 39)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: set_delete_user <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;

    // Populate next_uid / next_user_id by reading current users first.
    let _ = zk.get_users()?;

    // uid = 0 asks the crate to assign the next free uid / user_id.
    let user = User::new(0, "Test User", USER_DEFAULT, "1234", "", "", 0);
    zk.set_user(&user)?;
    println!("created a user; uid counter now {}", zk.next_uid());

    // Delete by user_id (uid = 0 triggers a lookup).
    let created = zk.get_users()?;
    if let Some(last) = created.iter().max_by_key(|u| u.uid) {
        println!("deleting uid={} id={}", last.uid, last.user_id);
        zk.delete_user(last.uid, &last.user_id)?;
    }

    zk.enable_device()?;
    zk.disconnect()?;
    Ok(())
}

pub fn disable_device(&mut self) -> ZkResult<()>

Disable the device (lock out users during bulk operations).

Examples found in repository

examples/get_attendance.rs (line 20)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_attendance <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(15))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;
    let logs = zk.get_attendance()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} records", logs.len());
    for a in logs {
        println!(
            "  {} user={} status={} {}",
            a.timestamp,
            a.user_id,
            a.status,
            a.punch_label()
        );
    }
    Ok(())
}

examples/get_users.rs (line 21)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_users <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    // Disable user interaction while we read in bulk, then restore it.
    zk.disable_device()?;
    let users = zk.get_users()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} users", users.len());
    for u in users {
        println!(
            "  uid={:<4} id={:<10} name={:<20} priv={} card={}",
            u.uid, u.user_id, u.name, u.privilege, u.card
        );
    }
    Ok(())
}

examples/set_delete_user.rs (line 22)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: set_delete_user <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;

    // Populate next_uid / next_user_id by reading current users first.
    let _ = zk.get_users()?;

    // uid = 0 asks the crate to assign the next free uid / user_id.
    let user = User::new(0, "Test User", USER_DEFAULT, "1234", "", "", 0);
    zk.set_user(&user)?;
    println!("created a user; uid counter now {}", zk.next_uid());

    // Delete by user_id (uid = 0 triggers a lookup).
    let created = zk.get_users()?;
    if let Some(last) = created.iter().max_by_key(|u| u.uid) {
        println!("deleting uid={} id={}", last.uid, last.user_id);
        zk.delete_user(last.uid, &last.user_id)?;
    }

    zk.enable_device()?;
    zk.disconnect()?;
    Ok(())
}

pub fn get_firmware_version(&mut self) -> ZkResult<String>

Firmware version string.

Examples found in repository

examples/device_info.rs (line 21)

fn main() -> zkteco::ZkResult<()> {
    let (ip, port) = parse_args();

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        // Many devices live on networks that block ICMP; skip the ping probe.
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("connected: {zk}");

    println!("firmware:    {}", zk.get_firmware_version()?);
    println!("serial:      {}", zk.get_serialnumber()?);
    println!("platform:    {}", zk.get_platform()?);
    println!("device name: {}", zk.get_device_name()?);
    println!("mac:         {}", zk.get_mac().unwrap_or_default());
    println!("time:        {}", zk.get_time()?);

    let sizes = zk.read_sizes()?;
    println!("sizes:       {sizes:?}");

    zk.disconnect()?;
    Ok(())
}

pub fn get_serialnumber(&mut self) -> ZkResult<String>

Device serial number.

Examples found in repository

examples/device_info.rs (line 22)

fn main() -> zkteco::ZkResult<()> {
    let (ip, port) = parse_args();

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        // Many devices live on networks that block ICMP; skip the ping probe.
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("connected: {zk}");

    println!("firmware:    {}", zk.get_firmware_version()?);
    println!("serial:      {}", zk.get_serialnumber()?);
    println!("platform:    {}", zk.get_platform()?);
    println!("device name: {}", zk.get_device_name()?);
    println!("mac:         {}", zk.get_mac().unwrap_or_default());
    println!("time:        {}", zk.get_time()?);

    let sizes = zk.read_sizes()?;
    println!("sizes:       {sizes:?}");

    zk.disconnect()?;
    Ok(())
}

pub fn get_platform(&mut self) -> ZkResult<String>

Platform name.

Examples found in repository

examples/device_info.rs (line 23)

fn main() -> zkteco::ZkResult<()> {
    let (ip, port) = parse_args();

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        // Many devices live on networks that block ICMP; skip the ping probe.
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("connected: {zk}");

    println!("firmware:    {}", zk.get_firmware_version()?);
    println!("serial:      {}", zk.get_serialnumber()?);
    println!("platform:    {}", zk.get_platform()?);
    println!("device name: {}", zk.get_device_name()?);
    println!("mac:         {}", zk.get_mac().unwrap_or_default());
    println!("time:        {}", zk.get_time()?);

    let sizes = zk.read_sizes()?;
    println!("sizes:       {sizes:?}");

    zk.disconnect()?;
    Ok(())
}

pub fn get_mac(&mut self) -> ZkResult<String>

MAC address.

Examples found in repository

examples/device_info.rs (line 25)

fn main() -> zkteco::ZkResult<()> {
    let (ip, port) = parse_args();

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        // Many devices live on networks that block ICMP; skip the ping probe.
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("connected: {zk}");

    println!("firmware:    {}", zk.get_firmware_version()?);
    println!("serial:      {}", zk.get_serialnumber()?);
    println!("platform:    {}", zk.get_platform()?);
    println!("device name: {}", zk.get_device_name()?);
    println!("mac:         {}", zk.get_mac().unwrap_or_default());
    println!("time:        {}", zk.get_time()?);

    let sizes = zk.read_sizes()?;
    println!("sizes:       {sizes:?}");

    zk.disconnect()?;
    Ok(())
}

pub fn get_device_name(&mut self) -> ZkResult<String>

Device name (empty string if unavailable).

Examples found in repository

examples/device_info.rs (line 24)

fn main() -> zkteco::ZkResult<()> {
    let (ip, port) = parse_args();

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        // Many devices live on networks that block ICMP; skip the ping probe.
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("connected: {zk}");

    println!("firmware:    {}", zk.get_firmware_version()?);
    println!("serial:      {}", zk.get_serialnumber()?);
    println!("platform:    {}", zk.get_platform()?);
    println!("device name: {}", zk.get_device_name()?);
    println!("mac:         {}", zk.get_mac().unwrap_or_default());
    println!("time:        {}", zk.get_time()?);

    let sizes = zk.read_sizes()?;
    println!("sizes:       {sizes:?}");

    zk.disconnect()?;
    Ok(())
}

pub fn get_face_version(&mut self) -> ZkResult<Option<u32>>

Face-engine version (0 if none, None if the option is missing).

pub fn get_fp_version(&mut self) -> ZkResult<u32>

Fingerprint algorithm version.

pub fn get_network_params(&mut self) -> ZkResult<NetworkParams>

Read network parameters (IP / mask / gateway).

pub fn get_pin_width(&mut self) -> ZkResult<u8>

Configured user-id (PIN) width in characters.

pub fn read_sizes(&mut self) -> ZkResult<DeviceSizes>

Read device memory / record counters into DeviceSizes (also cached on self, see sizes).

Examples found in repository

examples/device_info.rs (line 28)

fn main() -> zkteco::ZkResult<()> {
    let (ip, port) = parse_args();

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        // Many devices live on networks that block ICMP; skip the ping probe.
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("connected: {zk}");

    println!("firmware:    {}", zk.get_firmware_version()?);
    println!("serial:      {}", zk.get_serialnumber()?);
    println!("platform:    {}", zk.get_platform()?);
    println!("device name: {}", zk.get_device_name()?);
    println!("mac:         {}", zk.get_mac().unwrap_or_default());
    println!("time:        {}", zk.get_time()?);

    let sizes = zk.read_sizes()?;
    println!("sizes:       {sizes:?}");

    zk.disconnect()?;
    Ok(())
}

pub fn get_time(&mut self) -> ZkResult<NaiveDateTime>

Read the device clock.

Examples found in repository

examples/device_info.rs (line 26)

fn main() -> zkteco::ZkResult<()> {
    let (ip, port) = parse_args();

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        // Many devices live on networks that block ICMP; skip the ping probe.
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("connected: {zk}");

    println!("firmware:    {}", zk.get_firmware_version()?);
    println!("serial:      {}", zk.get_serialnumber()?);
    println!("platform:    {}", zk.get_platform()?);
    println!("device name: {}", zk.get_device_name()?);
    println!("mac:         {}", zk.get_mac().unwrap_or_default());
    println!("time:        {}", zk.get_time()?);

    let sizes = zk.read_sizes()?;
    println!("sizes:       {sizes:?}");

    zk.disconnect()?;
    Ok(())
}

pub fn set_time(&mut self, timestamp: NaiveDateTime) -> ZkResult<()>

Set the device clock.

pub fn restart(&mut self) -> ZkResult<()>

Restart the device (ends the session).

pub fn poweroff(&mut self) -> ZkResult<()>

Power the device off (ends the session).

pub fn refresh_data(&mut self) -> ZkResult<()>

Refresh the device’s internal data after writes.

pub fn free_data(&mut self) -> ZkResult<()>

Clear the device’s open data buffer.

pub fn test_voice(&mut self, index: u32) -> ZkResult<bool>

Play a built-in voice prompt / beep by index (see the device manual for the index table). Returns true if accepted.

pub fn unlock(&mut self, seconds: u32) -> ZkResult<()>

Unlock the door for seconds seconds.

pub fn get_lock_state(&mut self) -> ZkResult<bool>

Query the door/lock state. Returns true if the device acknowledges.

pub fn write_lcd(&mut self, line_number: i16, text: &str) -> ZkResult<()>

Write text to a line of the device LCD.

pub fn clear_lcd(&mut self) -> ZkResult<()>

Clear the device LCD.

pub fn reg_event(&mut self, flags: u32) -> ZkResult<()>

Register for real-time events (bitmask of EF_*).

pub fn cancel_capture(&mut self) -> ZkResult<bool>

Cancel an in-progress fingerprint capture.

pub fn verify_user(&mut self) -> ZkResult<()>

Enter verify state (used around enroll / live capture).

pub fn set_sdk_build_1(&mut self) -> ZkResult<bool>

Enable SDK build mode 1 (some devices need this before bulk reads).

pub fn get_users(&mut self) -> ZkResult<Vec<User>>

Read all enrolled users.

Examples found in repository

examples/get_users.rs (line 22)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_users <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    // Disable user interaction while we read in bulk, then restore it.
    zk.disable_device()?;
    let users = zk.get_users()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} users", users.len());
    for u in users {
        println!(
            "  uid={:<4} id={:<10} name={:<20} priv={} card={}",
            u.uid, u.user_id, u.name, u.privilege, u.card
        );
    }
    Ok(())
}

examples/set_delete_user.rs (line 25)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: set_delete_user <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;

    // Populate next_uid / next_user_id by reading current users first.
    let _ = zk.get_users()?;

    // uid = 0 asks the crate to assign the next free uid / user_id.
    let user = User::new(0, "Test User", USER_DEFAULT, "1234", "", "", 0);
    zk.set_user(&user)?;
    println!("created a user; uid counter now {}", zk.next_uid());

    // Delete by user_id (uid = 0 triggers a lookup).
    let created = zk.get_users()?;
    if let Some(last) = created.iter().max_by_key(|u| u.uid) {
        println!("deleting uid={} id={}", last.uid, last.user_id);
        zk.delete_user(last.uid, &last.user_id)?;
    }

    zk.enable_device()?;
    zk.disconnect()?;
    Ok(())
}

pub fn set_user(&mut self, user: &User) -> ZkResult<()>

Create or update a user.

If user.uid is 0, the next free uid / user-id is assigned (call get_users first so the counters are populated).

Examples found in repository

examples/set_delete_user.rs (line 29)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: set_delete_user <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;

    // Populate next_uid / next_user_id by reading current users first.
    let _ = zk.get_users()?;

    // uid = 0 asks the crate to assign the next free uid / user_id.
    let user = User::new(0, "Test User", USER_DEFAULT, "1234", "", "", 0);
    zk.set_user(&user)?;
    println!("created a user; uid counter now {}", zk.next_uid());

    // Delete by user_id (uid = 0 triggers a lookup).
    let created = zk.get_users()?;
    if let Some(last) = created.iter().max_by_key(|u| u.uid) {
        println!("deleting uid={} id={}", last.uid, last.user_id);
        zk.delete_user(last.uid, &last.user_id)?;
    }

    zk.enable_device()?;
    zk.disconnect()?;
    Ok(())
}

pub fn delete_user(&mut self, uid: u16, user_id: &str) -> ZkResult<()>

Delete a user by internal uid. If uid is 0, resolves it from user_id (which requires a get_users lookup).

Examples found in repository

examples/set_delete_user.rs (line 36)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: set_delete_user <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(10))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;

    // Populate next_uid / next_user_id by reading current users first.
    let _ = zk.get_users()?;

    // uid = 0 asks the crate to assign the next free uid / user_id.
    let user = User::new(0, "Test User", USER_DEFAULT, "1234", "", "", 0);
    zk.set_user(&user)?;
    println!("created a user; uid counter now {}", zk.next_uid());

    // Delete by user_id (uid = 0 triggers a lookup).
    let created = zk.get_users()?;
    if let Some(last) = created.iter().max_by_key(|u| u.uid) {
        println!("deleting uid={} id={}", last.uid, last.user_id);
        zk.delete_user(last.uid, &last.user_id)?;
    }

    zk.enable_device()?;
    zk.disconnect()?;
    Ok(())
}

pub fn clear_data(&mut self) -> ZkResult<()>

Clear ALL data on the device (users, attendance, templates).

pub fn get_attendance(&mut self) -> ZkResult<Vec<Attendance>>

Read all attendance records.

Examples found in repository

examples/get_attendance.rs (line 21)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: get_attendance <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(15))
        .omit_ping(true)
        .build();

    zk.connect()?;
    zk.disable_device()?;
    let logs = zk.get_attendance()?;
    zk.enable_device()?;
    zk.disconnect()?;

    println!("{} records", logs.len());
    for a in logs {
        println!(
            "  {} user={} status={} {}",
            a.timestamp,
            a.user_id,
            a.status,
            a.punch_label()
        );
    }
    Ok(())
}

pub fn clear_attendance(&mut self) -> ZkResult<()>

Clear all attendance records.

pub fn get_templates(&mut self) -> ZkResult<Vec<Finger>>

Read all fingerprint templates.

pub fn get_user_template( &mut self, uid: u16, finger_id: u8, ) -> ZkResult<Option<Finger>>

Fetch a single fingerprint template for (uid, finger_id).

pub fn delete_user_template( &mut self, uid: u16, finger_id: u8, user_id: &str, ) -> ZkResult<bool>

Delete a single template. If uid is 0 it is resolved from user_id.

pub fn enroll_user( &mut self, uid: u16, finger_id: u8, user_id: &str, ) -> ZkResult<bool>

Interactively enroll a fingerprint for an existing user.

This puts the device into enrollment mode; the person must press their finger on the sensor (typically three times). Returns true if a template was captured. If user_id is empty it is resolved from uid.

Note: this blocks while waiting for the person to interact with the device (the read timeout is temporarily raised to 60s, matching pyzk).

pub fn save_user_template( &mut self, user: &User, fingers: &[Finger], ) -> ZkResult<()>

Save a user together with their fingerprint templates (high-rate upload).

pub fn save_user_templates( &mut self, items: &[(User, Vec<Finger>)], ) -> ZkResult<()>

Save multiple users and their templates in a single buffered upload.

(pyzk’s HR_save_usertemplates.)

pub fn live_capture( &mut self, poll_timeout: Duration, ) -> ZkResult<LiveCapture<'_>>

Start capturing attendance punches in real time.

Returns a LiveCapture iterator. Each next() yields:

• Some(Ok(Some(att))) — a punch,
• Some(Ok(None)) — a timeout “tick” (lets you poll the stop flag),
• Some(Err(_)) — a fatal error,
• None — the capture was stopped.

poll_timeout controls how often a tick is produced.

Examples found in repository

examples/live_capture.rs (line 23)

fn main() -> zkteco::ZkResult<()> {
    let mut args = std::env::args().skip(1);
    let ip = args.next().expect("usage: live_capture <ip> [port]");
    let port: u16 = args.next().and_then(|p| p.parse().ok()).unwrap_or(4370);

    let mut zk = Zk::builder(ip)
        .port(port)
        .timeout(Duration::from_secs(30))
        .omit_ping(true)
        .build();

    zk.connect()?;
    println!("listening for punches (Ctrl-C to stop)...");

    let mut capture = zk.live_capture(Duration::from_secs(10))?;

    // Stop the loop on Ctrl-C by flipping the shared stop flag.
    let stop = capture.stop_handle();
    ctrlc_set(move || stop.store(true, Ordering::SeqCst));

    for event in &mut capture {
        match event? {
            Some(att) => println!("punch: {att}"),
            None => println!("(tick — no punch in the last interval)"),
        }
    }
    println!("stopped.");
    Ok(())
}

Trait Implementations

impl Display for Zk

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.