Biometric Attendance Machines Integration
ZKTeco biometric attendance integration for Odoo/Viindoo
Connect - sync - automate all attendance logs from ZKTeco devices into your HR system. Manage device users, support multiple devices - locations - timezones, keep safe audit trails and long term retention.
Supports TCP - UDP - optional "iCloud" push mode for devices. Streamline check-in workflows, reduce manual entry, and get payroll ready.
Key features
A production-ready attendance integration framework for ZKTeco devices. Flexible connectivity, safe synchronization, scalable across devices - locations - timezones, with permanent storage in Odoo/Viindoo.
Flexible connectivity
Connect via IP or domain using TCP or UDP. Optional "iCloud" mode lets devices push logs into the app.
On-device user management
Import - remove users, auto-map to employee profiles in Odoo. Track in - out - overtime states.
Multi-device - multi-site
Operate many ZKTeco devices across multiple locations and timezones, consolidate logs centrally.
Automated synchronization
Schedule or run manual pulls. Auto cleanup on device per configuration. Permanent storage in Odoo.
Secure connection
Password-based authentication when pairing devices with Odoo/Viindoo. Prevent unauthorized access and preserve integrity.
Broad device compatibility
Compatible with many ZKTeco and Ronald Jack models. Tested with SpeedFace, Uface, K-series, iFace, iClock, and more (see below).
Key benefits
Reduce manual entry, minimize errors, and shorten time-to-payroll.
Unify in - out - overtime data with HR records and Odoo Attendance.
Enable workforce analytics, support payroll and compliance needs.
Leverage existing devices, simple configuration, lower operating cost.
Connect devices
- Connect using IP or domain via TCP - UDP.
- Optional "iCloud" mode for device-to-app push.
- Secure with connection password to harden access.
User Management on Attendance Machines
- Support multiple ZKTeco attendance machines at different locations, time zones at various locations.
- Import - remove users to devices from employee lists.
- Automatically map users on attendance machines with employee profiles in Odoo.
- Support multiple attendance statuses (e.g., Check-in, Check-out, Start Overtime, End Overtime, etc.).
Attendance Data
- Automatically download attendance data from machines and synchronize it with the HR system in Odoo (users can configure automatic or manual synchronization).
- Automatically clear attendance data from machines according to the configuration or manually clear it.
- Permanently store attendance data in Odoo/Viindoo
"Icloud" option for Odoo 17+
Introduce ADSM iCloud Feature
Since Odoo 17, new feature was added call 'Icloud' to allow machine to push data into software. Before we only can get data from the machine, some client might get trouble when configure the machine because it need static IP and Modem configuration.
With this feature (optional, by default we still use either UDP or TCP one, we encourage to use this icloud option as the last one only because it has some security risk) you only need to configure in the machine by following instruction (this instruction use SpeedFace-H5L[P], but don't worry other machines have the same one):
Quick Guide
(this instruction use SpeedFace-H5L[P], but don't worry other machines have the same one):
- Go to 'Comm' setting of the machine
-
Select Cloud Server Setting and you will see some configuration:
- Enable Domain Name: enable this if you going to use domain name
- Server Address: enter IP address like 192.168.1.1 (check this by going to internet setting) or your domain name like example.viindoo.com
- Server Port: If it hosted online, probably '443' is fine or any port that your server has. In the local environment it should be the port to run Odoo config (8069 for example)
- Enable Proxy Server (Some machines have): activate Proxy, after that you will need to specify Server IP and Port of the proxy one
- HTTPS (Some machines have): Support https when pushing data, need to activate this unless you use local environment to develop. Note this, some machines might not have this, in that case it is necessary to change the nginx settings to prevent redirection to https for routers related to machines.
- Then go to machine manager to create a new one with protocol 'icloud', we have chosen the best setting for you so you do not need to do that
- Fill the 'Serial Number' (In the machine, go to 'System Info' → 'Device Info' to see the Serial Number)
- Hit button 'Upload Setting' to push setting into the machine
- From now on, your machine is ready to push data into the software
Supported Devices
Supports various models of ZKTeco machine.
Fully tested with the following devices:
- ZKTeco SENSEFACE 7A
- RONALD JACK B3-C
- ZKTeco K50
- ZKTeco MA300
- ZKTeco T4C
- ZKTeco G3
- RONALD JACK iClock260
- ZKTeco K14
- iFace702
- Uface 800 (worked with finger and face)
- ZKTeco K40
- ZKTeco K20
- ZKTeco U580
- ZKTeco F18
- ZKTeco F19
- iFace402/ID
- iFace800
- iClock3000
- iClock880-H
- iclock 700
- Ronald Jack T8
- Ronald jack 1000Plus
- ZKTeco MB20
- ZKteco IN0A-1
- Uface 800
- SpeedFace V5L
- Speedface H5L(P)
- VF680
- RSP10k1
- Uface 302
- ... (please advise us your machines. Tks!)
Devices reported working by customers:
- SpeedPalm-V5L
- SenseFace 7
- SenseFace 4
- SenseFace 3
- SenseFace 2A
- MB series
- F21
- F22
- SF400
- uFace series
- SilkBio series
- IN05 & IN05-A
- X628-C
- U300-C
- U260-C
- iClock680
- iClock360
- UA series
- WL series
- P series
- EFace10
- ... (Support devices with ADMS feature)
Watch Video Tutorial
Open the video introduction for ZKTeco biometric attendance integration odoo/Viindoo
Read User Guide
Explore Live Demo
Need a help for this module?
If you have questions, need any help, or have a customizations request, please contact us
Pre-Sales Question
- The module you are exploring: name and version
- Edition in use: CE, EE
- Your issue: trial, payment, installation, etc.
- Provide screenshots or videos, if available.
Support
- Your order number and attach a screenshot
- A description of the issue you're experiencing
- Your expectations for resolving the situation
- Include images or videos that replicate the issue
Technical requirements
Compatibility depends on firmware - protocol - distribution region. Test on a demo environment before rolling out to production.
Changelog
18.1.1.7 - compatibility and stability updates
- Improved TCP - UDP connection stability.
- Optimized sync for multiple attendance states.
- Updated guidance for the optional "iCloud" configuration.
Others info
Credit
Tons of thanks to Fananimi for his excellent pyzk library .
We took inspiration from it and extended it with additional features such as machine information, Python 3 support, and TCP/IP support, before integrating it into Odoo through this powerful Attendance Machine application.
Known Issues
To make this module work perfectly, your device must be accessible via the internet (if using an online platform like odoo.sh or a self-hosted instance).
Don't worry if the device is connected but still cannot download data, it could be one of following reason:
- Wrong device mode (we support mode call Time Attendance other mode like Access Control will not work)
- Lacking device configuration (by default some device will ignore the in/out checking stuff therefore we can not download your attendance data).
For troubleshooting, please contact us at https://viindoo.com/ticket/team/8 .
Who should use this
Companies with many devices
Operate multiple checkpoints and need centralized synchronization.
Large workforce
Lower manual workload, improve accuracy, stay payroll ready.
Compliance heavy environments
Require consistent, auditable attendance trails stored safely.
Installation
- Navigate to Apps;
- Find with keyword to_attendance_device;
- Press Install.
Usages
Instruction video: Biometric Attendance Machines Integration
Concepts
Machine Position is a model to store locations where your attendance machines are installed. Each location consists of the following information:
- Name: the name of the location.
- Time zone: the time zone of the location. This is to support attendance logs at multiple locations in different time zones.
Attendance State is a model to store states of attendance activity that can be defined by users. States could be Check-in, Check-out, Overtime Check-in, Overtime Start, etc. Please navigate to Attendance > Configuration > Attendance Status to see the list of default states that were created during the installation of this application.
Attendance Activity is a model that classifies attendance in activities such as Normal Working, Overtime, etc. Navigate to Attendance > Configuration > Attendance Activity to see the list of default activities that were created during the installation of this application. Each Attendance Activity is defined with the following:
- Name: the unique name of the activity.
- Attendance Status: list of the attendance states that are applied to this activity.
Machine User is a model that stores all the machines' users in your Odoo instance and map such users with Employees in the system. Each Machine User consists of (but is not limited to) the following information:
- Name: the name of the user stored in the machine.
- Attendance Machine: the machine to which this user belongs.
- UID: The ID (technical field) of the user in the machine storage, which is usually invisible at the machine's interface/screen.
- ID Number: the ID Number of the user/employee in the machine storage. It is also known as "User ID" in some machines.
- Employee: the employee that is mapped with this user. If you have multiple machines, each employee may map with multiple corresponding machine users.
User Attendance is a model that stores all the attendance records downloaded from all the machines. In other words,it is a central database of attendance logs for all your machines. This log will be used as the base to create HR Attendance. During that creation, the software will also check for the validity of the attendance to ensure that the HR Attendance data is clean and valid.
HR Attendance is a model offered by Odoo's standard module hr_attendance and is extended to have the following fields:
- Check-in: the time of check-in.
- Check-out: the time of check-out.
- Employee: the related employee.
- Checkin Machine: the attendance machine that logged the check-in.
- Checkout Machine: the attendance machine that logged the check-out.
HR Attendance records are created automatically and periodically by the Scheduled Action named Synchronize attendances schedule.
Employee is a model in Odoo that is extended for the additional following information:
- Unmapped Machines: to show the list of attendance machines that have not to gotten this employee mapped.
- Created from Machine: to indicate if the employee profile was created from a machine (e.g. Download users -> auto create employee-> auto map them). This will helps you filter your employees to see ones that were or were not created from machines.
Attendance Machine is a model that stores all the information of an attendance machine. It also provides a lot of tools such as:
- Upload Users: to upload all your employee to an attendance machine (e.g a new and fresh machine).
- Download Users: to download all the machine's users' data into odoo and map those users with employees (if an auto mapping is set).
- Map Employee: to map machine users with employees in your Odoo instance.
- Check connection: to check if your Odoo instance could connect to the machine.
- Get Machine Info: to get the most important information about the machine (e.g. OEM Vendor, Machine Name, Serial Number, Firmware Version, etc).
- Download Attendance: to download manually all the attendance data from the machine into your Odoo database, although this could be done automatically by the scheduled action named "Download attendances scheduler".
- Restart: to restart the machine.
- Clear Data: this is to empty your data. It is a very DANGEROUS function and is visible to and accessible by the HR Attendance Manager only.
- And many more...
Setup a new attendance machine
- Navigate to Attendances > Attendance Machines > Machines Manager.
- Click Create button to open a machine form view.
- Input the name of the machine (optional).
- Enter the IP of the machine. It must be accessible from your Odoo server. If your Odoo instance is on the Internet while the machine is in your office, behind a router, please ensure that port forwarding is enabled and the machine's network configuration is properly set to allow accessing your machine from outside via the Internet. You may need to refer to your router manufacturers for documentation on how to do NAT/port forwarding.
- Port: the port of the machine. It is usually 4370.
- Protocol: which is either UDP or TCP. Most modern machines nowadays support both. TCP is more reliable but may not be supported by a behind-a-decade machine.
- Location: the location where the machine is physically installed. The time zone of the location must be correct.
- You may want to see other options (e.g. Map Employee Before Download, Time zone, Generate Employees During Mapping, etc).
- Hit the Save button to create a new machine in your Odoo.
- Hit Check Connection to test if the connection works. If it did not work, please troubleshoot for the following cases:
- Check network settings inside the physical machine: IP, Gateway, Port, Net Mask.
- Check your firewall/router to see if it blocks connection from your Odoo instance.
- Try on switching between UDP and TCP.
Refer to the article Biometric attendance device intergration.
Map Machines Users and Employees
- If this is a fresh machine without any data stored inside:
- Click Upload users.
- If this is not a fresh machine:
- You may want to clear data before doing step 10.1 mentioned above.
- Or, you may want to Download Users and map them to an existing employee or create a new employee accordingly.
- Validate the result:
- All Machine Users should link to a corresponding employee.
- No unmapped employees are shown on the machine form view.
Refer to the article Link Attendance device users with employees in Viindoo system.
- Test Attendance Data download and synchronization:
- Do some check-in and check-out at the physical machine:
- Wait for seconds between check-in and check-out.
- Try some wrong actions: check-in a few times before checking-out.
- Come back to the machine form view in Odoo:
- Hit Download Attendance Data and wait for its completion. For just a few attendance records, it may take only a couple of seconds even if your device is located in a country other than the Odoo instance's.
- Validate the result:
- Navigate to Attendances > Attendance Machines > Attendance Data to validate if the attendance log is recorded there.
- If found, you are done now. You can continue with the following steps to bring the new machine into production:
- Clear the sample attendance data you have created:
- Navigate to Attendances > Attendance Machines > Attendance Data, find and delete those sample records.
- Navigate to Attendances > Attendance Machines > Synchronize and hit Clear Attendance Data button.
- Hit the Confirmed state in the header of the machine form view. If you don't do it, the schedulers will ignore the machine during their runs.
- Clear the sample attendance data you have created:
- If not found, there should be some trouble that needs further investigation:
- Check the connection.
- Try to get the machine information.
- Check the work codes of the machine if they match the ones specified in the "Attendance Status Codes" table in the machine form view.
- Contact the author of the "Attendance Machine" application if you could not solve the problem yourself.
- Do some check-in and check-out at the physical machine:
Set up for a new Employee
- Create an employee as usual.
- Hit the Action button in the header area of the employee form view to find the menu item "Upload to Attendance Machine" in the dropped-down list.
- Select the machine(s) that will be used for this employee then hit the Upload Employees button.
- You can also do mass upload by selecting employees from the employee list view. Or go to the machines.
How the automation works
There are two scheduled actions:
- Download attendances scheduler: by default, it runs every 30 minutes to:
- Download the attendance log/data from all your machines that are set in Confirmed status. Machines that are not in this status will be ignored.
- Create User Attendance records in your Odoo database.
- Depending on the configuration you made on the machines, it may also do the following automatically:
- Create new employees and map with the corresponding machine users if new users are found in the machines.
- Clear the attendance data from the machine if it's time to do it.
- Synchronize attendances scheduler: by default, it runs every 30 minutes to:
- Find the valid attendance in the user attendance log.
- Create HR Attendance records from such the log.
This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file).
You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one).
It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software.
The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.