nilpatel42 · nilpatel42 · Mar 8, 2026 · Mar 8, 2026
diff --git a/README.md b/README.md
@@ -1,46 +1,66 @@
-## Biometric Integration
+# Biometric Integration
 
-The Biometric Integration (Hikvision) app seamlessly connects your Hikvision Face Terminal with the Frappe framework, enabling smooth integration for biometric attendance management. This app is designed to streamline the process of recording and syncing employee attendance data, providing real-time access control and status updates directly within your Frappe-based ERP system.
+Biometric Integration is a Frappe app that connects Hikvision biometric terminals to your HR attendance process.
 
-## Features:
+It is designed for teams that want to stop maintaining attendance in spreadsheets and move to a reliable, device-driven process with clear review points for HR.
 
-- Biometric Data Sync: Automatically syncs attendance logs from the Hikvision face terminal to Frappe.
+## What this app helps you do in real work
 
-- Digest Authentication Support: Utilizes secure Digest Authentication for API communication, ensuring safe data transfer between your face terminal and Frappe.
+In a normal office setup, employees punch in and punch out from a Hikvision terminal. This app brings those events into Frappe and organizes them as daily attendance logs per employee.
 
-- Event Time Logging: Capture and store accurate timestamps for each attendance event.
+From the settings screen, HR or IT can first test whether the terminal is reachable. This avoids wasting time on sync attempts when network credentials or device access are not correct.
 
-- Error Handling and Notifications: Sync result field captures any failures or issues, allowing administrators to monitor the success of the sync operation.
+When connection is ready, attendance can be synced for any date and time range. This is useful in two common cases:
+- daily operations, where you pull the latest records;
+- recovery situations, where you re-sync a past window after downtime.
 
-- Daily Attendance Report: Generate daily attendance reports, providing a quick overview of employee attendance, including entry and exit times.
+The app also has scheduled sync support, so recent attendance can be pulled automatically without a person manually running sync every day.
 
-- Monthly Attendance Report: Automatically generate monthly attendance summaries, including total hours worked, attendance percentage, and any missed days.
+Device communication uses digest authentication against Hikvision ISAPI endpoints. In practice, this means you can use standard device credentials while keeping communication aligned with the device API model.
 
-- Manual Attendance Entry: Allows administrators to manually log attendance for employees in case of biometric data sync failures or when employees are unable to use the biometric system.
+During sync, the app creates or updates daily attendance logs and avoids saving duplicate punches for the same time. This keeps records clean when the same period is synced more than once.
 
-## Key Points:
+If employee names are available on the device, the app can fetch and store those names in attendance logs for better readability. There is also a utility to update employee name on the device from inside the app when naming needs correction.
 
-- Simplified Attendance Management: Eliminates manual logging and provides a more reliable, automated solution for employee attendance tracking.
+## Handling exceptions (manual punches)
 
-- Enhanced Security: Uses secure communication protocols to protect sensitive data.
+Real attendance operations always include exceptions: missed punches, hardware access issues, or late corrections approved by HR.
 
-- Customizable: Adapt the app to meet the specific needs of your business or organization.
+For these cases, the app supports manual punch entry linked to Employee records. The same manual entry can be edited later (date/time replacement flow) and deleted safely, with linked punch rows removed from attendance logs.
 
-- Easy Setup: With minimal configuration required, quickly connect the Hikvision face terminal to Frappe for seamless operation.
+There is also a bulk update utility that rebuilds attendance logs from existing manual punch records. This is helpful when you need to normalize data after multiple manual corrections.
 
-## You Need
+Punches are stored with type context (Auto or Manual), so report readers can quickly understand whether an event came from device sync or HR correction.
 
-- IP Address of the Device
-
-- User Credential of the Device
+## Reporting and visibility
 
-----------------------------------------------------------------------------------
+The app includes practical reports for daily and monthly review:
 
