cubetiq/pyztk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

update readme

Browse Source
This commit is contained in:
Fanani M. Ihsan 2018-12-27 17:51:43 +07:00
parent 2ba766c156
commit eedcccac0f
1 changed files with 197 additions and 128 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

325
README.md
View File

@ -1,21 +1,13 @@
# pyzk # pyzk
pyzk is an unofficial library of zksoftware the fingerprint attendance machine. pyzk is an unofficial library of zksoftware (zkteco family) the fingerprint attendance machine.
# Installation # Installation
[![Build Status](https://travis-ci.org/kurenai-ryu/pyzk.svg?branch=master)](https://travis-ci.org/kurenai-ryu/pyzk) [![Build Status](https://travis-ci.org/fananimi/pyzk.svg?branch=master)](https://travis-ci.org/fananimi/pyzk)
replace original pyzk, if it was installed
```sh ```sh
pip install -U git+https://github.com/kurenai-ryu/pyzk.git pip install -U pyzk
```
or using pipenv:
```sh
pipenv install git+https://gith.com/kurenai-ryu/pyzk#egg=pyzk
``` ```
or clone and execute: or clone and execute:
@ -35,11 +27,11 @@ from zk import ZK, const
# Documentation # Documentation
Complete documentation of the original project can be found at [Readthedocs](http://pyzk.readthedocs.io/en/latest/ "pyzk's readthedocs") . Complete documentation can be found at [Readthedocs](http://pyzk.readthedocs.io/en/latest/ "pyzk's readthedocs") .
# Api Usage # API Usage
Just create a ZK object and you will be ready to call api. Create the ZK object and you will be ready to call api.
* Basic Usage * Basic Usage
@ -49,34 +41,34 @@ from zk import ZK, const
conn = None conn = None
zk = ZK('192.168.1.201', port=4370, timeout=5, password=0, force_udp=False, ommit_ping=False) zk = ZK('192.168.1.201', port=4370, timeout=5, password=0, force_udp=False, ommit_ping=False)
try: try:
print ('Connecting to device ...') print ('Connecting to device ...')
conn = zk.connect() conn = zk.connect()
print ('Disabling device ...') print ('Disabling device ...')
conn.disable_device() conn.disable_device()
print ('Firmware Version: : {}'.format(conn.get_firmware_version())) print ('Firmware Version: : {}'.format(conn.get_firmware_version()))
# print '--- Get User ---' # print '--- Get User ---'
users = conn.get_users() users = conn.get_users()
for user in users: for user in users:
privilege = 'User' privilege = 'User'
if user.privilege == const.USER_ADMIN: if user.privilege == const.USER_ADMIN:
privilege = 'Admin' privilege = 'Admin'
print ('- UID #{}'.format(user.uid)) print ('- UID #{}'.format(user.uid))
print (' Name : {}'.format(user.name)) print (' Name : {}'.format(user.name))
print (' Privilege : {}'.format(privilege)) print (' Privilege : {}'.format(privilege))
print (' Password : {}'.format(user.password)) print (' Password : {}'.format(user.password))
print (' Group ID : {}'.format(user.group_id)) print (' Group ID : {}'.format(user.group_id))
print (' User ID : {}'.format(user.user_id)) print (' User ID : {}'.format(user.user_id))
print ("Voice Test ...") print ("Voice Test ...")
conn.test_voice() conn.test_voice()
print ('Enabling device ...') print ('Enabling device ...')
conn.enable_device() conn.enable_device()
except Exception as e: except Exception as e:
print ("Process terminate : {}".format(e)) print ("Process terminate : {}".format(e))
finally: finally:
if conn: if conn:
conn.disconnect() conn.disconnect()
``` ```
* Connect/Disconnect * Connect/Disconnect
@ -89,7 +81,9 @@ conn.disconnect()
* Disable/Enable Connected Device * Disable/Enable Connected Device
```python ```python
# disable (lock) device, ensure no activity while some process run
conn.disable_device() conn.disable_device()
# re-enable the connected device
conn.enable_device() conn.enable_device()
``` ```
@ -97,10 +91,10 @@ conn.enable_device()
```python ```python
from datetime import datetime from datetime import datetime
# get current machine's time
zktime = conn.get_time() zktime = conn.get_time()
print zktime print zktime
# update new time to machine
newtime = datetime.today() newtime = datetime.today()
conn.set_time(newtime) conn.set_time(newtime)
``` ```
@ -135,7 +129,8 @@ conn.fingers
conn.records conn.records
conn.users_cap conn.users_cap
conn.fingers_cap conn.fingers_cap
conn.records_cap # TODO: add records_cap counter
# conn.records_cap
``` ```
* User Operation * User Operation
@ -148,7 +143,6 @@ users = conn.get_users()
# Delete User # Delete User
conn.delete_user(uid=1) conn.delete_user(uid=1)
``` ```
there is also an `enroll_user()` (but it doesn't work with some tcp ZK8 devices)
* Fingerprints * Fingerprints
@ -160,18 +154,18 @@ fingers = conn.get_templates()
# to restore a finger, we need to assemble with the corresponding user # 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 # pass a User object and a list of finger (max 10) to save
conn.save_user_template(user, [fing1 ,fing2]) conn.save_user_template(user, [fing1 ,fing2])
``` ```
* Remote Fingerprint Enrollment * Remote Fingerprint Enrollment
```python ```python
zk.enroll_user('23') zk.enroll_user('1')
# but it doesn't work with some tcp ZK8 devices
``` ```
* Attendance Record * Attendance Record
​```python ```python
# Get attendances (will return list of Attendance object) # Get attendances (will return list of Attendance object)
attendances = conn.get_attendance() attendances = conn.get_attendance()
# Clear attendances record # Clear attendances record
@ -181,14 +175,93 @@ conn.clear_attendance()
* Test voice * Test voice
```python ```python
conn.test_voice(index=10) # beep or chirp """
play test voice:
0 Thank You
1 Incorrect Password
2 Access Denied
3 Invalid ID
4 Please try again
5 Re-enter ID
6 The clock is full
7 The clock is full
8 Duplicate finger
9 Accepted. Thank you
10 beep kuko
11 beep siren
12 -
13 beep bell
/*
**
***
HELP! TRANSLATE TO ENGLISH THE FOLLOWING ITEMS
***
**
*
*/
14 excedido tiempo p esta operacion /-
15 coloque su dedo de nuevo /-
16 coloque su dedo por ultima vez /-
17 ATN numero de tarjeta está repetida /-
18 proceso de registro correcto * /-
19 borrado correcto /-
20 Numero de usuario / ponga la caja de ojos
21 ATN se ha llegado al max num usuarios /-
22 verificacion de usuarios /-
23 usuario no registrado /-
24 ATN se ha llegado al num max de registros /-
25 ATN la puerta no esta cerrada /-
26 registro de usuarios /-
27 borrado de usuarios /-
28 coloque su dedo /-
29 registre la tarjeta de administrador /-
30 0 /-
31 1 /-
32 2 /-
33 3 /-
34 4 /-
35 5 /-
36 6 /-
37 7 /-
38 8 /-
39 9 /-
40 PFV seleccione numero de usuario /-
41 registrar /-
42 operacion correcta /-
43 PFV acerque su tarjeta /-
43 la tarjeta ha sido registrada /-
45 error en operacion /-
46 PFV acerque tarjeta de administracion, p confirmacion /-
47 descarga de fichajes /-
48 descarga de usuarios /-
49 carga de usuarios /-
50 actualizan de firmware /-
51 ejeuctar ficheros de configuracion /-
52 confirmación de clave de acceso correcta /-
53 error en operacion de tclado /-
54 borrar todos los usuarios /-
55 restaurar terminal con configuracion por defecto /-
56 introduzca numero de usuario /-
57 teclado bloqueado /-
58 error en la gestión de la tarjeta /-
59 establezca una clave de acceso /-
60 pulse el teclado /-
61 zona de accceso invalida /-
62 acceso combinado invĺlido /-
63 verificación multiusuario /-
64 modo de verificación inválido /-
65 - /-
"""
conn.test_voice(index=0) # will say 'Thank You'
``` ```
* Device Maintenance * Device Maintenance
```python ```python
# DANGER!!! This command will be erase all data in the device (incude: user, attendance report, and finger database)
conn.clear_data()
# shutdown connected device # shutdown connected device
conn.power_off() conn.poweroff()
# restart connected device # restart connected device
conn.restart() conn.restart()
# clear buffer # clear buffer
@ -200,57 +273,57 @@ conn.free_data()
```python ```python
# live capture! (timeout at 10s) # live capture! (timeout at 10s)
for attendance in conn.live_capture(): for attendance in conn.live_capture():
if attendance is None: if attendance is None:
# implement here timeout logic # implement here timeout logic
pass pass
else: else:
print (attendance) # Attendance object print (attendance) # Attendance object
#
#if you need to break gracefully just set #if you need to break gracefully just set
# conn.end_live_capture = True # conn.end_live_capture = True
# #
# On interactive mode, # On interactive mode,
# use Ctrl+C to break gracefully # use Ctrl+C to break gracefully
# this way it restores timeout # this way it restores timeout
# and disables live capture # and disables live capture
``` ```
**Test Machine** **Test Machine**
```sh ```sh
usage: ./test_machine.py [-h] [-a ADDRESS] [-p PORT] [-T TIMEOUT] [-P PASSWORD] usage: ./test_machine.py [-h] [-a ADDRESS] [-p PORT] [-T TIMEOUT] [-P PASSWORD]
[-f] [-t] [-r] [-u] [-l] [-D DELETEUSER] [-A ADDUSER] [-f] [-t] [-r] [-u] [-l] [-D DELETEUSER] [-A ADDUSER]
[-E ENROLLUSER] [-F FINGER] [-E ENROLLUSER] [-F FINGER]
ZK Basic Reading Tests ZK Basic Reading Tests
optional arguments: optional arguments:
-h, --help show this help message and exit -h, --help show this help message and exit
-a ADDRESS, --address ADDRESS -a ADDRESS, --address ADDRESS
ZK device Address [192.168.1.201] ZK device Address [192.168.1.201]
-p PORT, --port PORT ZK device port [4370] -p PORT, --port PORT ZK device port [4370]
-T TIMEOUT, --timeout TIMEOUT -T TIMEOUT, --timeout TIMEOUT
Default [10] seconds (0: disable timeout) Default [10] seconds (0: disable timeout)
-P PASSWORD, --password PASSWORD -P PASSWORD, --password PASSWORD
Device code/password Device code/password
-b, --basic get Basic Information only. (no bulk read, ie: users) -b, --basic get Basic Information only. (no bulk read, ie: users)
-f, --force-udp Force UDP communication -f, --force-udp Force UDP communication
-v, --verbose Print debug information -v, --verbose Print debug information
-t, --templates Get templates / fingers (compare bulk and single read) -t, --templates Get templates / fingers (compare bulk and single read)
-tr, --templates-raw Get raw templates (dump templates) -tr, --templates-raw Get raw templates (dump templates)
-r, --records Get attendance records -r, --records Get attendance records
-u, --updatetime Update Date/Time -u, --updatetime Update Date/Time
-l, --live-capture Live Event Capture -l, --live-capture Live Event Capture
-o, --open-door Open door -o, --open-door Open door
-D DELETEUSER, --deleteuser DELETEUSER -D DELETEUSER, --deleteuser DELETEUSER
Delete a User (uid) Delete a User (uid)
-A ADDUSER, --adduser ADDUSER -A ADDUSER, --adduser ADDUSER
Add a User (uid) (and enroll) Add a User (uid) (and enroll)
-E ENROLLUSER, --enrolluser ENROLLUSER -E ENROLLUSER, --enrolluser ENROLLUSER
Enroll a User (uid) Enroll a User (uid)
-F FINGER, --finger FINGER -F FINGER, --finger FINGER
Finger for enroll (fid=0) Finger for enroll (fid=0)
``` ```
@ -258,33 +331,33 @@ optional arguments:
```sh ```sh
usage: ./test_backup_restore.py [-h] [-a ADDRESS] [-p PORT] [-T TIMEOUT] usage: ./test_backup_restore.py [-h] [-a ADDRESS] [-p PORT] [-T TIMEOUT]
[-P PASSWORD] [-f] [-v] [-r] [-P PASSWORD] [-f] [-v] [-r]
[filename] [filename]
ZK Basic Backup/Restore Tool ZK Basic Backup/Restore Tool
positional arguments: positional arguments:
filename backup filename (default [serialnumber].bak) filename backup filename (default [serialnumber].bak)
optional arguments: optional arguments:
-h, --help show this help message and exit -h, --help show this help message and exit
-a ADDRESS, --address ADDRESS -a ADDRESS, --address ADDRESS
ZK device Address [192.168.1.201] ZK device Address [192.168.1.201]
-p PORT, --port PORT ZK device port [4370] -p PORT, --port PORT ZK device port [4370]
-T TIMEOUT, --timeout TIMEOUT -T TIMEOUT, --timeout TIMEOUT
Default [10] seconds (0: disable timeout) Default [10] seconds (0: disable timeout)
-P PASSWORD, --password PASSWORD -P PASSWORD, --password PASSWORD
Device code/password Device code/password
-f, --force-udp Force UDP communication -f, --force-udp Force UDP communication
-v, --verbose Print debug information -v, --verbose Print debug information
-E, --erase clean the device after writting backup! -E, --erase clean the device after writting backup!
-r, --restore Restore from backup -r, --restore Restore from backup
-c, --clear-attendance -c, --clear-attendance
On Restore, also clears the attendance [default keep On Restore, also clears the attendance [default keep
attendance] 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. 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 # Compatible devices
@ -293,23 +366,11 @@ Firmware Version : Ver 6.21 Nov 19 2008
Platform : ZEM500 Platform : ZEM500
DeviceName : U580 DeviceName : U580
Firmware Version : Ver 6.60 Oct 29 2012 Firmware Version : Ver 6.60 Apr 9 2010
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 Platform : ZEM510_TFT
DeviceName : T4-C DeviceName : T4-C
Firmware Version : Ver 6.60 Apr 9 2010 Firmware Version : Ver 6.60 Dec 1 2010
Platform : ZEM510_TFT Platform : ZEM510_TFT
DeviceName : T4-C DeviceName : T4-C
@ -317,6 +378,22 @@ Firmware Version : Ver 6.60 Mar 18 2011
Platform : ZEM600_TFT Platform : ZEM600_TFT
DeviceName : iClock260 DeviceName : iClock260
Platform : ZEM560_TFT
Firmware Version : Ver 6.60 Feb 4 2012
DeviceName :
Firmware Version : Ver 6.60 Oct 29 2012
Platform : ZEM800_TFT
DeviceName : iFace402/ID
Firmware Version : Ver 6.60 Mar 18 2013
Platform : ZEM560
DeviceName : MA300
Firmware Version : Ver 6.60 Dec 27 2014
Platform : ZEM600_TFT
DeviceName : iFace800/ID
Firmware Version : Ver 6.60 Nov 6 2017 (remote tested with correct results) Firmware Version : Ver 6.60 Nov 6 2017 (remote tested with correct results)
Platform : ZMM220_TFT Platform : ZMM220_TFT
DeviceName : (unknown device) (broken info but at least the important data was read) DeviceName : (unknown device) (broken info but at least the important data was read)
@ -343,8 +420,6 @@ Firmware Version : Ver 6.60 Jun 16 2015
Platform : JZ4725_TFT Platform : JZ4725_TFT
DeviceName : K14 (not tested, but same behavior like the other one) DeviceName : K14 (not tested, but same behavior like the other one)
Firmware Version : Ver 6.60 Jun 5 2015 Firmware Version : Ver 6.60 Jun 5 2015
Platform : ZMM200_TFT Platform : ZMM200_TFT
DeviceName : iClock3000/ID (Active testing! latest fix) DeviceName : iClock3000/ID (Active testing! latest fix)
@ -364,12 +439,6 @@ DeviceName : iClock260 (no capture data - probably similar problem as the latest
If you have another version tested and it worked, please inform me to update this list! 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
# Todo # Todo
* Create better documentation * Create better documentation