Connection ZKTeco with ERPNext

@luthfullah were you successful in setting up your ZKTeco to connect to ERPNext? Can you help me with a step-by-step guide? I’ve tried but seem to be encountering series of errors.

UPDATE: I seem to have successfully configured the device and the script but when i enter python3 push_to_erpnext.py what i see is

Service Running…

but nothing happens in ERPNext and it just stays that way. Could i have done something wrong?

Also, @karthikeyan5 if you’re one of the developers who built the app, do you mind taking a look at PyQt5 dependency? it seems to be breaking the requirements.txt setup process. I had to manually install v5.14 in order to get past the error.

If you are able to see this you probably have set up the script correctly… please take a look at the logs directory and see what is the status there. by default you can find this in the same directory as you script.

thanks for reporting this… yes there have been recent changes that have been pushed to enable an UI application for this script… this bug probably crept in with it… can you please create an issue in the github repo for this?

@karthikeyan5 Thanks for the tip. I checked the error.log file and found this error:

2020-03-31 18:53:03,001 ERROR exception when calling pull_process_and_push_data function for device{“device_id”: “attendance”, “ip”: “192.168.1.30”, “punch_direction”: null, “clear_from_device_on_fetch”: false}
Traceback (most recent call last):
File “/usr/local/lib/python3.6/dist-packages/zk/base.py”, line 249, in __send_command
self.__tcp_data_recv = self.__sock.recv(response_size + 8)
socket.timeout: timed out

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File “push_to_erpnext.py”, line 138, in get_all_attendance_from_device
conn = zk.connect()
File “/usr/local/lib/python3.6/dist-packages/zk/base.py”, line 373, in connect
cmd_response = self.__send_command(const.CMD_CONNECT)
File “/usr/local/lib/python3.6/dist-packages/zk/base.py”, line 260, in __send_command
raise ZKNetworkError(str(e))
zk.exception.ZKNetworkError: timed out

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File “push_to_erpnext.py”, line 51, in main
pull_process_and_push_data(device, device_attendance_logs)
File “push_to_erpnext.py”, line 78, in pull_process_and_push_data
device_attendance_logs = get_all_attendance_from_device(device[‘ip’], device_id=device[‘device_id’], clear_from_device_on_fetch=device[‘clear_from_device_on_fetch’])
File “push_to_erpnext.py”, line 159, in get_all_attendance_from_device
raise Exception(‘Device fetch failed.’)
Exception: Device fetch failed.

I can ping the device successfully in spite of this error. What could be wrong? My device is Zkteco MA300.

i have verified that your device is compatable.
if you are sure that you can ping the device… there is one other thing that you can check - the port:

  1. make sure the connection port is 4370 on your device (because this is hardcoded in the script… and is the default for all devices.)
  2. check if that port is not blocked on you network.

@karthikeyan5 Thanks for your reply. First i checked the device to make sure it’s set to port 4370 and confirmed it is:

Then i checked to make sure the port is open in my network:

