How allison-ggr/sdk-checador works
Project Type and Purpose
• This is an open-source Python SDK and tooling suite for ZKTeco biometric attendance devices.
• It provides:
• A core Python library (zk/) implementing device communications (connect, get_users, get_attendance, set_user, backup/restore, etc.)
• A set of CLI/test scripts (e.g., test_machine.py, test_backup_restore.py, basic_test.py, script_*.py) that invoke the library to perform common tasks.
• Example scripts under example/ showing API usage.
• A collection of static HTML/JS/CSS files (vistashtml/) representing a simple web dashboard/user interface.
• Documentation built with Sphinx in docs/.
File Structure Analysis
• Top‐level:
• setup.py, .travis.yml, GitHub config – packaging and CI.
• zk/ – core library modules (attendance.py, user.py, finger.py, base.py, const.py, exception.py, scripphpjson.php).
• example/ – standalone scripts demonstrating library usage.
• *.py scripts at root – assorted utilities for backup, restore, user/device management.
• test_*.py – unit/integration tests.
• vistashtml/ – static front-end assets (HTML, JS, CSS) for a dashboard-like UI.
• docs/ – Sphinx source for developer documentation.
Architecture Overview
• Main Components:
A. User Interfaces
1. CLI Tools & Scripts
2. Example Scripts
3. Static Web Dashboard (optional, file‐served or embedded in another server)
B. Core SDK
– ZK class and submodules (attendance, user, finger, exception, const)
– Network transport layer (TCP/UDP) for device communications
C. External Service
– ZKTeco attendance device(s) over LAN (IP+port)
D. Persistent Artifacts
– Backup files (.bak, .json)
– Logs and test outputs
Relationships & Data Flows
• Users (via CLI or Web UI) → invoke functions in the Core SDK
• Core SDK → serialize commands → send to Device over TCP/UDP
• Device → responds → Core SDK parses responses into objects (User, Attendance, Finger)
• Core SDK → returns objects/data to CLI or Web UI
• For backup/restore: Core SDK ↔ File system (read/write backup files, JSON)
• Tests/Examples → import Core SDK directly
Architectural Patterns & Design Principles
• Layered Design:
• Presentation (CLI / Web UI)
• Domain & API (Core SDK)
• Infrastructure (Network transport, File I/O)
• Single Responsibility: each script/tool has one focus (backup, restore, test machine, user management).
• Extensibility: modular subpackages (attendance.py, user.py, finger.py, etc.)
• Standard packaging (setup.py) and documentation (Sphinx)
Components & Technologies
• Python 2/3 compatibility (setup.py, pip packaging)
• Networking: socket-based TCP/UDP communication in zk/base.py
• Sphinx (docs/) for documentation
• Travis CI for continuous integration
• Static HTML/JS/CSS front-end (no backend, can be served by simple HTTP server)
• JSON for backup/restore payloads
Essential Elements
• Annotations for key protocols, data formats (JSON, templates, .bak)