📡 Biometric Attendance Setup

This guide walks you through connecting a ZKTeco, eSSL, or CPPlus biometric attendance device to Ledgr. Once configured, every fingerprint/face/card punch on the device flows automatically into Ledgr's attendance grid — feeding payroll without any manual entry.

What Ledgr's biometric integration does

• LAN-pull mode — Ledgr connects to your device over your local network (TCP port 4370) using the open ZK protocol. No cloud, no third-party SaaS in the middle.
• Multi-device — front gate + factory floor + back office on different devices? Ledgr aggregates punches from all of them into one attendance record per employee per day.
• Auto-sync timer — runs every N minutes (default 60). Configurable: Off / 5 / 15 / 30 / 60 minutes.
• Mapping wizard — match each device's user IDs to your Ledgr employee records. One-time setup with auto-suggestion by name similarity.
• Manual override preserved — if you manually mark an employee absent or on-leave for a day, biometric sync respects that and won't overwrite.
• Idempotent — re-syncing the same window is safe (UNIQUE constraint on device + user + timestamp). No duplicate punches.

Compatibility

Architecture

  ┌──────────────────┐  TCP 4370  ┌──────────────────┐
  │  ZKTeco / eSSL  │ ─────────→  │ Ledgr Desktop    │
  │  Device         │             │ (your PC)        │
  │  192.168.1.50   │             │ Pulls punches    │
  └──────────────────┘             └──────────────────┘
                                          │
                                          ▼
                                ┌────────────────────┐
                                │ biometric_punches  │ raw log
                                │ table (audit)      │
                                └────────────────────┘
                                          │
                                          ▼ aggregator
                                ┌────────────────────┐
                                │ attendance table   │ daily
                                │ (employee × date)  │
                                └────────────────────┘
                                          │
                                          ▼
                                ┌────────────────────┐
                                │ Salary runs        │
                                │ (auto-feeds hours) │
                                └────────────────────┘
    

Ledgr sits on the same LAN as your device. It opens a TCP socket, authenticates with the comm password (default 0), and reads punches. Each punch is recorded in the raw biometric_punches table. The aggregator then groups punches by (employee, date), picks first-in/last-out, and writes a row to the daily attendance table.

Initial setup

1. Enable the Biometric Attendance feature

The feature is OFF by default for every niche. Turn it on:

1. Settings → Modules.
2. Find Biometric Attendance in the feature list.
3. Toggle ON.
4. Save → restart the app. The Staff & Payroll hub now shows a Biometric tab with Devices + Punches sub-tabs, plus a status pill in the top-right.

2. Network requirements

Three things must be true:

• The device has a static LAN IP (or DHCP reservation). Don't let it shuffle IPs — Ledgr saves the IP per device.
• Ledgr's PC and the device are on the same subnet. (Or routed with port 4370 reachable — VPN is fine.)
• No firewall blocks TCP outbound port 4370 from Ledgr's PC to the device.

3. Configure the device's IP

On the device's keypad / touchscreen menu (varies slightly per model):

1. Menu → Comm / Network → set IP, subnet mask, gateway.
2. Set communication password (default 0). If you've set it to non-zero, remember the value.
3. Save and restart the device.
4. Ping the device IP from Ledgr's PC to confirm it's reachable: ping 192.168.1.50

4. Add the device in Ledgr

