DOCSEARCHbyAlgolia
Submit Docs

zk-protocol

repository·master·Indexed 42 days ago

https://github.com/adrobinoga/zk-protocol

A precise description of the communication protocol used by ZKTeco Standalone devices, specifically the TFT series. It provides a reference for developers building integrations, covering packet structures, checksum calculations, and command identifiers for operations such as user data management, record management, and realtime events.

Tokens
17.2K
Snippets
50
Records
67
Agent score
53%

What's inside zk-protocol

  2. Overview of ZKAccess Protocol Operations

    master

    The protocol allows for bidirectional communication with standalone terminals. Terminals act as a server, and communication can occur via TCP/IP, UDP/IP, Serial, or USB.

    Operation Types

    • Download: Requesting information from the terminal (e.g., attendance records, device model, status).
    • Upload: Sending information to the terminal (e.g., adding users, changing permissions, device settings).
    • Report Events: Packets sent from the machine to the PC automatically when specific actions occur (unsolicited).

    Functional Classifications

    • Terminal operations: Managing communication, device time, and generic device info.
    • Data operations: Managing specific data types including User, Record (attendance logs), Shorcut, Workcode, SMS, Bell, Photo, Voice, Theme, App, and Biometric data.
    • Access: Managing groups, timezones, and holidays.
    • Realtime: Realtime event procedures.
    • Misc: Miscellaneous tasks like restarting, powering off, or taking fingerprint pictures.

  3. Understand ZKTeco Standalone Device Terminology

    master

    The protocol documentation uses specific terms to describe different hardware types and device categories. Use these terms to identify the device capabilities you are interacting with:

    • terminal / machine: The standalone device itself.
    • FRT: Fingerprint reader terminal.
    • FFR: Fingerprint and facial recognition terminal.
    • BW devices: Devices with a black & white screen.
    • TFT devices: Devices with a color TFT screen.
    • iFace devices: Devices with face recognition and a touch screen.
    • SSR: Self service recorder.

  4. Protocol Communication Patterns

    master

    Communication follows two main patterns depending on the complexity of the task:

    1. Simple Tasks: A standard request-reply pattern (e.g., get-device-time).
    2. Intensive Operations: For large transactions (e.g., bulk user updates), the procedure should begin with a disable-device command to prevent undefined behavior, followed by the operations, and finally an enable-device command.

  5. Packet Structure for ZKTeco Standalone Devices

    master

    All communication with ZKTeco devices uses a packet-based protocol consisting of two main types: Regular packets (used for request/reply procedures) and Realtime packets (used by the machine to report events spontaneously).

    Every packet follows a common header structure:

    NameDescriptionValue [hex]Size [bytes]Offset
    startIndicates start of packet5050827d40
    payload sizeSize of packet payload (Little Endian)varies44
    payloadThe actual packet datavariespayload_size8

    Note: The payload size is in Little Endian format.

    Example of a regular type packet (hex):
50 50 82 7D 0C 00 00 00 0B 00 58 EF C5 C0 05 00 7E 4F 53 00

