Seamless Biometric Attendance Integration with ERPNext using Ubuntu Subsystem (WSL) – Tested & Working Method

This guide explains how to set up the Biometric Attendance Sync Tool inside Ubuntu Subsystem (WSL) on Windows, configure it for ERPNext, and automate it using Windows Task Scheduler.

This method is tested and working in real client setups.

1. Prerequisites

Before starting, make sure you have:

1. Windows 10/11 with Windows Subsystem for Linux (WSL) enabled
2. Ubuntu 20.04 LTS installed from the Microsoft Store
3. A biometric device connected to the same network as your Windows machine
4. ERPNext API Key & Secret (user must have HR permissions)
5. Python 3.8 installed in the Ubuntu Subsystem

2. Install Ubuntu Subsystem & Python

Refer to the following to install the Ubuntu subsystem:

Reference Video 1

Reference Video 2

Open Ubuntu and run:

sudo apt update
sudo apt install software-properties-common
sudo apt install python3.8
sudo apt install python3-pip
python -m pip install pip

3. Install the Biometric Attendance Sync Tool

cd ~
git clone https://github.com/frappe/biometric-attendance-sync-tool
cd biometric-attendance-sync-tool
pip install -r requirements.txt
pip install pickledb pyzk PyQt5

4. Configure local_config.py

Inside the biometric-attendance-sync-tool folder:

Copy the template config file:

cp local_config.template.py local_config.py

Edit the file:

nano local_config.py

Update with your ERPNext and device details:

# =============================# ERPNext related configs# =============================
ERPNEXT_API_KEY = '<YOUR_ERP_NEXT_API_KEY>'        # e.g. from My Profile → API Access
ERPNEXT_API_SECRET = '<YOUR_ERP_NEXT_API_SECRET>'  # Keep this secure!
ERPNEXT_URL = 'http://erp.yourdomain.com'          # Public or LAN URL to ERPNext
ERPNEXT_VERSION = 15                               # 14 or 15 based on your ERPNext version# =============================# Operational configs# =============================
PULL_FREQUENCY = 60         # in minutes (adjust as per requirement)
LOGS_DIRECTORY = 'logs'     # Folder where logs will be stored
IMPORT_START_DATE = None    # format: 'YYYYMMDD' — leave None for current date# =============================# Device configurations# =============================
devices = [
    {
        'device_id': 'office_main',
        'ip': '192.168.1.50',        # Replace with actual device IP'punch_direction': None,     # Optional: 'IN' / 'OUT' / None'clear_from_device_on_fetch': False,
        'latitude': 12.9716,         # Optional GPS latitude'longitude': 77.5946         # Optional GPS longitude
    },
    {
        'device_id': 'factory_gate',
        'ip': '192.168.1.51',        # Replace with actual device IP'punch_direction': None,
        'clear_from_device_on_fetch': False,
        'latitude': 12.9716,   # Optional GPS latitude
        'longitude': 77.5946   # Optional GPS longitude
    }
]

# =============================# Mapping devices to ERPNext Shift Types# =============================
shift_type_device_mapping = [
    {
        'shift_type_name': ['Morning Shift', 'Night Shift'],  #Add your shift types 
        'related_device_id': ['office_main', 'factory_gate']  #Add your device ID 
    }
]

Save → CTRL+O, Exit → CTRL+X

5. Create the .sh Script

nano hello.sh

Add:

#!/bin/shcd /home/administrator/biometric-attendance-sync-tool
python3 erpnext_sync.py

Make it executable:

chmod +x hello.sh

6. Test Manually

Run:

sh hello.sh

If successful, a logs A folder will be created automatically with:

7. Automate with Windows Task Scheduler

Follow these steps to add a schedular :

1. Open Task Scheduler → Create Basic Task
2. Name: Biometric Sync
3. Trigger: Every 5 minutes (or at startup)
4. Action: Start a program
5. Program/script:

C:\Windows\System32\wsl.exe

1. Add arguments:

sh /home/administrator/biometric-attendance-sync-tool/hello.sh

1. Properties: Enable:
2. Run whether logged in or not
3. Run with the highest privileges
4. Save the task.

8. Troubleshooting

Common issues & solutions:

9. Lessons Learned

I first tried setting this up remotely via AnyDesk, but faced:

1. Client’s availability issues
2. Device offline during remote session
3. Missed testing windows

Solution: On-site visit, local connectivity testing, and immediate automation setup.

10. Conclusion

Using Ubuntu Subsystem + Task Scheduler is a stable and reliable method for syncing biometric attendance into ERPNext.

Once set up, it:

1. Runs automatically on schedule
2. Logs all activities for review
3. Eliminates manual punch imports

If you want, I can add a flow diagram showing:

Biometric Device → WSL Python Script → ERPNext API → Checkins

…so the client immediately understands the data flow without reading all the text.