1. Staff & Payroll → Biometric tab → Devices.
2. Click + Add Device.
3. Fill the form:
   • Name — friendly label like "Front Gate", "Factory Floor".
   • Vendor — ZKTeco / eSSL / CPPlus (drives expected behavior; doesn't change protocol).
   • IP address — e.g. 192.168.1.50.
   • Port — leave 4370 unless you've changed it on the device.
   • Comm password — leave 0 unless you've set a non-zero value.
   • Timezone — optional; defaults to company timezone.
4. Save.

5. Test the connection

From the Devices list, click the 🌐 Test icon next to your device. Ledgr opens a TCP socket and reads:

• Device name + serial number + firmware version
• Total user count + total record count on the device

Success toast: "Front Gate: connected. ZKTeco K50 (S/N 1234ABC5678) · 23 users · 1,847 punches on device."

Failure toast: "Front Gate: Connection failed: dial tcp 192.168.1.50:4370 i/o timeout." — see Troubleshooting below.

The User Mapping Wizard

Critical step. The device knows users by their device user ID (e.g. "1", "EMP-042", "100"). Ledgr knows them by employee ID. We need to map between the two.

How it works

1. From the Devices list, click the 👥 Map Users icon next to your device.
2. Ledgr fetches the list of users from the device. Each row shows: device user ID, device user name (as enrolled on the device), privilege level (Admin / User).
3. For each row, pick the matching Ledgr employee from the dropdown.
4. Click ✨ Auto-match by name at the top — Ledgr suggests matches by name similarity (handles upper/lower case, spaces, punctuation). Manually fix any wrong suggestions.
5. Click Save (N). The mapping is stored and any pending punches for those users are auto-resolved to the matched employees.

Multi-device mapping

If the same employee swipes on multiple devices (front gate, back office, factory floor), each device may have a different user ID for them. Repeat the mapping wizard per device — same employee, multiple device-user-ID rows in the mapping table. Punches from any device flow into the same employee's attendance.

Syncing punches

Manual sync

From the Devices list, click the 🔄 Sync icon next to a device. Ledgr connects, pulls all punches, and writes new ones to biometric_punches with INSERT-OR-IGNORE on the (device, user, timestamp) unique constraint — re-syncs are safe.

Result toast: "Front Gate: pulled 1,847 (12 new — 8 matched, 4 unmapped). Map remaining users."

Auto-sync timer

1. Settings → Attendance Policy.
2. Scroll to Auto-Sync Biometric Devices.
3. Pick interval: Off / 5 / 15 / 30 / 60 min. Default is 60.
4. Tick Auto-aggregate punches into attendance (recommended) — so punches automatically become attendance rows.
5. Save.

Now whenever the Staff hub is open in your Ledgr app, the timer fires every N minutes. The status pill (top-right of Staff hub) shows the latest sync result.

Status pill

While in the Staff hub:

• 🟢 Green: all devices synced OK + 0 unmapped punches + no errors
• 🟡 Amber: synced OK but ≥1 device has unmapped punches — open Devices → Map Users
• 🔴 Red: ≥1 device failed last sync — open Devices and check last_error
• ⚪ Gray: hasn't synced yet (still in 30s startup delay or interval=Off)
• Pulsing: a sync is currently running

Click the pill to expand: per-device breakdown (✓ matched count vs ✗ error message), aggregated rows + total new punches stats, unmapped warning banner, and a manual "Sync Now" button.

The aggregator (punches → attendance)

Raw punches need to become daily attendance rows. The aggregator runs:

• Automatically after each sync (when auto-aggregate is on)
• Manually via Punches view → "Aggregate to Attendance" button

How it derives status

For each (employee, date) with matched punches in the configured date range:

1. in_time = earliest punch on that date
2. out_time = latest punch (NULL if only one punch)
3. hours = decimal difference between out and in
4. status derived from your Attendance Policy:
   • Hours ≥ full_day_min_hours (default 6.0) → present
   • Hours ≥ half_day_min_hours (default 3.0) and < full → half_day
   • Single punch (no out) → present with note "Auto: missing out punch"
   • Hours < half_day_min → absent

Manual override priority

The aggregator does not overwrite attendance rows that you've manually edited (source = 'manual' or 'mixed'). If you marked an employee on-leave for a day, biometric sync respects that and skips the row. More on the manual/biometric coexistence in Staff & Payroll docs.

Attendance policy configuration

Settings → Attendance Policy controls how punches translate to status:

Common workflows

Daily morning check

1. Open Staff hub. Status pill shows current state.
2. If amber (unmapped punches): click pill → Map Users → resolve.
3. If red: click pill → see device error → ping device IP → restart device if needed.
4. Otherwise: nothing to do. Punches flow continuously while Ledgr is open.

End-of-month: prep payroll

1. Click the auto-sync pill → "Sync Now" to ensure latest punches are in.
2. Staff → Attendance → Monthly Grid → review the month.
3. Override any anomalies (employee was on approved leave, missed punch, etc.).
4. Save.
5. Staff → Payroll → Create Salary Run for the month → finalize → mark paid.

New employee onboarding

1. Enroll fingerprint/face on the device. Note the device user ID assigned (or set it manually to match employee_code).
2. In Ledgr: Staff → Employees → New Employee → save.
3. Staff → Biometric → Devices → Map Users → click 🔄 to refresh device user list.
4. Find the new device user, pick the new employee from dropdown, save.
5. From now on, their punches flow automatically.

Removing an employee from device + Ledgr

1. On the device: delete the user (their fingerprint template is wiped).
2. In Ledgr: Staff → Employees → select employee → click power icon to soft-delete.
3. Their old punches stay in biometric_punches for historical audit. Their attendance rows are preserved.

Troubleshooting

"Connection failed: i/o timeout"

• Ping the device IP. If ping fails: networking issue (cable, switch, wrong subnet).
• Confirm port 4370 is open. Try telnet 192.168.1.50 4370. If it hangs without "Connected", a firewall is blocking.
• Some routers block direct cross-VLAN traffic. Move device to same VLAN as Ledgr's PC, or set up routing.

"Connection failed: invalid checksum"

• Some older firmwares (notably ZAM170 with v6.60 build) need legacy checksum mode. Currently rustzk handles auto-detection; if you still see this, WhatsApp us with the device firmware version.

"Device authentication failed"

• You've changed the comm password on the device but not in Ledgr's device record. Edit the device, set the matching password.

Punches arriving with wrong timestamps

• Device clock has drifted. On the device: Menu → Time → set correct date/time.
• Or: Device's timezone differs from Ledgr's. In Ledgr's device settings, set the right timezone explicitly.

Punches stuck in "pending" status

• The user mapping for that device user ID isn't set. Map Users → assign the employee → click Save. Pending punches auto-resolve.

Sync runs but no new punches found

• Are employees actually punching on the device? Check on the device: Menu → Records → today.
• Confirm the device's clock is correct. Punches with future timestamps confuse the sync.

FAQ — Biometric specific

Does Ledgr need to be running 24/7 for sync to work?

Yes for auto-sync, but it's not critical. The device buffers punches in non-volatile memory (typically 100,000+ records). When you next open Ledgr, the next sync pulls everything new. So overnight downtime is fine.

Can I set up real-time push (so punches flow instantly)?

Not yet — Ledgr v1.0.3 supports LAN-pull only. Real-time push (HTTP iClock / ADMS protocol) is on the roadmap. For 90% of SMB use cases, 60-min auto-pull is fast enough.

What about multi-branch — devices across multiple offices?

Two options: (a) one Ledgr install per branch, each pulling from its local device. Or (b) Tailscale / WireGuard VPN between branches, then one central Ledgr install pulls from all branches via VPN-routed IPs.

Does Ledgr store fingerprint templates?

No. Ledgr only reads the punch log (user_id + timestamp + punch_type + verify_method). Fingerprint templates stay on the device. This means we don't need to handle biometric data privacy concerns — Ledgr stores no biometrics.

Can I sync from a cloud-hosted device (like ZKTeco BioCloud)?

Not directly. Ledgr's LAN-pull doesn't speak the BioCloud API. Workaround: export attendance from BioCloud as CSV → import via the Monthly Attendance Grid's CSV import (long format).

What if my device uses face recognition instead of fingerprint?

Doesn't matter to Ledgr — the protocol is the same. ZKTeco SpeedFace, eSSL Face, etc. all expose the same TCP 4370 protocol and same punch format. Verify method is just metadata.

Can multiple Ledgr installs sync from the same device?

Technically yes — the device handles concurrent connections. But you'd get duplicate records in two separate databases. Not recommended unless you specifically want multi-install redundancy.

How do I bulk-import historical attendance from before installing Ledgr?

Export from your old system as CSV in long format (employee_code, date, status, in_time, out_time, hours, notes). Use the Import CSV button on the Monthly Attendance Grid. Ledgr validates and inserts.