pyztk/README.md

218 lines
5.1 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
2016-05-27 02:10:53 +07:00
[![Build Status](https://travis-ci.org/fananimi/pyzk.svg?branch=master)](https://travis-ci.org/fananimi/pyzk)
2016-05-26 23:27:05 +07:00
`pip install pyzk`
2016-05-27 01:33:51 +07:00
# Documentation
Complete documentation can be found at [Readthedocs](http://pyzk.readthedocs.io/en/latest/ "pyzk's readthedocs") .
2016-05-26 23:27:05 +07:00
# Api Usage
2016-05-26 12:51:04 +07:00
2016-07-04 16:29:01 +07:00
Just create a ZK object and you will ready to call api.
2016-05-26 12:51:04 +07:00
2016-05-26 22:15:03 +07:00
* Basic Usage
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
2018-05-04 02:58:52 +07:00
zk = ZK('192.168.1.201', port=4370, timeout=5)
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
```
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
```
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
```
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
```
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])
```
2016-05-26 12:51:04 +07:00
2016-06-17 13:54:05 +07:00
* Attendance Record
2018-05-04 02:58:52 +07:00
```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-04 02:58:52 +07:00
Test Machine
```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
-f, --force-udp Force UDP communication
-t, --templates Get templates / fingers
-r, --records Get attendance records
-u, --updatetime Update Date/Time
-l, --live-capture Live Event Capture
-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)
```
2016-06-17 15:02:01 +07:00
# Related Project
2016-06-23 16:22:13 +07:00
* [zkcluster](https://github.com/fananimi/zkcluster/ "zkcluster project") is a django apps to manage multiple fingerprint devices.
* [Driji](https://github.com/fananimi/driji/ "Driji project") is an attendance apps based fingerprint for school
2016-06-17 15:02:01 +07:00
2016-05-26 12:55:18 +07:00
# Todo
2016-05-26 22:15:03 +07:00
* Create better documentation
2016-05-26 12:55:18 +07:00
* Finger template downloader & uploader
* HTTP Rest api
2016-05-26 22:15:03 +07:00
* Create real time api (if possible)
2016-06-17 13:54:05 +07:00
* and much more ...