flutter_zk 1.0.2

An unofficial library of zksoftware (zkteco family) attendance machine.

flutter_zk

A Flutter plugin to connect and interact with ZKTeco biometric attendance devices over TCP/IP. This package is a Dart implementation inspired by the pyzk Python library.

Features

• Connect to ZKTeco devices.
• Authenticate with a device password.
• Get device information:
  • Firmware Version
  • Serial Number
  • Device Time
  • Platform
  • MAC Address
  • Device Name
  • Face and Fingerprint Algorithm Versions
  • Network Parameters (IP, Subnet Mask, Gateway)
• Manage users:
  • Fetch user data from the device.
  • Add and update users.
  • Delete users.
• Fetch attendance records from the device.
• Control device operations:
  • Enable/Disable device.
  • Restart/Power off device.
  • Refresh data.
  • Unlock doors.
  • Play voice messages.
• Manage data:
  • Clear all data.
  • Clear attendance records.
• Disconnect gracefully.
• Robust error handling.

Platform Support

This package supports the following platforms:

• ✅ Android
• ✅ iOS
• ✅ Windows
• ✅ Linux
• ✅ macOS
• ❌ Web (Not supported - requires direct TCP socket access)

Note: Web platform is intentionally not supported as browsers do not allow direct TCP socket connections for security reasons. This is a limitation of the web platform, not the package.

Getting started

Prerequisites

Ensure your Flutter development environment is set up. Your ZKTeco device must be connected to the same network as your application and must be reachable via its IP address.

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_zk: ^1.0.0 

Then, run flutter pub get in your terminal.

Usage

Here is a basic example of how to use the flutter_zk package.

import 'package:flutter_zk/flutter_zk.dart';
import 'package:flutter_zk/src/utils/logger.dart'; // Import the custom logger

void main() async {
  final zk = ZK('192.168.1.201', port: 4370, password: 0);

  try {
    // Connect to the device
    await zk.connect();
    debugLog('Connected to device.');

    // Get firmware version
    final firmware = await zk.getFirmwareVersion();
    debugLog('Firmware Version: $firmware');

    // Get serial number
    final serial = await zk.getSerialNumber();
    debugLog('Serial Number: $serial');

    // Get all users
    debugLog('Fetching users...');
    final users = await zk.getUsers();
    debugLog('Found ${users.length} users.');
    for (var user in users) {
      debugLog('- UID: ${user.uid}, UserID: ${user.userId}, Name: ${user.name}');
    }

  } catch (e) {
    debugLog('An error occurred: $e', error: e);
  } finally {
    // Always ensure to disconnect
    await zk.disconnect();
    debugLog('Disconnected from device.');
  }
}

API Overview

ZK(String ip, {int port, int password})

Creates a new ZK instance.

• ip: The IP address of the ZKTeco device.
• port: The communication port (default is 4370).
• password: The device's communication password (default is 0).

Core Methods

• Future<void> connect(): Establishes a connection with the device and performs authentication.
• Future<void> disconnect(): Closes the connection to the device.
• Future<String> getFirmwareVersion(): Retrieves the device's firmware version.
• Future<String> getSerialNumber(): Retrieves the device's serial number.
• Future<String> getPlatform(): Retrieves the device's platform information.
• Future<String> getMacAddress(): Retrieves the device's MAC address.
• Future<String> getDeviceName(): Retrieves the device's name.
• Future<int?> getFaceVersion(): Retrieves the face recognition algorithm version.
• Future<int> getFingerprintVersion(): Retrieves the fingerprint algorithm version.
• Future<Map<String, String>> getNetworkParams(): Retrieves the network parameters (IP, subnet mask, gateway) of the device.
• Future<DateTime> getTime(): Retrieves the current time from the device.
• Future<void> setTime(DateTime timestamp): Sets the time on the device.
• Future<List<User>> getUsers(): Fetches a list of all users registered on the device.
• Future<void> setUser({int? uid, String name, int privilege, String password, String groupId, String? userId, int card}): Creates a new user or updates an existing user on the device.
• Future<void> deleteUser({int? uid, String? userId}): Deletes a user from the device.
• Future<List<Attendance>> getAttendance({DateTime? fromDate, DateTime? toDate, String sort}): Retrieves attendance records from the device.
• Future<void> enableDevice(): Enables the device, allowing it to accept user input and perform operations.
• Future<void> disableDevice(): Disables the device, preventing it from accepting user input.
• Future<void> restart(): Restarts the device.
• Future<void> powerOff(): Powers off the device.
• Future<void> refreshData(): Refreshes the device's internal data.
• Future<void> unlock({int time}): Unlocks the door connected to the device's relay.
• Future<bool> testVoice({int index}): Plays a pre-recorded voice message on the device.
• Future<void> clearData(): Clears all data from the device.
• Future<void> clearAttendance(): Clears all attendance records from the device.

It is recommended to wrap calls to the library in a try...catch block.

Additional information

To file issues or contribute to the package, please visit the GitHub repository.