pyztk/README.md

380 lines
9.8 KiB
Markdown
Raw Normal View History

2016-05-24 08:11:36 +07:00
# pyzk
2016-06-24 19:00:55 +07:00
pyzk is an unofficial library of zksoftware the fingerprint attendance machine.
2016-05-26 12:51:04 +07:00
2016-05-26 23:27:05 +07:00
# Installation
2018-06-13 21:14:21 +07:00
[![Build Status](https://travis-ci.org/kurenai-ryu/pyzk.svg?branch=master)](https://travis-ci.org/kurenai-ryu/pyzk)
2016-05-27 02:10:53 +07:00
2018-06-13 21:14:21 +07:00
replace original pyzk, if it was installed
2018-08-21 20:00:46 +07:00
```sh
pip install -U git+https://github.com/kurenai-ryu/pyzk.git
```
or using pipenv:
```sh
pipenv install git+https://gith.com/kurenai-ryu/pyzk#egg=pyzk
```
2018-06-13 21:14:21 +07:00
or clone and execute:
2018-08-21 20:00:46 +07:00
```sh
python setup.py install
```
2018-06-13 21:14:21 +07:00
or in your project, append the path of this project
```python
import sys
import os
sys.path.insert(1,os.path.abspath("./pyzk"))
from zk import ZK, const
```
2016-05-26 23:27:05 +07:00
2016-05-27 01:33:51 +07:00
# Documentation
2018-06-13 21:14:21 +07:00
Complete documentation of the original project can be found at [Readthedocs](http://pyzk.readthedocs.io/en/latest/ "pyzk's readthedocs") .
2016-05-27 01:33:51 +07:00
2016-05-26 23:27:05 +07:00
# Api Usage
2016-05-26 12:51:04 +07:00
2018-05-26 04:26:41 +07:00
Just create a ZK object and you will be ready to call api.
2016-05-26 12:51:04 +07:00
2016-05-26 22:15:03 +07:00
* Basic Usage
2018-10-02 23:01:50 +07:00
2018-05-04 02:58:52 +07:00
```python
2016-06-24 19:00:55 +07:00
from zk import ZK, const
2016-05-26 12:51:04 +07:00
2016-06-24 19:00:55 +07:00
conn = None
zk = ZK('192.168.1.201', port=4370, timeout=5, password=0, force_udp=False, ommit_ping=False)
2016-05-26 12:51:04 +07:00
try:
2018-05-04 02:58:52 +07:00
print ('Connecting to device ...')
2016-05-30 09:49:54 +07:00
conn = zk.connect()
2018-05-04 02:58:52 +07:00
print ('Disabling device ...')
2016-06-24 19:00:55 +07:00
conn.disable_device()
2018-05-04 02:58:52 +07:00
print ('Firmware Version: : {}'.format(conn.get_firmware_version()))
2016-06-24 19:00:55 +07:00
# print '--- Get User ---'
users = conn.get_users()
2016-05-30 09:49:54 +07:00
for user in users:
privilege = 'User'
if user.privilege == const.USER_ADMIN:
privilege = 'Admin'
2018-05-04 02:58:52 +07:00
print ('- UID #{}'.format(user.uid))
print (' Name : {}'.format(user.name))
print (' Privilege : {}'.format(privilege))
print (' Password : {}'.format(user.password))
print (' Group ID : {}'.format(user.group_id))
print (' User ID : {}'.format(user.user_id))
2016-06-17 14:00:13 +07:00
2018-05-04 02:58:52 +07:00
print ("Voice Test ...")
2016-06-24 19:00:55 +07:00
conn.test_voice()
2018-05-04 02:58:52 +07:00
print ('Enabling device ...')
2016-06-24 19:00:55 +07:00
conn.enable_device()
2018-05-04 02:58:52 +07:00
except Exception as e:
print ("Process terminate : {}".format(e))
2016-05-26 12:51:04 +07:00
finally:
2016-05-30 09:49:54 +07:00
if conn:
2016-06-24 19:00:55 +07:00
conn.disconnect()
2016-05-26 12:51:04 +07:00
```
2016-06-17 13:54:05 +07:00
* Connect/Disconnect
2018-08-21 20:00:46 +07:00
```python
2016-06-24 19:00:55 +07:00
conn = zk.connect()
conn.disconnect()
2016-06-17 13:54:05 +07:00
```
* Disable/Enable Connected Device
2018-08-21 20:00:46 +07:00
```python
2016-06-24 19:00:55 +07:00
conn.disable_device()
conn.enable_device()
2016-06-17 13:54:05 +07:00
```
2018-04-30 21:25:43 +07:00
* Get and Set Time
2018-08-21 20:00:46 +07:00
```python
2018-04-30 21:25:43 +07:00
from datetime import datetime
zktime = conn.get_time()
print zktime
newtime = datetime.today()
conn.set_time(newtime)
```
* Ger Firmware Version and extra information
2016-05-26 12:51:04 +07:00
2018-08-21 20:00:46 +07:00
```python
2016-06-24 19:00:55 +07:00
conn.get_firmware_version()
2018-04-30 21:25:43 +07:00
conn.get_serialnumber()
conn.get_platform()
conn.get_device_name()
conn.get_face_version()
conn.get_fp_version()
conn.get_extend_fmt()
conn.get_user_extend_fmt()
conn.get_face_fun_on()
conn.get_compat_old_firmware()
conn.get_network_params()
conn.get_mac()
conn.get_pin_width()
```
* Get Device use and free Space
2018-05-04 02:58:52 +07:00
```python
2018-04-30 21:25:43 +07:00
conn.read_sizes()
print(conn)
#also:
conn.users
conn.fingers
conn.records
conn.users_cap
conn.fingers_cap
conn.records_cap
2016-05-26 12:51:04 +07:00
```
2016-06-17 13:54:05 +07:00
* User Operation
2016-05-26 12:51:04 +07:00
2018-05-04 02:58:52 +07:00
```python
2016-06-17 13:54:05 +07:00
# Create user
2018-04-30 21:25:43 +07:00
conn.set_user(uid=1, name='Fanani M. Ihsan', privilege=const.USER_ADMIN, password='12345678', group_id='', user_id='123', card=0)
2016-06-17 13:54:05 +07:00
# Get all users (will return list of User object)
2016-06-24 19:00:55 +07:00
users = conn.get_users()
2016-06-17 13:54:05 +07:00
# Delete User
2016-06-24 19:00:55 +07:00
conn.delete_user(uid=1)
2016-05-26 12:51:04 +07:00
```
2018-05-04 02:58:52 +07:00
there is also an `enroll_user()` (but it doesn't work with some tcp ZK8 devices)
2018-04-30 21:25:43 +07:00
* Fingerprints
2018-05-04 02:58:52 +07:00
```python
2018-04-30 21:25:43 +07:00
# Get a single Fingerprint (will return a Finger object)
template = conn.get_user_template(uid=1, temp_id=0) #temp_id is the finger to read 0~9
# Get all fingers from DB (will return a list of Finger objects)
fingers = conn.get_templates()
# to restore a finger, we need to assemble with the corresponding user
# pass a User object and a list of finger (max 10) to save
conn.save_user_template(user, [fing1 ,fing2])
2018-10-30 09:04:15 +07:00
```
2016-05-26 12:51:04 +07:00
2018-03-01 16:56:09 +07:00
* Remote Fingerprint Enrollment
2018-10-30 09:04:15 +07:00
```python
2018-03-01 16:56:09 +07:00
zk.enroll_user('23')
2018-04-30 21:25:43 +07:00
```
2016-05-26 12:51:04 +07:00
2016-06-17 13:54:05 +07:00
* Attendance Record
​```python
2016-06-17 13:54:05 +07:00
# Get attendances (will return list of Attendance object)
2016-06-24 19:00:55 +07:00
attendances = conn.get_attendance()
2016-06-17 13:54:05 +07:00
# Clear attendances record
2016-06-24 19:00:55 +07:00
conn.clear_attendance()
2016-05-26 13:05:17 +07:00
```
2016-05-26 12:51:04 +07:00
* Test voice
2018-05-04 02:58:52 +07:00
```python
2018-04-30 21:25:43 +07:00
conn.test_voice(index=10) # beep or chirp
2016-05-26 12:51:04 +07:00
```
2016-06-17 13:54:05 +07:00
* Device Maintenance
2016-05-26 12:51:04 +07:00
2018-05-04 02:58:52 +07:00
```python
2016-06-17 13:54:05 +07:00
# shutdown connected device
2016-06-24 19:00:55 +07:00
conn.power_off()
2016-06-17 13:54:05 +07:00
# restart connected device
2016-06-24 19:00:55 +07:00
conn.restart()
2018-04-30 21:25:43 +07:00
# clear buffer
conn.free_data()
2016-05-26 12:55:18 +07:00
```
2018-05-26 04:26:41 +07:00
* Live Capture!
```python
# live capture! (timeout at 10s)
for attendance in conn.live_capture():
if attendance is None:
# implement here timeout logic
pass
else:
print (attendance) # Attendance object
#
2018-05-26 04:26:41 +07:00
#if you need to break gracefully just set
# conn.end_live_capture = True
#
# On interactive mode,
2018-05-26 04:26:41 +07:00
# use Ctrl+C to break gracefully
# this way it restores timeout
# and disables live capture
```
2018-09-13 20:47:49 +07:00
**Test Machine**
2018-05-04 02:58:52 +07:00
```sh
usage: ./test_machine.py [-h] [-a ADDRESS] [-p PORT] [-T TIMEOUT] [-P PASSWORD]
[-f] [-t] [-r] [-u] [-l] [-D DELETEUSER] [-A ADDUSER]
[-E ENROLLUSER] [-F FINGER]
ZK Basic Reading Tests
optional arguments:
-h, --help show this help message and exit
-a ADDRESS, --address ADDRESS
ZK device Address [192.168.1.201]
-p PORT, --port PORT ZK device port [4370]
-T TIMEOUT, --timeout TIMEOUT
Default [10] seconds (0: disable timeout)
-P PASSWORD, --password PASSWORD
Device code/password
-b, --basic get Basic Information only. (no bulk read, ie: users)
2018-05-04 02:58:52 +07:00
-f, --force-udp Force UDP communication
2018-05-26 04:26:41 +07:00
-v, --verbose Print debug information
-t, --templates Get templates / fingers (compare bulk and single read)
-tr, --templates-raw Get raw templates (dump templates)
2018-05-04 02:58:52 +07:00
-r, --records Get attendance records
-u, --updatetime Update Date/Time
-l, --live-capture Live Event Capture
2018-06-13 21:14:21 +07:00
-o, --open-door Open door
2018-05-04 02:58:52 +07:00
-D DELETEUSER, --deleteuser DELETEUSER
Delete a User (uid)
-A ADDUSER, --adduser ADDUSER
Add a User (uid) (and enroll)
-E ENROLLUSER, --enrolluser ENROLLUSER
Enroll a User (uid)
-F FINGER, --finger FINGER
Finger for enroll (fid=0)
```
2018-09-13 20:47:49 +07:00
**Backup/Restore (Users and fingers only!!!)** *(WARNING! destructive test! do it at your own risk!)*
```sh
usage: ./test_backup_restore.py [-h] [-a ADDRESS] [-p PORT] [-T TIMEOUT]
[-P PASSWORD] [-f] [-v] [-r]
[filename]
ZK Basic Backup/Restore Tool
positional arguments:
filename backup filename (default [serialnumber].bak)
optional arguments:
-h, --help show this help message and exit
-a ADDRESS, --address ADDRESS
ZK device Address [192.168.1.201]
-p PORT, --port PORT ZK device port [4370]
-T TIMEOUT, --timeout TIMEOUT
Default [10] seconds (0: disable timeout)
-P PASSWORD, --password PASSWORD
Device code/password
-f, --force-udp Force UDP communication
-v, --verbose Print debug information
2018-09-13 21:23:58 +07:00
-E, --erase clean the device after writting backup!
-r, --restore Restore from backup
-c, --clear-attendance
On Restore, also clears the attendance [default keep
attendance]
```
to restore on a different device, make sure to specify the `filename`. on restoring, it asks for the serial number of the destination device (to make sure it was correct, as it deletes all data) WARNING. there is no way to restore attendance data, you can keep it or clear it, but once cleared, there is no way to restore it.
# Compatible devices
```
Firmware Version : Ver 6.21 Nov 19 2008
Platform : ZEM500
DeviceName : U580
Firmware Version : Ver 6.60 Oct 29 2012
Platform : ZEM800_TFT
DeviceName : iFace402/ID
Firmware Version : Ver 6.60 Dec 27 2014
Platform : ZEM600_TFT
DeviceName : iFace800/ID
Firmware Version : Ver 6.60 Mar 18 2013
Platform : ZEM560
DeviceName : MA300
Firmware Version : Ver 6.60 Dec 1 2010
Platform : ZEM510_TFT
DeviceName : T4-C
Firmware Version : Ver 6.60 Apr 9 2010
Platform : ZEM510_TFT
DeviceName : T4-C
Firmware Version : Ver 6.60 Mar 18 2011
Platform : ZEM600_TFT
DeviceName : iClock260
Firmware Version : Ver 6.60 Nov 6 2017 (remote tested with correct results)
Platform : ZMM220_TFT
DeviceName : (unknown device) (broken info but at least the important data was read)
2018-09-13 23:07:32 +07:00
Firmware Version : Ver 6.60 Jun 9 2017
Platform : JZ4725_TFT
DeviceName : K20 (latest checked correctly!)
Firmware Version : Ver 6.60 Aug 23 2014
Platform : ZEM600_TFT
DeviceName : VF680 (face device only, but we read the user and attendance list!)
```
### Latest tested (not really confirmed)
```
Firmware Version : Ver 6.60 Jun 16 2015
Platform : JZ4725_TFT
DeviceName : iClock260
Firmware Version : Ver 6.60 Jun 16 2015
Platform : JZ4725_TFT
DeviceName : K14 (not tested, but same behavior like the other one)
2018-09-13 23:07:32 +07:00
Firmware Version : Ver 6.60 Jun 5 2015
Platform : ZMM200_TFT
DeviceName : iClock3000/ID (Active testing! latest fix)
2018-09-13 20:47:49 +07:00
Firmware Version : Ver 6.70 Jul 12 2013
Platform : ZEM600_TFT
DeviceName : iClock880-H/ID (Active testing! latest fix)
```
### Not Working (needs more tests, more information)
```
Firmware Version : Ver 6.4.1 (build 99) (display version 2012-08-31)
Platform :
DeviceName : iClock260 (no capture data - probably similar problem as the latest TESTED)
```
If you have another version tested and it worked, please inform me to update this list!
# Related Project
* [zkcluster](https://github.com/kurenai-ryu/zkcluster/ "zkcluster project") is a django apps to manage multiple fingerprint devices. (Initial support form the [original project](https://github.com/fananimi/zkcluster/))
# Related Project (TODO: check compatibility with this fork)
* [Driji](https://github.com/fananimi/driji/ "Driji project") is an attendance apps based fingerprint for school
2016-05-26 12:55:18 +07:00
# Todo
2016-05-26 22:15:03 +07:00
* Create better documentation
* ~~Finger template downloader & uploader~~
2016-05-26 12:55:18 +07:00
* HTTP Rest api
* ~~Create real time api (if possible)~~
2016-06-17 13:54:05 +07:00
* and much more ...