-![Screenshot from 2025-02-13 15-08-53](https://github.com/user-attachments/assets/6034cfd8-7f36-4284-8e7b-7a5c594fd745)
-![Screenshot from 2025-02-13 15-08-02](https://github.com/user-attachments/assets/60f27d55-869e-493c-a007-a94a18f02827)
+- Biometric Daily Report: punch sequence, total worked duration, and early-leave indicator, with visibility for absent active employees.
+- Biometric Monthly Report: day-wise duration and monthly totals in both HH:MM and decimal hours.
+- Biometric Manual Punch Report: available in the app structure but currently disabled.
 
-----------------------------------------------------------------------------------
+## Data model used
 
-## Supported Devices
+Core doctypes available in this app:
+- Biometric Integration Settings (single doctype)
+- Biometric Attendance Log
+- Biometric Attendance Punch Table (child)
+- Biometric Manual Punch
+- Attendance Leave Log
+- Biometric Attendance Leave Table (child)
 
-ACT-T1331RU, ACT-T1331WRU, ACT-T1341MFRU, ACT-T1341MRU, ACT-T1331, ACT-T1331W, DS-K1A330, DS-K1A340FWX, DS-K1A340FX, DS-K1A340WX, DS-K1A340WX#India, DS-K1A340X, DS-K1T331, DS-K1T331W, DS-K1T341A, DS-K1T341AM, DS-K1T341AM-S, DS-K1T341AMF, DS-K1T341AMF-S, DS-K1T341AMHUN#India, DS-K1T341B, DS-K1T341BMI-T, DS-K1T341BMW, DS-K1T341BMWI-T, DS-K1T341CM, DS-K1T341CMF, DS-K1T341CMFW, DS-K1T341CMW, DS-K1T341M, DS-K1T342DWX, DS-K1T342DX, DS-K1T342EFWX, DS-K1T342EWX, DS-K1T342EX, DS-K1T342MFWX, DS-K1T342MFX, DS-K1T342MWX, DS-K1T342MX, DS-K1T343EFWX, DS-K1T343EFX, DS-K1T343EWX, DS-K1T343EX, DS-K1T343MFWX, DS-K1T343MFX, DS-K1T343MFX#India, DS-K1T343MWX, DS-K1T343MX, DS-K1T607, DS-K1T607E, DS-K1T607TEF#India, DS-K1T642, DS-K1T642E, DS-K1T642EF, DS-K1T642EFW, DS-K1T642EW, DS-K1T642M, DS-K1T642MF, DS-K1T642MFW, DS-K1T642MW, DS-K1T643MWX-T, DS-K1T643MX-T, DS-K1T671, DS-K1T671AM, DS-K1T671AMW, DS-K1T671BM, DS-K1T671BMF, DS-K1T671BMFW, DS-K1T671BMW, DS-K1T671BTM, DS-K1T671BTMF, DS-K1T671BTMFW, DS-K1T671BTMW, DS-K1T671M, DS-K1T671M#RUBB, DS-K1T671M#turkey, DS-K1T671M-L, DS-K1T671MF, DS-K1T671MF-L, DS-K1T671T, DS-K1T671TM, DS-K1T671TM-3XF, DS-K1T671TMF, DS-K1T671TMFW, DS-K1T671TMW, DS-K1T672, DS-K1T672DWX-T, DS-K1T672DX-T, DS-K1T672E, DS-K1T672M, DS-K1T672MW, DS-K1T673DWX, DS-K1T673DX, DS-K1T673TDGX, DS-K1T673TDWX, DS-K1T673TDX, DS-K1T680D, DS-K1T680D-E1, DS-K1T680DF, DS-K1T680DF-E1, DS-K1T680DFG, DS-K1T680DFW, DS-K1T680DG, DS-K1T680DW, DS-K1T690M-E1, DS-K1T690M-T, DS-K1T690MF-X, DS-K1T690MW, DS-K1T6Q-F71M, DS-K1T6QT-F72DWX, DS-K1T6QT-F72DX, DS-K1T6QT-F72TDGX, DS-K1T6QT-F72TDWX, DS-K1T6QT-F72TDX, DS-K1TA70MI-T, DS-K1TV41MF#Asia, DS-K5604A-3XF/V, DS-K5671-3XF/ZU, DS-K5671-W, DS-K5671-ZH, DS-K5671-ZU, DS-K5671-ZV, DS-K5671-ZV(B)#IN, DS-K5671A-ZU, DS-K5671B-ZH, DS-K5671B-ZU, DS-K5671B-ZV, DS-K5672MW-Z, VDP-T331#CATC, and VDP-T341#CATC
+The workspace includes shortcuts for these doctypes and reports so HR users can access regular tasks from one place.
+
+## Requirements
+
+To run this smoothly in production:
+- Frappe or ERPNext environment with this app installed.
+- Hikvision terminal IP, username, and password.
+- Employee records mapped with `attendance_device_id`.
+
+## Supported devices
+
+This app targets Hikvision terminals that expose the ISAPI access-control endpoints used by the sync process. The following models are included in the validated list from implementation testing:
+
+ACT-T1331RU, ACT-T1331WRU, ACT-T1341MFRU, ACT-T1341MRU, ACT-T1331, ACT-T1331W, DS-K1A330, DS-K1A340FWX, DS-K1A340FX, DS-K1A340WX, DS-K1A340WX#India, DS-K1A340X, DS-K1T331, DS-K1T331W, DS-K1T341A, DS-K1T341AM, DS-K1T341AM-S, DS-K1T341AMF, DS-K1T341AMF-S, DS-K1T341AMHUN#India, DS-K1T341B, DS-K1T341BMI-T, DS-K1T341BMW, DS-K1T341BMWI-T, DS-K1T341CM, DS-K1T341CMF, DS-K1T341CMFW, DS-K1T341CMW, DS-K1T341M, DS-K1T342DWX, DS-K1T342DX, DS-K1T342EFWX, DS-K1T342EWX, DS-K1T342EX, DS-K1T342MFWX, DS-K1T342MFX, DS-K1T342MWX, DS-K1T342MX, DS-K1T343EFWX, DS-K1T343EFX, DS-K1T343EWX, DS-K1T343EX, DS-K1T343MFWX, DS-K1T343MFX, DS-K1T343MFX#India, DS-K1T343MWX, DS-K1T343MX, DS-K1T607, DS-K1T607E, DS-K1T607TEF#India, DS-K1T642, DS-K1T642E, DS-K1T642EF, DS-K1T642EFW, DS-K1T642EW, DS-K1T642M, DS-K1T642MF, DS-K1T642MFW, DS-K1T642MW, DS-K1T643MWX-T, DS-K1T643MX-T, DS-K1T671, DS-K1T671AM, DS-K1T671AMW, DS-K1T671BM, DS-K1T671BMF, DS-K1T671BMFW, DS-K1T671BMW, DS-K1T671BTM, DS-K1T671BTMF, DS-K1T671BTMFW, DS-K1T671BTMW, DS-K1T671M, DS-K1T671M#RUBB, DS-K1T671M#turkey, DS-K1T671M-L, DS-K1T671MF, DS-K1T671MF-L, DS-K1T671T, DS-K1T671TM, DS-K1T671TM-3XF, DS-K1T671TMF, DS-K1T671TMFW, DS-K1T671TMW, DS-K1T672, DS-K1T672DWX-T, DS-K1T672DX-T, DS-K1T672E, DS-K1T672M, DS-K1T672MW, DS-K1T673DWX, DS-K1T673DX, DS-K1T673TDGX, DS-K1T673TDWX, DS-K1T673TDX, DS-K1T680D, DS-K1T680D-E1, DS-K1T680DF, DS-K1T680DF-E1, DS-K1T680DFG, DS-K1T680DFW, DS-K1T680DG, DS-K1T680DW, DS-K1T690M-E1, DS-K1T690M-T, DS-K1T690MF-X, DS-K1T690MW, DS-K1T6Q-F71M, DS-K1T6QT-F72DWX, DS-K1T6QT-F72DX, DS-K1T6QT-F72TDGX, DS-K1T6QT-F72TDWX, DS-K1T6QT-F72TDX, DS-K1TA70MI-T, DS-K1TV41MF#Asia, DS-K5604A-3XF/V, DS-K5671-3XF/ZU, DS-K5671-W, DS-K5671-ZH, DS-K5671-ZU, DS-K5671-ZV, DS-K5671-ZV(B)#IN, DS-K5671A-ZU, DS-K5671B-ZH, DS-K5671B-ZU, DS-K5671B-ZV, DS-K5672MW-Z, VDP-T331#CATC, VDP-T341#CATC.