BNet.ZKTecoADMS 3.0.0

ZKTecoADMS

A lightweight, async, event-driven HTTP server that speaks the ZKTeco ADMS / Push protocol. Built on raw HttpListener with no third-party dependencies — just clean attendance data handling with photo support, heartbeat monitoring, and async events.

📦 Installation

Clone or reference the library directly from the GitHub repository:

• Library source: BNet.ZKTecoADMS
• Sample project: BNet.ZKTecoADMS.Sample

🚀 Quick Start

using ZKTecoADMS;

var server = new ZKTecoServer
{
    Port               = 4780,
    PhotoSaveDirectory = @"C:\ZKPhotos",
    Delay              = 10,
    ErrorDelay         = 30,
    TimeZone           = 8
};

server.OnHandshake += (sender, e) =>
    Console.WriteLine($"Device connected: {e.SN}");

server.OnAttendance += (sender, e) =>
    Console.WriteLine($"Punch: User={e.UserId} Time={e.PunchTime} Verify={e.VerifyMode}");

server.OnPhotoReceived += (sender, e) =>
    Console.WriteLine($"Photo saved: {e.SavedPath}");

server.OnHeartbeat += (sender, e) =>
    Console.WriteLine($"Heartbeat from {e.SN} — pending photos: {e.PhotoCount}");

server.OnError += (sender, e) =>
    Console.WriteLine($"Error [{e.Source}]: {e.Exception?.Message}");

await server.StartAsync();

🔌 Pointing Your ZKTeco Device

On the device admin panel, set the Push Server (ADMS/Cloud) address to your server's IP and port.

Plain HTTP:

http://192.168.1.100:4780

Common menu path on the device:

Menu → Comm → Cloud Server Settings → Server Address + Port

The device will call /iclock/cdata for handshake, /iclock/getrequest for heartbeats, and POST to /iclock/cdata?table=ATTLOG / ATTPHOTO to push records.

📡 API Reference

ZKTecoServer

Events

📋 Event Args Reference

HandshakeEventArgs

HeartbeatEventArgs

AttendanceEventArgs

PunchType Enum

MB460 Plus firmware note: This device always sends PunchState=4 via ADMS Push. The actual punch type selected on the device is carried in the VerifyMode field and resolved automatically by the server.

PhotoEventArgs

ErrorEventArgs

RawRequestEventArgs

🔤 ZKTecoHelper

VerifyLabel(int verifyMode)

Returns a human-readable label for a VerifyMode value.

📸 Attendance Photos

The server automatically extracts and saves JPEG photos from ATTPHOTO uploads. When a device sends a photo:

1. Extracts the JPEG by scanning for the FF D8 FF magic bytes after the CMD=uploadphoto marker.
2. Saves the file to PhotoSaveDirectory with the filename format {userId}_{yyyy-MM-dd_HHmmss}.jpg.
3. Fires OnPhotoReceived with the saved path and raw bytes so you can do additional processing.

Accessing the raw bytes (e.g. to save to a database instead of disk):

server.OnPhotoReceived += (sender, e) =>
{
    if (e.Success && e.ImageBytes != null)
    {
        // e.g. upload to cloud storage, store in DB blob column...
        await myStorage.UploadAsync(e.UserId, e.ImageBytes);
    }
};

Controlling which photos the device sends via PhotoStamp:

// 0 = resend every photo from the beginning (default)
server.PhotoStamp = 0;

// Set to a specific stamp value to only receive photos newer than that point
server.PhotoStamp = 1234567890;

🛑 Graceful Shutdown

Use a CancellationToken to stop the server cleanly:

using var cts = new CancellationTokenSource();

// Start in background
server.Start(cts.Token);

// Later — stop gracefully
cts.Cancel();
await server.StopAsync();

Or use using for automatic cleanup (on .NET Core 3+ / .NET 5+):

await using var server = new ZKTecoServer { Port = 4780 };
await server.StartAsync();

🔍 Raw Request Debugging

Subscribe to OnRawRequest to inspect every HTTP call from the device before any parsing occurs:

server.OnRawRequest += (sender, e) =>
    Console.WriteLine($"{e.Method} {e.Url} — body {e.RawBody?.Length} bytes");

⚠️ Limitations

• HttpListener requires elevated privileges on Windows when binding to a non-localhost prefix. Run as Administrator, or register the URL prefix with netsh:

  netsh http add urlacl url=http://+:4780/ user=DOMAIN\username
  

• Single-read per request: Very large photo payloads that exceed the TCP receive buffer in a single read may be truncated. Keeping individual photo sizes under ~35 KB is recommended.
• No built-in TLS: The ADMS Push protocol typically runs over plain HTTP on the local network. If you need HTTPS, place a reverse proxy (nginx, IIS, Caddy) in front.
• netstandard2.0 / netstandard2.1 targets require the System.Net.HttpListener NuGet package — this is included automatically when referencing this library.