(venv) flexy@flexy-VM:~/push-biometric-erpnext$ telnet 192.168.1.30 4370
Trying 192.168.1.30…
Connected to 192.168.1.30.
Escape character is ‘^]’.
^]
telnet> q
Connection closed.
(venv) flexy@flexy-VM:~/push-biometric-erpnext$ nc -vz 192.168.1.30 4370
Connection to 192.168.1.30 4370 port [tcp/*] succeeded!
(venv) flexy@flexy-VM:~/push-biometric-erpnext$
As you can see i was able to telnet to the device using the port and confirmed that the port is open. Yet i still got the same error when i ran python3 push_to_erpnext.py.

My successful setup connect ZKTeco with ERPnext V12 Ubuntu 18.04.4

  1. this link i used to install erpnext V12 ubuntu 18.04.4 ubuntu How to install erpnext version 12 on ubuntu 18.04 - #60 by ssemotom
  2. Clone this repository using - cd frappe-bench then git clone GitHub - frappe/biometric-attendance-sync-tool: A simple tool for syncing Biometric Attendance data with your ERPNext server
  3. sudo apt-get install python3-venv
  4. sudo -H pip install -r requirements.txt
  5. cd push-biometric-erpnext then run sudo nano local_config.py.template
  6. generate api secret : profile → my seting → API ACCESS → generate key
  7. Save API Secret: 4aart49c1efhb47 - then refresh page open api access copy api key : fe14cdc19ed92tg
  8. edit local_ sudo nano config.py.template
# ERPNext related configs 
ERPNEXT_API_KEY = 'fe14cdc19ed92tg' 
ERPNEXT_API_SECRET = '4aart49c1efhb47' 
ERPNEXT_URL = 'http://10.0.0.110' 
# operational configs 
PULL_FREQUENCY = 1 # in minutes  # for testing,  i suggest set it 1 min. then if working set it back to 10  to 20 min
LOGS_DIRECTORY = 'logs' # logs of this script is stored in this directory 
IMPORT_START_DATE = None # format: '20190501' 
# Biometric device configs (all keys mandatory) 
    #- device_id - must be unique, strictly alphanumerical chars only. no space allowed. 
    #- ip - device IP Address 
    #- punch_direction - 'IN'/'OUT'/'AUTO'/None 
    #- clear_from_device_on_fetch: if set to true then attendance is deleted after fetch is success$ 
                                    #(Caution: this feature can lead to data loss if used carelessl$ 
devices = [ 
    {'device_id':'iface7','ip':'10.0.0.96', 'punch_direction': 'AUTO', 'clear_from_device_on_fetch': False}, 
#device id :  name it what ever name you want, ip same ip you set on device , punch derection set to AUTO 
#    {'device_id':'test_2','ip':'192.168.2.209', 'punch_direction': None, 'clear_from_device_on_fetc$ 
] 
# Configs updating sync timestamp in the Shift Type DocType 
shift_type_device_mapping = [ 
    {'shift_type_name': ['Shift1','shift2'], 'related_device_id': ['iface7']} 
#shift name must be same on erpnext, in my case shift have 2 type
]

then "ctrl O " save as local_config.py
10. create employee list same as your device has :
- eg: in erpnext has list 2 employee, you device should have 2 employee register
11. set employee ID same as device :
- human-resource > employee > Employee name > Attendance Device ID (Biometric/RF tag ID). in my case employee 1 id is 1 so device for employee 1 is 1, employee 2 id is 2… and so on .Both id must be same between erpnext and device.
12. create shift type : related link about shift : Shift Management
- employee > Shift Management > Shift types
- shift name must same as local_config.py . in my case shift1 and shift2 in my case 2 different shift periods time
- tick Enable Auto Attendance
- Auto auto attendance setting :
Determine Check-in and Check-out -->>>>> Alternating entries as IN and OUT during the same shift
Working Hours Calculation Based On -->>>> Every Valid Check-in and Check-out
- set Process Attendance After date —> set today. this will set auto calculate attendance when shift is done on that day.
- then click mark auto attendance .
13. Run this script using python3 push_to_erpnext.py
14. check error log if accrue
- tail -f /frappe-bench/push-biometric-erpnext/logs/error.log
15. try check punch in on device then check employee check in at
- Human Resources > Employee Checkin
16. then if everything is working then set “PULL_FREQUENCY = 1” to 10 minute

7 Likes

@Mohd_Rizal_sharif Thanks for the step-by-step setup instruction. Simplified a lot. Although it did not account for pyqt5 installation failure when you run pip install -r requirements.txt.

My ongoing challenge is this error:

2020-04-06 14:03:57,130 ERROR exception when calling pull_process_and_push_data function for device{“device_id”: “Attendance”, “ip”: “192.168.1.30”, “punch_direction”: null, “clear_from_device_on_fetch”: false}
Traceback (most recent call last):
File “/usr/local/lib/python3.6/dist-packages/zk/base.py”, line 249, in __send_command
self.__tcp_data_recv = self.__sock.recv(response_size + 8)
socket.timeout: timed out

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File “push_to_erpnext.py”, line 138, in get_all_attendance_from_device
conn = zk.connect()
File “/usr/local/lib/python3.6/dist-packages/zk/base.py”, line 373, in connect
cmd_response = self.__send_command(const.CMD_CONNECT)
File “/usr/local/lib/python3.6/dist-packages/zk/base.py”, line 260, in __send_command
raise ZKNetworkError(str(e))
zk.exception.ZKNetworkError: timed out

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File “push_to_erpnext.py”, line 51, in main
pull_process_and_push_data(device, device_attendance_logs)
File “push_to_erpnext.py”, line 78, in pull_process_and_push_data
device_attendance_logs = get_all_attendance_from_device(device[‘ip’], device_id=device[‘device_id’], clear_from_device_on_fetch=device[‘clear_from_device_on_fetch’])
File “push_to_erpnext.py”, line 159, in get_all_attendance_from_device
raise Exception(‘Device fetch failed.’)
Exception: Device fetch failed.

I don’t know why this error occurs or how to fix it. Everything else seems fine. @karthikeyan5 mentioned above that Zkteco MA300 is supported so i don’t know why socket times out when it tries to get attendance from device.

I will really appreciate any help i can get.

@flexy2ky are you using VM? , virtual box ? try check VM network setting, i used network “bridge Adapter” , try reset your device remove device password and clear all punch log on your device.

this step will check if device properly connect or not

run command

cd frappe-bench
git clone GitHub - karthikeyan5/pyzk: Unofficial library of zkteco fingerprint attendance machine

when its done. run command

cd pyzk
python3 test_machine.py -a 192.168.1.30 -l

in my setup i get ouput like this

erpnext@lb:~/frappe-bench/pyzk$ python3  test_machine.py -a 10.0.0.96 -l

Connecting to device …
SDK build=1 : True
Disabling device …
ExtendFmt : 1
UsrExtFmt : 1
Face FunOn : 1
Face Version : 7
Finger Version : 10
Old Firm compat : None
IP:10.0.0.96 mask:255.255.255.0 gateway:10.0.0.1
Time : 2020-04-06 23:19:01
WRN: TIME IS NOT SYNC!!! (local: 2020-04-07 00:17:49) use command -u to update
Firmware Version : Ver 6.60 Apr 22 2016
Platform : ZEM600_TFT
DeviceName : iFace7
Pin Width : 9
Serial Number : 6641161700782
MAC: 00:17:61:12:87:AB

— sizes & capacity —
ZK tcp://10.0.0.96:4370 users[72]:7/10000 fingers:6/2000, records:11/100000 faces:1/1500

— Get User —
took 0.406[s]
→ UID #1 Name : rizal Privilege : Admin-14
Group ID : User ID : 1 Password : Card : 0
→ UID #2 Name : firas Privilege : User
Group ID : User ID : 2 Password : Card : 0
→ UID #3 Name : firdaus Privilege : User
Group ID : User ID : 3 Password : Card : 0
→ UID #4 Name : Dhia Privilege : User
Group ID : User ID : 4 Password : Card : 0
→ UID #5 Name : Harraz Privilege : User
Group ID : User ID : 5 Password : Card : 0
→ UID #6 Name : Luqman Privilege : User
Group ID : User ID : 6 Password : Card : 0
→ UID #7 Name : zul Privilege : Admin-14
Group ID : User ID : 7 Password : Card : 0
took 0.406[s]

— sizes & capacity —
ZK tcp://10.0.0.96:4370 users[72]:7/10000 fingers:6/2000, records:11/100000 faces:1/1500

— Live Capture! (press ctrl+C to break) —

then try punch in to your device , you should get respond like mine maybe?

@Mohd_Rizal_sharif Thanks for your reply and your help to troubleshoot my issue.

I reset my device and cleared all data and i ran the test_machine.py as directed in your post above but i still go the connection timeout erroro:

flexy@Biometrics:~/pyzk$ python3 test_machine.py -a 192.168.1.30 -l
Connecting to device …
Process terminate : timed out
Error: <class ‘zk.exception.ZKNetworkError’>

Traceback (most recent call last):
File “/home/flexy/pyzk/zk/base.py”, line 249, in __send_command
self.__tcp_data_recv = self.__sock.recv(response_size + 8)
socket.timeout: timed out

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
File “test_machine.py”, line 67, in
conn = zk.connect()
File “/home/flexy/pyzk/zk/base.py”, line 373, in connect
cmd_response = self.__send_command(const.CMD_CONNECT)
File “/home/flexy/pyzk/zk/base.py”, line 260, in __send_command
raise ZKNetworkError(str(e))
zk.exception.ZKNetworkError: timed out

flexy@Biometrics:~/pyzk$

I don’t know what else to check.

My device is ZKteco MA300 Firmware version 6.62.

its seem like you have connection problem, are you install erpnext on Virtual Box?. what port your device used?

try this put "-f ". force connection UDP
**> ## ~/pyzk$ python3 test_machine.py -f -a 192.168.1.30 -p 4370 -l**

$ python3 test_machine.py -h ← help for more idea to troubleshoot

my device use port 4370 without password . below are ZK Access 3.5.5.1

.

@Mohd_Rizal_sharif I really appreciate your interest in my predicament. Finally some progress to report!

I ran this ~/pyzk$ python3 test_machine.py -f -a 192.168.1.30 -p 4370 -l to force connection to UDP as you recommended and i was able to obtain this report:

flexy@Biometrics:~/pyzk$ sudo python3 test_machine.py -f -a 192.168.1.30 -p 4370 -l
Connecting to device …
SDK build=1 : True
Disabling device …
ExtendFmt : 0
UsrExtFmt : 0
Face FunOn : 0
Face Version : 0
Finger Version : 10
Old Firm compat : 0
IP:192.168.1.30 mask:255.255.255.0 gateway:192.168.1.1
Time : 2020-04-07 08:41:31
Firmware Version : Ver 6.62 Dec 7 2015
Platform : ZEM560
DeviceName :
Pin Width : 9
Serial Number : AHGU194360028
MAC: 00:17:61:11:B8:A0

— sizes & capacity —
ZK udp://192.168.1.30:4370 users[28]:1/10000 fingers:0/1500, records:0/100000 faces:0/0

— Get User —
took 0.009[s]
→ UID #1 Name : NN-1 Privilege : User
Group ID : 0 User ID : 1 Password : Card : 2736013
took 0.009[s]

— sizes & capacity —
ZK udp://192.168.1.30:4370 users[28]:1/10000 fingers:0/1500, records:0/100000 faces:0/0

— Live Capture! (press ctrl+C to break) —
timeout 0
timeout 0
timeout 0
timeout 0
timeout 0
ATT 0: uid: 1, user_id: 1 t: 2020-04-07 08:42:28, s:2 p:0
timeout 0
timeout 0
timeout 0
ATT 0: uid: 1, user_id: 1 t: 2020-04-07 08:43:03, s:2 p:0
timeout 0
^C
— capture End!—

Enabling device …
ok bye!

flexy@Biometrics:~/pyzk$ ^C
flexy@Biometrics:~/pyzk$

My initial installation was on Hyper-V but i switched to Virtualbox. I was still getting the same error even in Virtualbox.

This my device configuration:


There’s no password and following your earlier advice i wiped off all data on the device. How can i get this connection to work in production mode?

@flexy2ky hi ,maybe your windows firewall / antivirus / router / try use other port / . i have 2 device MB10 and iface7 both are support. hope it s help you.

@Mohd_Rizal_sharif I have checked everything, opened all ports on my firewall and router but connection is still failing but when i do the test using the test_machine.py i am able to connect.

@karthikeyan5 @Mohd_Rizal_sharif After much research i found that my firmware may not be compatible. Although MA300 is supported but the firmware version is 6.62 while the supported version is 6.60. Anyone know how i can downgrade the firmware or if it’s at all possible? I would appreciate any help here

Just got caught up with the thread. And I personally have experience with the MA300 devices.

To put simply there are 2 types of devices from ZKTeco. 1st, RGB, 2nd, black and white (our definition). MA300 is one of the black and white devices, or simply “dumb”-er devices. Devices from ZKTeco that do not have built in screen are those black and white types. Hence for some reason they do not support the default API’s of ZK softwares. The device is really beautiful and well built, but after about a week of trying to connect it with our WordPress HR software we gave up and went with 800h devices. They have built-in screen (the RGB type device), which means they fully support regular APIs. Ugly, clumsy, cheaply built, but supports PyZK.

We have many success with connecting RGB devices with all sorts of softwares such as WordPress, and specially ERPNext.

I suggest you to return the MA300 device and go for devices with built in screens.

Ohh and that firmware difference is bull crap. We have requested for all sorts of firmwares from ZKTeco directly, and they never were able to locate it internally.

@flexy2ky try wireshark used troubleshoot tcp udp Two simple filters for wireshark to analyze TCP and UDP traffic | TechRepublic. hope help you. about firmware , ZKteco not share their firmware public you should ask them.

1 Like

@Mohd_Rizal_sharif I followed your recommendation and used wireshark to troubleshoot my connection. running the normal python3 test_machine.py -a 192.168.1.30 -I does not throw any UDP result in wireshark but when i add the -f command to force UDP connection this is what i got on wireshark:
For query


and for Reply:

Unfortunately i am not good with networking so i don’t know what this network data suggests. I am wondering if it is possible to include a command in the push_to_erpnext.py script to force UDP connection as a workaround since this seems to be the issue.

1 Like

Bumping this up in case someone has an idea of what i’m going through and can recommend a solution.

@flexy2ky

Did you see the comment below from iMoshi?

@olamide_shodunke Yes i did. But unfortunately this doesn’t seem to be an option for me becaus as you know, most companies here have strict no-return policy and of course the device was with me for more than 24hrs before this post and then the lockdown happened. So my only option is to purchase another device. But i am now skeptical because there’s no guarantee it will work as the documentation for the integration app says 6.60 firmware for all supported devices and this thing is expensive here.