---
title: "Biometric Attendance Sync \u2014 Setup Guide"
space: "Biometric Attendance Sync \u2014 Setup Guide"
url: "https://support.aakvatech.com/biometric-attendance-sync-setup-guide/biometric-attendance-sync-\u2014-setup-guide"
updated: "2026-05-06"
---

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**


| **Problem**                   | **Solution**                                   |
| ----------------------------- | ---------------------------------------------- |
| ModuleNotFoundError: pyzk     | Use full venv python path, not system python3  |
| Connection timeout            | Check IP and test: `nc -zv 192.168.1.100 4370` |
| Employee not found            | Set `attendance_device_id` on Employee record  |
| API auth failed               | Regenerate API keys in ERPNext User settings   |
| Works manually, fails in cron | Use absolute paths — cron has no venv or PATH  |