Biometric Attendance Sync — Setup Guide

This guide explains how to set up frappe/biometric-attendance-sync-tool on Ubuntu, schedule it with crontab, and monitor logs.

Prerequisites

Before starting, confirm the following:

• Python 3 installed — python3 --version
• Machine is on the same network as the biometric device
• ERPNext API Key and Secret ready (from User → API Access)
• attendance_device_id set on each Employee record in ERPNext

1. Installation

1. Clone the repo

cd ~
git clone https://github.com/frappe/biometric-attendance-sync-tool.git biometric
cd biometric

2. Create a virtual environment

python3 -m venv venv
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt
pip install pyzk

4. Create logs directory

mkdir -p ~/biometric/logs

2. Configure local_config.py

cp local_config.py.template local_config.py
nano local_config.py

ERPNext connection

ERPNEXT_API_KEY    = "your_api_key"
ERPNEXT_API_SECRET = "your_api_secret"
ERPNEXT_URL        = "https://erp.yourcompany.com"
ERPNEXT_VERSION    = 15

Devices

devices = [
    { "device_id": "1", "ip": "192.168.1.100", "punch_direction": "AUTO" },
    { "device_id": "2", "ip": "192.168.1.101", "punch_direction": "AUTO" },
]

Sync behaviour

PULL_FREQUENCY    = 60          # minutes
IMPORT_START_DATE = "20250101"  # YYYYMMDD

Port 4370 is used by default for all devices. This is set once and shared across all device entries.

3. Test manually first

Always run manually before adding to crontab:

cd ~/biometric
source venv/bin/activate
python3 erpnext_sync.py

You should see output like: Fetched 42 records · Pushed 38 · Skipped 4 (duplicates)

Fix any errors here before proceeding. Common causes: wrong IP, device offline, wrong API credentials.

4. Set up crontab

Cron does NOT load your .bashrc or activate your venv. You must use full absolute paths everywhere.

1. Find your Python path

which python3
# /home/aakvatech/biometric/venv/bin/python3

2. Open the crontab editor

crontab -e
# First time: select nano (press 1)

3. Add these two lines

@reboot /home/USERNAME/biometric/venv/bin/python3 /home/USERNAME/biometric/erpnext_sync.py >> /home/USERNAME/biometric/logs/sync.log 2>&1

*/60 * * * * /home/USERNAME/biometric/venv/bin/python3 /home/USERNAME/biometric/erpnext_sync.py >> /home/USERNAME/biometric/logs/sync.log 2>&1

Replace USERNAME with your actual username. Run whoami to confirm. 4. Save and exit nano

Ctrl + O   → save
Enter      → confirm
Ctrl + X   → exit

You should see: crontab: installing new crontab

If you see No modification made — you forgot to save before exiting. Repeat step 4.

5. Verify & monitor logs

| Command | Purpose | | --------------------------------------------------- | -------------------------------- | | crontab -l | Confirm crontab was saved | | tail -f ~/biometric/logs/sync.log | Watch logs live (Ctrl+C to stop) | | ps aux | grep erpnext_sync | Check if process is running | | grep CRON /var/log/syslog | grep erpnext | tail -20 | Check cron fired |

If you see No MTA installed, discarding output in syslog — your crontab line is missing >> log 2>&1. Output was going nowhere.

Troubleshooting