In this example:
- Payload size: `0x0000000C` (12 bytes)
- Payload: `0B 00 58 EF C5 C0 05 00 7E 4F 53 00`

  6. Construct a Realtime Packet

    master

    Realtime packets are used for event-driven communication. They differ from regular packets only in the session id and reply number fields. All other fields, including payload size and checksum, are calculated using the same logic as regular packets.

    Use the notation rtpacket(event=<event code>, data=<payload data>) to represent these. The event code is provided in Big Endian format.

    rtpacket(event=<event code>, data=<payload data>)

  7. Understand the Permission Token bitmask

    master

    The permission token (1 byte at offset 2 in a user entry) defines the user's admin level and their enabled/disabled state.

    Bit Offset7-43210
    FieldUnusedP2P1P0E0

    Admin Levels (P2P1P0)

    P2P1P0Level
    000Common user
    001Enroll user
    011Admin
    111Super admin

    User State (E0)

    E0State
    0Enabled
    1Disabled

  8. Construct a Regular Packet

    master

    A regular packet is the standard communication unit for ZKTeco standalone devices. When using the protocol notation packet(id=<command/reply code>, data=<payload data>), the resulting binary structure follows this layout. Note that payload size, checksum, session id, and reply number must be calculated based on the context and the provided parameters.

    NameDescriptionValue [hex]Size [bytes]Offset
    startIndicates start of packet5050827d40
    payload sizeSize of packet payloadpayload_size(<)44
    idCommand identifier/Reply codevaries28
    checksumChecksumvaries210
    session idSession idvaries212
    reply numberReply numbervaries214
    dataSpecific data for command/replyvariespayload_size - 816

    Important Implementation Details:

    • Endianness: The < symbol indicates Little Endian format for the payload size and other numeric fields.
    • Command Codes: While the packet structure uses little endian for sizes, the hex codes for id (command/reply codes) are provided in Big Endian in the documentation tables.
    • Empty Data: If the data parameter is absent, assume an empty payload field.
    • String Termination: Some commands require the data field to be terminated with 0x00 to indicate the end of a string. This is explicitly shown in the documentation as 00 or \x00 to prevent ambiguity.
    packet(id=CMD_ACK_OK, session id=0000)

  9. How user access and permissions work

    master

    Access control in ZKTeco devices is determined by three primary factors. A user must satisfy all of these conditions to open a door:

    1. Successful Verification: The user must pass their assigned Verify style (e.g., Fingerprint, RFID card, Password, or User ID).
    2. Valid Timezone: The attempt must occur within one of the user's assigned timezones (or the group's timezones). Timezones are defined as (Start time):(End time) for each day of the week. Timezones are ORed, meaning if the user satisfies at least one, they are valid.
    3. Valid Unlock Combination: The user must belong to a group that is part of an active unlock combination. An unlock combination can consist of up to 5 groups (e.g., G1 G2 G3 G4 G5). To satisfy a combination, users from the required groups must validate at the same time. A single-group combination is represented as 01: 01 00 00 00 00.

  10. Sending large datasets

    master
    This protocol does not implement a specific procedure for writing large datasets in a single operation. Instead, large datasets should be written using individual write operations (e.g., modifying user info or templates one at a time). While some systems like ZKAccess use bulk sync procedures, this project handles large data transfers via sequential individual writes.

  11. Getting started with zk-protocol

    master

    The zk-protocol project provides a description of the protocol used in ZKTeco devices, specifically targeting an alternative for ZKTeco's Standalone devices.

    Before using this protocol, it is highly recommended to:

    1. Read the official ZKTeco user manual.
    2. Review the Standalone SDK documentation available on ZKTeco's SDKs Download page.
    3. Check the PyZatt lib for related implementations.

    To understand the core protocol logic, start with the protocol.md file.

  12. Read Attendance Records

    master

    To read attendance records, you must first disable the device, request the data using CMD_DATA_WRRQ with a specific 11-byte payload, and then re-enable the device.

    Workflow:

    1. Send CMD_DISABLEDEVICE and wait for CMD_ACK_OK.
    2. Send CMD_DATA_WRRQ with payload 010d000000000000000000.
    3. Receive data via CMD_DATA. For small structures, the data is sent immediately. For larger structures, follow the Exchange of Data specification.
    4. Send CMD_ENABLEDEVICE and wait for CMD_ACK_OK to return the device to normal operation.

    Attendance Record Structure (att rec):

    • att_size (4 bytes, offset 0): Total size of user attendance entries (Little Endian).
    • attN entry (40 bytes each): Individual log entries starting at offset 4.

    Attendance Entry Fields (40 bytes):

    • user sn (2 bytes, offset 0): Internal serial number (Little Endian).
    • user id (9 bytes, offset 2): User ID as a string.
    • Fixed (15 bytes, offset 11): Constant 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00.
    • verify type (1 byte, offset 26): 0=Password, 1=Fingerprint, 2=RF card.
    • record time (4 bytes, offset 27): Event time (Little Endian).
    • verify state (1 byte, offset 31): 0=Check in, 1=Check out, 2=Break out, 3=Break in, 4=OT in, 5=OT out.
    • Fixed (8 bytes, offset 32): Constant 00 00 00 00 FF 00 00 00.
    // 1. Disable device
packet(id=CMD_DISABLEDEVICE)
packet(id=CMD_ACK_OK)

// 2. Request attendance data
packet(id=CMD_DATA_WRRQ, data=010d000000000000000000)

// 3. Receive data (example for small structure)
packet(id=CMD_DATA, data=<att rec>)

// 4. Enable device
packet(id=CMD_ENABLEDEVICE)
packet(id=CMD_ACK_OK)