zkteco-lan-agent 1.0.0__tar.gz

zkteco_lan_agent-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+uv.lock

zkteco_lan_agent-1.0.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: zkteco-lan-agent
+Version: 1.0.0
+Summary: Bridge non-ADMS ZKTeco devices to Fitssort ADMS HTTP (attendance, commands, enroll)
+Project-URL: Homepage, https://github.com/GeeksSort/Gym-Management-System-SaaS
+Project-URL: Documentation, https://github.com/GeeksSort/Gym-Management-System-SaaS/blob/main/zkteco_lan_agent/README.md
+Project-URL: Repository, https://github.com/GeeksSort/Gym-Management-System-SaaS
+Author: GeeksSort / Fitssort
+License: Proprietary
+Keywords: adms,attendance,biometric,fitssort,zkteco
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.28
+Requires-Dist: zk>=0.9
+Description-Content-Type: text/markdown
+
+# ZKTeco LAN Agent — gym laptop deployment
+
+Bridge non-ADMS ZKTeco devices (Ethernet / PC Connection only) to Fitssort via
+ADMS HTTP. Runs on a gym LAN laptop or Pi.
+
+```
+Device(s) ──TCP 4370──► Gym laptop (agent) ──HTTP :80 /iclock/*──► Production
+```
+
+Package on PyPI: [`zkteco-lan-agent`](https://pypi.org/project/zkteco-lan-agent/)
+
+## Install (gym laptop)
+
+### With uv (recommended)
+
+```bash
+uv tool install zkteco-lan-agent
+# or one-off:
+uvx zkteco-lan-agent --config devices.yaml
+```
+
+### With pip
+
+```bash
+python -m pip install zkteco-lan-agent
+zkteco-lan-agent --config devices.yaml
+```
+
+### From this repo (development)
+
+```bash
+cd zkteco_lan_agent
+uv sync
+uv run zkteco-lan-agent --config ../devices.yaml
+```
+
+Copy and edit config:
+
+```bash
+cp devices.yaml.example devices.yaml   # from repo root, or create manually
+```
+
+Example `devices.yaml`:
+
+```yaml
+server_url: http://tenant.fitssort.com
+poll_interval_seconds: 30
+command_poll_interval_seconds: 10
+heartbeat_interval_seconds: 60
+
+devices:
+  - name: Front Door K40
+    device_ip: 192.168.1.100
+    device_port: 4370
+    device_sn: "CHANGEME_SN"
+    comm_password: 0
+    timezone: Asia/Dhaka
+```
+
+Keep the laptop awake (disable sleep while the gym is open).
+
+---
+
+## Run as a background service
+
+**systemd does not exist on Windows.** Use the section that matches the OS.
+
+### Linux — systemd
+
+```bash
+# After: uv tool install zkteco-lan-agent
+which zkteco-lan-agent   # note the path, e.g. ~/.local/bin/zkteco-lan-agent
+
+sudo cp zkteco-lan-agent.service /etc/systemd/system/
+# edit ExecStart, WorkingDirectory (config path), User=
+sudo systemctl daemon-reload
+sudo systemctl enable --now zkteco-lan-agent
+sudo systemctl status zkteco-lan-agent
+```
+
+### Windows — Task Scheduler (built-in)
+
+1. Create `start-lan-agent.bat`:
+
+```bat
+@echo off
+cd /d C:\gym\agent
+zkteco-lan-agent --config devices.yaml
+```
+
+2. Task Scheduler → **Create Task** → run at startup → Action: start the `.bat`.
+3. Enable restart on failure; uncheck “Stop if runs longer than…”.
+
+### Windows — NSSM (Windows Service)
+
+```powershell
+nssm install ZktecoLanAgent "C:\Users\You\AppData\Local\Programs\Python\Python312\Scripts\zkteco-lan-agent.exe"
+nssm set ZktecoLanAgent AppDirectory "C:\gym\agent"
+nssm set ZktecoLanAgent AppParameters "--config devices.yaml"
+nssm set ZktecoLanAgent AppRestartDelay 10000
+nssm start ZktecoLanAgent
+```
+
+---
+
+## Dashboard registration
+
+| Field | Value |
+|-------|-------|
+| Profile | ZKTeco |
+| Model | K40 (or actual model) |
+| Mode | **TCP Relay** |
+| Serial | Exact hardware SN |
+
+## Production ADMS smoke tests
+
+```bash
+curl -v "http://<tenant>.fitssort.com/iclock/cdata?SN=<YOUR_SN>"
+curl -v "http://<tenant>.fitssort.com/iclock/getrequest?SN=<YOUR_SN>"
+```
+
+Use `http://` only (HTTPS ADMS paths are not routed).
+
+## Card + fingerprint
+
+- Enroll fingerprints from the web app (ADMS or TCP Relay) or on the device.
+- Provision cards from the app so USERINFO includes `Card=`.
+- Device needs a card reader module for card taps.
+
+---
+
+## Publish to PyPI (maintainers)
+
+Uses [uv](https://docs.astral.sh/uv/).
+
+### One-time setup
+
+1. Create a PyPI account at https://pypi.org (and TestPyPI at https://test.pypi.org).
+2. Create an **API token** (Account → API tokens). Scope: entire account or project `zkteco-lan-agent`.
+3. Prefer env vars (never commit tokens):
+
+```bash
+export UV_PUBLISH_TOKEN=pypi-AgEIcHlwaS5vcmc...   # PyPI
+# or for TestPyPI:
+export UV_PUBLISH_TOKEN=pypi-...                 # TestPyPI token
+```
+
+### Build & test locally
+
+```bash
+cd zkteco_lan_agent
+uv sync --group dev
+uv run pytest
+uv build
+# artifacts in dist/: .whl and .tar.gz
+```
+
+### Publish to TestPyPI first
+
+```bash
+cd zkteco_lan_agent
+uv build
+uv publish --publish-url https://test.pypi.org/legacy/ --token "$UV_PUBLISH_TOKEN"
+```
+
+Install from TestPyPI to verify:
+
+```bash
+uv tool install --index https://test.pypi.org/simple/ --index-strategy unsafe-best-match zkteco-lan-agent
+```
+
+### Publish to PyPI
+
+1. Bump `version` in `pyproject.toml` (and ensure changelog/notes if you keep them).
+2. Build and publish:
+
+```bash
+cd zkteco_lan_agent
+uv build
+uv publish --token "$UV_PUBLISH_TOKEN"
+```
+
+Or interactive (uv prompts for username `__token__` and the API token as password):
+
+```bash
+uv publish
+```
+
+### Version bumps
+
+Edit `version` in [`pyproject.toml`](pyproject.toml). Reinstall picks up `__version__` via `importlib.metadata`.

zkteco_lan_agent-1.0.0/README.md

@@ -0,0 +1,191 @@
+# ZKTeco LAN Agent — gym laptop deployment
+
+Bridge non-ADMS ZKTeco devices (Ethernet / PC Connection only) to Fitssort via
+ADMS HTTP. Runs on a gym LAN laptop or Pi.
+
+```
+Device(s) ──TCP 4370──► Gym laptop (agent) ──HTTP :80 /iclock/*──► Production
+```
+
+Package on PyPI: [`zkteco-lan-agent`](https://pypi.org/project/zkteco-lan-agent/)
+
+## Install (gym laptop)
+
+### With uv (recommended)
+
+```bash
+uv tool install zkteco-lan-agent
+# or one-off:
+uvx zkteco-lan-agent --config devices.yaml
+```
+
+### With pip
+
+```bash
+python -m pip install zkteco-lan-agent
+zkteco-lan-agent --config devices.yaml
+```
+
+### From this repo (development)
+
+```bash
+cd zkteco_lan_agent
+uv sync
+uv run zkteco-lan-agent --config ../devices.yaml
+```
+
+Copy and edit config:
+
+```bash
+cp devices.yaml.example devices.yaml   # from repo root, or create manually
+```
+
+Example `devices.yaml`:
+
+```yaml
+server_url: http://tenant.fitssort.com
+poll_interval_seconds: 30
+command_poll_interval_seconds: 10
+heartbeat_interval_seconds: 60
+
+devices:
+  - name: Front Door K40
+    device_ip: 192.168.1.100
+    device_port: 4370
+    device_sn: "CHANGEME_SN"
+    comm_password: 0
+    timezone: Asia/Dhaka
+```
+
+Keep the laptop awake (disable sleep while the gym is open).
+
+---
+
+## Run as a background service
+
+**systemd does not exist on Windows.** Use the section that matches the OS.
+
+### Linux — systemd
+
+```bash
+# After: uv tool install zkteco-lan-agent
+which zkteco-lan-agent   # note the path, e.g. ~/.local/bin/zkteco-lan-agent
+
+sudo cp zkteco-lan-agent.service /etc/systemd/system/
+# edit ExecStart, WorkingDirectory (config path), User=
+sudo systemctl daemon-reload
+sudo systemctl enable --now zkteco-lan-agent
+sudo systemctl status zkteco-lan-agent
+```
+
+### Windows — Task Scheduler (built-in)
+
+1. Create `start-lan-agent.bat`:
+
+```bat
+@echo off
+cd /d C:\gym\agent
+zkteco-lan-agent --config devices.yaml
+```
+
+2. Task Scheduler → **Create Task** → run at startup → Action: start the `.bat`.
+3. Enable restart on failure; uncheck “Stop if runs longer than…”.
+
+### Windows — NSSM (Windows Service)
+
+```powershell
+nssm install ZktecoLanAgent "C:\Users\You\AppData\Local\Programs\Python\Python312\Scripts\zkteco-lan-agent.exe"
+nssm set ZktecoLanAgent AppDirectory "C:\gym\agent"
+nssm set ZktecoLanAgent AppParameters "--config devices.yaml"
+nssm set ZktecoLanAgent AppRestartDelay 10000
+nssm start ZktecoLanAgent
+```
+
+---
+
+## Dashboard registration
+
+| Field | Value |
+|-------|-------|
+| Profile | ZKTeco |
+| Model | K40 (or actual model) |
+| Mode | **TCP Relay** |
+| Serial | Exact hardware SN |
+
+## Production ADMS smoke tests
+
+```bash
+curl -v "http://<tenant>.fitssort.com/iclock/cdata?SN=<YOUR_SN>"
+curl -v "http://<tenant>.fitssort.com/iclock/getrequest?SN=<YOUR_SN>"
+```
+
+Use `http://` only (HTTPS ADMS paths are not routed).
+
+## Card + fingerprint
+
+- Enroll fingerprints from the web app (ADMS or TCP Relay) or on the device.
+- Provision cards from the app so USERINFO includes `Card=`.
+- Device needs a card reader module for card taps.
+
+---
+
+## Publish to PyPI (maintainers)
+
+Uses [uv](https://docs.astral.sh/uv/).
+
+### One-time setup
+
+1. Create a PyPI account at https://pypi.org (and TestPyPI at https://test.pypi.org).
+2. Create an **API token** (Account → API tokens). Scope: entire account or project `zkteco-lan-agent`.
+3. Prefer env vars (never commit tokens):
+
+```bash
+export UV_PUBLISH_TOKEN=pypi-AgEIcHlwaS5vcmc...   # PyPI
+# or for TestPyPI:
+export UV_PUBLISH_TOKEN=pypi-...                 # TestPyPI token
+```
+
+### Build & test locally
+
+```bash
+cd zkteco_lan_agent
+uv sync --group dev
+uv run pytest
+uv build
+# artifacts in dist/: .whl and .tar.gz
+```
+
+### Publish to TestPyPI first
+
+```bash
+cd zkteco_lan_agent
+uv build
+uv publish --publish-url https://test.pypi.org/legacy/ --token "$UV_PUBLISH_TOKEN"
+```
+
+Install from TestPyPI to verify:
+
+```bash
+uv tool install --index https://test.pypi.org/simple/ --index-strategy unsafe-best-match zkteco-lan-agent
+```
+
+### Publish to PyPI
+
+1. Bump `version` in `pyproject.toml` (and ensure changelog/notes if you keep them).
+2. Build and publish:
+
+```bash
+cd zkteco_lan_agent
+uv build
+uv publish --token "$UV_PUBLISH_TOKEN"
+```
+
+Or interactive (uv prompts for username `__token__` and the API token as password):
+
+```bash
+uv publish
+```
+
+### Version bumps
+
+Edit `version` in [`pyproject.toml`](pyproject.toml). Reinstall picks up `__version__` via `importlib.metadata`.

zkteco_lan_agent-1.0.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "zkteco-lan-agent"
+version = "1.0.0"
+description = "Bridge non-ADMS ZKTeco devices to Fitssort ADMS HTTP (attendance, commands, enroll)"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [
+  { name = "GeeksSort / Fitssort" },
+]
+keywords = ["zkteco", "adms", "attendance", "fitssort", "biometric"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: System Administrators",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Networking",
+]
+dependencies = [
+  "zk>=0.9",
+  "requests>=2.28",
+  "PyYAML>=6.0",
+]
+
+# Note: dependency `zk` pulls in `thriftpy2`, which needs a C compiler + Python
+# headers on first install (Linux: sudo apt install python3-dev build-essential).
+
+[project.urls]
+Homepage = "https://github.com/GeeksSort/Gym-Management-System-SaaS"
+Documentation = "https://github.com/GeeksSort/Gym-Management-System-SaaS/blob/main/zkteco_lan_agent/README.md"
+Repository = "https://github.com/GeeksSort/Gym-Management-System-SaaS"
+
+[project.scripts]
+zkteco-lan-agent = "zkteco_lan_agent.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zkteco_lan_agent"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/zkteco_lan_agent",
+  "tests",
+  "README.md",
+]
+
+[dependency-groups]
+dev = [
+  "pytest>=8.0",
+]
+
+[tool.uv]
+package = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

zkteco_lan_agent-1.0.0/src/zkteco_lan_agent/__init__.py

@@ -0,0 +1,13 @@
+"""ZKTeco LAN Agent — bridges non-ADMS ZKTeco devices to Fitssort ADMS HTTP."""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        __version__ = version("zkteco-lan-agent")
+    except PackageNotFoundError:
+        __version__ = "1.0.0"
+except ImportError:  # pragma: no cover
+    __version__ = "1.0.0"

zkteco_lan_agent-1.0.0/src/zkteco_lan_agent/__main__.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+import time
+
+from zkteco_lan_agent import __version__
+from zkteco_lan_agent.config import ConfigError, load_config
+from zkteco_lan_agent.device_worker import DeviceWorker
+from zkteco_lan_agent.server_client import ServerClient
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+log = logging.getLogger("zkteco_lan_agent")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="ZKTeco LAN Agent — bridge non-ADMS devices to Fitssort")
+    parser.add_argument(
+        "--config",
+        "-c",
+        default="devices.yaml",
+        help="Path to devices.yaml",
+    )
+    parser.add_argument("--version", action="version", version=f"zkteco-lan-agent {__version__}")
+    args = parser.parse_args(argv)
+
+    try:
+        config = load_config(args.config)
+    except ConfigError as exc:
+        log.error("%s", exc)
+        return 2
+
+    server = ServerClient(config.server_url)
+    workers = [DeviceWorker(config, device, server) for device in config.devices]
+    log.info(
+        "Started zkteco-lan-agent %s server=%s devices=%d",
+        __version__,
+        config.server_url,
+        len(workers),
+    )
+    for w in workers:
+        log.info(
+            "  device name=%s sn=%s ip=%s:%d",
+            w.device.name,
+            w.device.device_sn,
+            w.device.device_ip,
+            w.device.device_port,
+        )
+
+    try:
+        while True:
+            start = time.monotonic()
+            for worker in workers:
+                worker.tick()
+            elapsed = time.monotonic() - start
+            time.sleep(max(1, config.poll_interval_seconds - elapsed))
+    except KeyboardInterrupt:
+        log.info("Shutting down")
+        return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

zkteco_lan_agent-1.0.0/src/zkteco_lan_agent/attendance.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+
+def format_attlog_line(
+    user_id: str | int,
+    ts: datetime,
+    *,
+    status: int = 0,
+    verify: int | None = None,
+    in_out: int = 0,
+    work_code: int = 0,
+) -> str:
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
+    time_str = ts.strftime("%Y-%m-%d %H:%M:%S")
+    verify_val = 1 if verify is None else int(verify)
+    return f"{user_id}\t{time_str}\t{status}\t{verify_val}\t{in_out}\t{work_code}"
+
+
+def build_attlog_body(lines: list[str]) -> str:
+    return "TABLE=ATTLOG\n" + "\n".join(lines)
+
+
+def build_userinfo_body(rows: list[dict]) -> str:
+    """Build USERINFO push body from dicts with pin, name, card keys."""
+    lines = ["TABLE=USERINFO"]
+    for row in rows:
+        pin = row.get("pin") or row.get("uid") or ""
+        name = (row.get("name") or "").replace("\t", " ").strip()[:40]
+        card = (row.get("card") or "").strip()
+        lines.append(f"PIN={pin}\tName={name}\tCard={card}")
+    return "\n".join(lines)
+
+
+VERIFY_FINGERPRINT = 1
+VERIFY_CARD = 2
+VERIFY_PASSWORD = 0
+VERIFY_PIN = 3
+VERIFY_FACE = 4
+
+
+def entry_method_for_verify(verify: int | None) -> str:
+    mapping = {
+        VERIFY_PASSWORD: "password",
+        VERIFY_FINGERPRINT: "fingerprint",
+        VERIFY_CARD: "card",
+        VERIFY_PIN: "pin",
+        VERIFY_FACE: "face",
+    }
+    if verify is None:
+        return "fingerprint"
+    return mapping.get(int(verify), "fingerprint")

zkteco_lan_agent-1.0.0/src/zkteco_lan_agent/command_executor.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Callable
+
+from zkteco_lan_agent.attendance import build_attlog_body, build_userinfo_body, format_attlog_line
+
+log = logging.getLogger("zkteco_lan_agent.commands")
+
+
+def parse_userinfo_fields(cmd: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    # Normalize "DATA UPDATE USERINFO PIN=..." so PIN is its own token
+    normalized = re.sub(r"(USERINFO)\s+", r"\1\t", cmd, count=1, flags=re.IGNORECASE)
+    for part in re.split(r"[\t\n]", normalized):
+        part = part.strip()
+        if "=" not in part:
+            continue
+        key, value = part.split("=", 1)
+        key = key.strip()
+        # Drop leading command words glued to the key
+        if " " in key:
+            key = key.split()[-1]
+        fields[key] = value.strip()
+    return fields
+
+
+class CommandExecutor:
+    """Map ADMS command strings to pyzk device operations."""
+
+    def __init__(self, connect_fn: Callable[[], Any], push_cdata: Callable[[str, str], bool]):
+        self._connect = connect_fn
+        self._push_cdata = push_cdata
+
+    def execute(self, cmd: str) -> int:
+        """Return ADMS Return code (0 = success)."""
+        upper = cmd.upper()
+        try:
+            if "UPDATE USERINFO" in upper or upper.startswith("DATA UPDATE USERINFO"):
+                return self._exec_userinfo(cmd)
+            if upper.startswith("ENROLL_FP"):
+                return self._exec_enroll_fp(cmd)
+            if "QUERY ATTLOG" in upper:
+                return self._exec_query_attlog(cmd)
+            if "QUERY USERINFO" in upper:
+                return self._exec_query_userinfo()
+            log.warning("Unsupported command: %s", cmd[:120])
+            return 1
+        except Exception as exc:
+            log.exception("Command execution failed: %s", exc)
+            return 1
+
+    def _with_conn(self, fn: Callable[[Any], int]) -> int:
+        conn = None
+        try:
+            conn = self._connect()
+            conn.disable_device()
+            return fn(conn)
+        finally:
+            if conn is not None:
+                try:
+                    conn.enable_device()
+                except Exception:
+                    pass
+                try:
+                    conn.disconnect()
+                except Exception:
+                    pass
+
+    def _exec_userinfo(self, cmd: str) -> int:
+        fields = parse_userinfo_fields(cmd)
+        pin = fields.get("PIN") or fields.get("Pin") or ""
+        if not pin:
+            return 1
+        name = fields.get("Name") or ""
+        card = fields.get("Card") or ""
+
+        def _run(conn: Any) -> int:
+            uid = int(pin)
+            kwargs: dict[str, Any] = {
+                "uid": uid,
+                "name": name,
+                "privilege": 0,
+                "password": "",
+                "group_id": "",
+                "user_id": str(pin),
+            }
+            # pyzk set_user signature varies; pass card when supported
+            try:
+                conn.set_user(card=card, **kwargs)
+            except TypeError:
+                conn.set_user(**kwargs)
+                if card and hasattr(conn, "set_user"):
+                    # Best-effort second call with positional card if available
+                    try:
+                        conn.set_user(uid, name, 0, "", card, "", str(pin))
+                    except Exception:
+                        log.warning("Could not set card=%s for pin=%s", card, pin)
+            return 0
+
+        return self._with_conn(_run)
+
+    def _exec_enroll_fp(self, cmd: str) -> int:
+        fields = parse_userinfo_fields(cmd)
+        pin = fields.get("PIN") or ""
+        fid = int(fields.get("FID") or 0)
+        if not pin:
+            return 1
+
+        def _run(conn: Any) -> int:
+            uid = int(pin)
+            # pyzk enroll_user / enroll fingerprint APIs differ by firmware
+            if hasattr(conn, "enroll_user"):
+                conn.enroll_user(uid)
+                return 0
+            if hasattr(conn, "enroll_fingerprint"):
+                conn.enroll_fingerprint(uid, fid)
+                return 0
+            log.warning("Device connection has no enroll API; command not executed")
+            return 1
+
+        return self._with_conn(_run)
+
+    def _exec_query_attlog(self, cmd: str) -> int:
+        fields = parse_userinfo_fields(cmd)
+        start = fields.get("StartTime")
+
+        def _run(conn: Any) -> int:
+            logs = conn.get_attendance() or []
+            lines: list[str] = []
+            for att in logs:
+                ts = att.timestamp
+                if start and ts.strftime("%Y-%m-%d %H:%M:%S") < start:
+                    continue
+                verify = getattr(att, "punch", None)
+                if verify is None:
+                    verify = getattr(att, "status", None)
+                lines.append(
+                    format_attlog_line(
+                        att.user_id,
+                        ts,
+                        status=int(getattr(att, "status", 0) or 0),
+                        verify=int(verify) if verify is not None else None,
+                        in_out=int(getattr(att, "punch", 0) or 0),
+                    )
+                )
+            if lines:
+                self._push_cdata(build_attlog_body(lines), "ATTLOG")
+            return 0
+
+        return self._with_conn(_run)
+
+    def _exec_query_userinfo(self) -> int:
+        def _run(conn: Any) -> int:
+            users = conn.get_users() or []
+            rows = []
+            for user in users:
+                rows.append(
+                    {
+                        "pin": getattr(user, "user_id", None) or getattr(user, "uid", ""),
+                        "name": getattr(user, "name", "") or "",
+                        "card": getattr(user, "card", "") or "",
+                    }
+                )
+            if rows:
+                self._push_cdata(build_userinfo_body(rows), "USERINFO")
+            return 0
+
+        return self._with_conn(_run)

zkteco_lan_agent-1.0.0/src/zkteco_lan_agent/config.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+@dataclass
+class DeviceConfig:
+    name: str
+    device_ip: str
+    device_sn: str
+    device_port: int = 4370
+    comm_password: int = 0
+    timezone: str = "Asia/Dhaka"
+
+
+@dataclass
+class AgentConfig:
+    server_url: str
+    devices: list[DeviceConfig] = field(default_factory=list)
+    poll_interval_seconds: int = 30
+    command_poll_interval_seconds: int = 10
+    heartbeat_interval_seconds: int = 60
+    state_dir: str = "/tmp/zkteco_lan_agent"
+
+
+class ConfigError(ValueError):
+    pass
+
+
+def load_config(path: str | Path) -> AgentConfig:
+    raw_path = Path(path)
+    if not raw_path.exists():
+        raise ConfigError(f"Config file not found: {raw_path}")
+
+    data = yaml.safe_load(raw_path.read_text(encoding="utf-8")) or {}
+    return parse_config(data)
+
+
+def parse_config(data: dict[str, Any]) -> AgentConfig:
+    server_url = str(data.get("server_url") or "").rstrip("/")
+    if not server_url:
+        raise ConfigError("server_url is required")
+
+    devices_raw = data.get("devices") or []
+    if not isinstance(devices_raw, list) or not devices_raw:
+        raise ConfigError("devices must be a non-empty list")
+
+    devices: list[DeviceConfig] = []
+    for idx, item in enumerate(devices_raw):
+        if not isinstance(item, dict):
+            raise ConfigError(f"devices[{idx}] must be a mapping")
+        sn = str(item.get("device_sn") or "").strip()
+        if not sn:
+            raise ConfigError(f"devices[{idx}].device_sn is required")
+        ip = str(item.get("device_ip") or "").strip()
+        if not ip:
+            raise ConfigError(f"devices[{idx}].device_ip is required")
+        devices.append(
+            DeviceConfig(
+                name=str(item.get("name") or sn),
+                device_ip=ip,
+                device_sn=sn,
+                device_port=int(item.get("device_port") or 4370),
+                comm_password=int(item.get("comm_password") or 0),
+                timezone=str(item.get("timezone") or "Asia/Dhaka"),
+            )
+        )
+
+    return AgentConfig(
+        server_url=server_url,
+        devices=devices,
+        poll_interval_seconds=int(data.get("poll_interval_seconds") or 30),
+        command_poll_interval_seconds=int(data.get("command_poll_interval_seconds") or 10),
+        heartbeat_interval_seconds=int(data.get("heartbeat_interval_seconds") or 60),
+        state_dir=str(data.get("state_dir") or "/tmp/zkteco_lan_agent"),
+    )

zkteco_lan_agent-1.0.0/src/zkteco_lan_agent/device_worker.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import logging
+import time
+from datetime import datetime, timezone
+from typing import Any
+
+from zk import ZK
+
+from zkteco_lan_agent.attendance import build_attlog_body, format_attlog_line
+from zkteco_lan_agent.command_executor import CommandExecutor
+from zkteco_lan_agent.config import AgentConfig, DeviceConfig
+from zkteco_lan_agent.server_client import ServerClient
+from zkteco_lan_agent.state import DeviceState
+
+log = logging.getLogger("zkteco_lan_agent.worker")
+
+
+class DeviceWorker:
+    def __init__(self, agent: AgentConfig, device: DeviceConfig, server: ServerClient):
+        self.agent = agent
+        self.device = device
+        self.server = server
+        self.state = DeviceState(agent.state_dir, device.device_sn)
+        self._last_heartbeat = 0.0
+        self._last_command_poll = 0.0
+
+    def _connect(self) -> Any:
+        zk = ZK(
+            self.device.device_ip,
+            port=self.device.device_port,
+            timeout=10,
+            password=self.device.comm_password,
+            force_udp=False,
+        )
+        return zk.connect()
+
+    def poll_attendance(self) -> None:
+        conn = None
+        try:
+            conn = self._connect()
+            log.info(
+                "Connected to %s (%s:%d)",
+                self.device.device_sn,
+                self.device.device_ip,
+                self.device.device_port,
+            )
+            conn.disable_device()
+            last_poll = self.state.load_last_poll()
+            logs = conn.get_attendance() or []
+            log.info("SN=%s has %d attendance records", self.device.device_sn, len(logs))
+
+            new_logs = []
+            for att in logs:
+                ts: datetime = att.timestamp
+                if ts.tzinfo is None:
+                    ts = ts.replace(tzinfo=timezone.utc)
+                if last_poll and ts <= last_poll:
+                    continue
+                new_logs.append(att)
+
+            if new_logs:
+                lines: list[str] = []
+                newest: datetime | None = None
+                for att in new_logs:
+                    ts = att.timestamp
+                    if ts.tzinfo is None:
+                        ts = ts.replace(tzinfo=timezone.utc)
+                    # pyzk: status often holds punch type; punch may hold verify on some firmwares
+                    verify = getattr(att, "punch", None)
+                    status = int(getattr(att, "status", 0) or 0)
+                    # Prefer explicit verify attribute if present
+                    if hasattr(att, "verify") and getattr(att, "verify") is not None:
+                        verify = getattr(att, "verify")
+                    lines.append(
+                        format_attlog_line(
+                            att.user_id,
+                            ts,
+                            status=status,
+                            verify=int(verify) if verify is not None else None,
+                            in_out=int(getattr(att, "punch", 0) or 0) if verify is None else 0,
+                        )
+                    )
+                    if newest is None or ts > newest:
+                        newest = ts
+                body = build_attlog_body(lines)
+                if self.server.push_cdata(self.device.device_sn, body, table="ATTLOG") and newest:
+                    self.state.save_last_poll(newest)
+            else:
+                log.info("SN=%s no new records", self.device.device_sn)
+                self._maybe_heartbeat(force=True)
+
+            conn.enable_device()
+        except Exception as exc:
+            log.error("Device poll error SN=%s: %s", self.device.device_sn, exc)
+        finally:
+            if conn:
+                try:
+                    conn.disconnect()
+                except Exception:
+                    pass
+
+    def poll_commands(self) -> None:
+        pending = self.server.get_request(self.device.device_sn)
+        if not pending:
+            return
+
+        def push(body: str, table: str) -> bool:
+            return self.server.push_cdata(self.device.device_sn, body, table=table)
+
+        executor = CommandExecutor(self._connect, push)
+        return_code = executor.execute(pending.cmd)
+        self.server.ack_command(self.device.device_sn, pending.id, return_code)
+
+    def _maybe_heartbeat(self, *, force: bool = False) -> None:
+        now = time.monotonic()
+        if force or now - self._last_heartbeat >= self.agent.heartbeat_interval_seconds:
+            if self.server.heartbeat(self.device.device_sn):
+                self._last_heartbeat = now
+
+    def tick(self) -> None:
+        self.poll_attendance()
+        now = time.monotonic()
+        if now - self._last_command_poll >= self.agent.command_poll_interval_seconds:
+            self.poll_commands()
+            self._last_command_poll = now
+        self._maybe_heartbeat()

zkteco_lan_agent-1.0.0/src/zkteco_lan_agent/server_client.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+
+import requests
+
+from zkteco_lan_agent import __version__
+
+log = logging.getLogger("zkteco_lan_agent.server")
+
+
+@dataclass
+class PendingCommand:
+    id: int
+    cmd: str
+
+
+class ServerClient:
+    def __init__(self, server_url: str, timeout: float = 15.0):
+        self.server_url = server_url.rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({"User-Agent": f"zkteco-lan-agent/{__version__}"})
+
+    def heartbeat(self, device_sn: str) -> bool:
+        try:
+            resp = self.session.get(
+                f"{self.server_url}/iclock/cdata/",
+                params={"SN": device_sn, "agent": __version__},
+                timeout=self.timeout,
+            )
+            return resp.status_code == 200
+        except requests.RequestException as exc:
+            log.warning("Heartbeat failed SN=%s: %s", device_sn, exc)
+            return False
+
+    def push_cdata(self, device_sn: str, body: str, *, table: str) -> bool:
+        try:
+            resp = self.session.post(
+                f"{self.server_url}/iclock/cdata/",
+                params={"SN": device_sn, "table": table},
+                data=body.encode("utf-8"),
+                timeout=self.timeout,
+            )
+            log.info(
+                "Push SN=%s table=%s status=%s body=%s",
+                device_sn,
+                table,
+                resp.status_code,
+                resp.text.strip()[:200],
+            )
+            return resp.status_code == 200
+        except requests.RequestException as exc:
+            log.error("Push failed SN=%s: %s", device_sn, exc)
+            return False
+
+    def get_request(self, device_sn: str) -> PendingCommand | None:
+        try:
+            resp = self.session.get(
+                f"{self.server_url}/iclock/getrequest/",
+                params={"SN": device_sn},
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            log.warning("getrequest failed SN=%s: %s", device_sn, exc)
+            return None
+
+        text = (resp.text or "").strip()
+        if not text or text.upper().startswith("OK"):
+            return None
+
+        match = re.match(r"^C:(\d+):(.+)$", text, re.DOTALL)
+        if not match:
+            log.warning("Unrecognized getrequest response SN=%s: %s", device_sn, text[:200])
+            return None
+        return PendingCommand(id=int(match.group(1)), cmd=match.group(2).strip())
+
+    def ack_command(self, device_sn: str, cmd_id: int, return_code: int = 0) -> bool:
+        try:
+            resp = self.session.post(
+                f"{self.server_url}/iclock/devicecmd/",
+                params={"SN": device_sn},
+                data=f"ID={cmd_id}&Return={return_code}&CMD=DATA".encode("utf-8"),
+                timeout=self.timeout,
+            )
+            return resp.status_code == 200
+        except requests.RequestException as exc:
+            log.error("devicecmd ack failed SN=%s id=%s: %s", device_sn, cmd_id, exc)
+            return False

zkteco_lan_agent-1.0.0/src/zkteco_lan_agent/state.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+
+class DeviceState:
+    def __init__(self, state_dir: str | Path, device_sn: str):
+        self._dir = Path(state_dir)
+        self._dir.mkdir(parents=True, exist_ok=True)
+        safe = "".join(c if c.isalnum() or c in "-_" else "_" for c in device_sn)
+        self._path = self._dir / f"{safe}_last_poll.txt"
+
+    def load_last_poll(self) -> datetime | None:
+        if not self._path.exists():
+            return None
+        raw = self._path.read_text(encoding="utf-8").strip()
+        if not raw:
+            return None
+        try:
+            return datetime.fromisoformat(raw)
+        except ValueError:
+            return None
+
+    def save_last_poll(self, dt: datetime) -> None:
+        self._path.write_text(dt.isoformat(), encoding="utf-8")

zkteco_lan_agent-1.0.0/tests/test_agent.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import sys
+import unittest
+from datetime import datetime, timezone
+from pathlib import Path
+
+SRC = Path(__file__).resolve().parents[1] / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+from zkteco_lan_agent.attendance import (
+    build_attlog_body,
+    entry_method_for_verify,
+    format_attlog_line,
+)
+from zkteco_lan_agent.config import ConfigError, parse_config
+from zkteco_lan_agent.command_executor import parse_userinfo_fields
+
+
+class ConfigTests(unittest.TestCase):
+    def test_parse_multi_device(self):
+        cfg = parse_config(
+            {
+                "server_url": "http://gym.fitssort.com",
+                "devices": [
+                    {"name": "A", "device_ip": "192.168.1.1", "device_sn": "SN1"},
+                    {"device_ip": "192.168.1.2", "device_sn": "SN2"},
+                ],
+            }
+        )
+        self.assertEqual(len(cfg.devices), 2)
+        self.assertEqual(cfg.devices[1].name, "SN2")
+
+    def test_missing_sn_rejected(self):
+        with self.assertRaises(ConfigError):
+            parse_config(
+                {
+                    "server_url": "http://x",
+                    "devices": [{"device_ip": "1.2.3.4"}],
+                }
+            )
+
+    def test_empty_devices_rejected(self):
+        with self.assertRaises(ConfigError):
+            parse_config({"server_url": "http://x", "devices": []})
+
+
+class AttlogFormatTests(unittest.TestCase):
+    def test_full_line_includes_verify(self):
+        ts = datetime(2026, 1, 11, 10, 12, 30, tzinfo=timezone.utc)
+        line = format_attlog_line("1001", ts, status=0, verify=2, in_out=0, work_code=0)
+        self.assertEqual(line, "1001\t2026-01-11 10:12:30\t0\t2\t0\t0")
+
+    def test_default_verify_fingerprint(self):
+        ts = datetime(2026, 1, 11, 10, 12, 30, tzinfo=timezone.utc)
+        line = format_attlog_line("1001", ts)
+        parts = line.split("\t")
+        self.assertEqual(parts[3], "1")
+
+    def test_body_prefix(self):
+        body = build_attlog_body(["1001\t2026-01-11 10:12:30\t0\t1\t0\t0"])
+        self.assertTrue(body.startswith("TABLE=ATTLOG\n"))
+
+    def test_entry_method_mapping(self):
+        self.assertEqual(entry_method_for_verify(2), "card")
+        self.assertEqual(entry_method_for_verify(1), "fingerprint")
+        self.assertEqual(entry_method_for_verify(None), "fingerprint")
+
+
+class CommandParseTests(unittest.TestCase):
+    def test_parse_userinfo(self):
+        fields = parse_userinfo_fields(
+            "DATA UPDATE USERINFO PIN=42\tName=Jane\tCard=RFID-9\tPri=0"
+        )
+        self.assertEqual(fields["PIN"], "42")
+        self.assertEqual(fields["Card"], "RFID-9")
+        self.assertEqual(fields["Name"], "Jane")
+
+
+if __name__ == "__main__":
+    unittest.main()