Biometric Attendance System

Production-oriented biometric attendance platform that combines edge fingerprint recognition (ESP8266 + R307) with a PHP/MySQL web control plane for enrollment, attendance tracking, and audit-ready reporting.

Overview

This project implements an end-to-end biometric attendance system for local-network deployments where low-cost hardware, deterministic behavior, and operational visibility are required.

It is designed as a full system, not only a sensor demo:

• Edge capture and matching with fingerprint templates on device.
• Server-side attendance state management (check-in/check-out lifecycle).
• Web-based operations for enrollment, user administration, and daily log export.

Primary use cases:

• Campus and training center attendance automation.
• SME office time tracking with biometric identity verification.
• Controlled facility access logging in LAN-only environments.

Architecture

The runtime pipeline is:

Fingerprint Scan -> Edge Verification -> HTTP Event Gateway -> Attendance State Engine -> MySQL Persistence -> Admin Dashboard / Export

Component Design

• Input Layer (Edge Device): NodeMCU ESP8266 reads fingerprint data from the R307 sensor and drives OLED feedback for operator status.
• Device Logic Layer: Firmware classifies scan outcomes (valid/no-finger/not-found/error), sends attendance events, and polls for enrollment/deletion commands.
• Gateway + Control Layer (PHP): A single endpoint handles attendance writes and device control signals (FingerID, Get_Fingerid, DeleteID, confirm_id).
• Persistence Layer (MySQL):
  • users stores identity metadata and command flags (fingerprint_select, add_fingerid, del_fingerid).
  • users_logs stores daily attendance events with timein and timeout.
• Operations Layer (Web UI): Admin pages support user CRUD, fingerprint assignment, live logs, and XLS report export.

Architecture Diagram

Diagram reading notes:

• Left lane: R307 Sensor + ESP8266 (capture, match, status rendering).
• Middle lane: PHP API + Attendance Logic (event processing, add/remove commands).
• Right lane: MySQL + Admin UI (data persistence, management screens, reporting).
• Control arrows:
  • Device -> API: FingerID attendance event posts.
  • API -> Device: enrollment/deletion commands.
  • API -> DB: user and log writes.
  • UI -> API: admin operations and date-filtered log queries.

Features

• Real-time attendance events from fingerprint scans.
• Two-way device/server command channel for fingerprint enrollment and deletion.
• User lifecycle management (add, update, select active fingerprint, remove).
• Daily attendance log viewer with date filtering and export to .xls.
• OLED feedback states for connection, scan status, and action outcomes.
• Local deployment model using XAMPP + MySQL (no cloud dependency required).

Technical Highlights

• Stateful attendance engine: Check-in/check-out is controlled by same-day open session detection (timeout='0') to avoid duplicate active sessions.
• Asynchronous control-plane pattern: Device polling (Get_Fingerid, DeleteID) decouples admin actions from hardware timing and keeps firmware simple.
• Enrollment handshake: New IDs are staged in DB, enrolled on sensor, then confirmed back to backend (confirm_id) for consistency across layers.
• Prepared-statement usage in core handlers: Helps reduce SQL injection risk on critical read/write paths.
• Deterministic response protocol: Compact response tokens (login, logout, add-id, del-id, available) simplify parsing on constrained hardware.
• Operational visibility: Admin UI auto-refreshes tables and supports date-scoped exports for quick audit workflows.

Tech Stack

Layer	Technologies
Embedded Edge	ESP8266 NodeMCU, R307 Fingerprint Sensor, OLED SSD1306
Firmware	Arduino C++, ESP8266WiFi, ESP8266HTTPClient, Adafruit Fingerprint/SSD1306/GFX
Backend	PHP (procedural), MySQL, XAMPP (Apache + MariaDB/MySQL)
Frontend	HTML/CSS, JavaScript, jQuery (AJAX polling)
Reporting	Server-side XLS export

Getting Started

1. Clone Repository

git clone https://github.com/kershrita/Biometric-Attendance-System.git
cd Biometric-Attendance-System

2. Hardware Assembly

• ESP8266 NodeMCU
• R307 Fingerprint Sensor
• 0.96-inch I2C OLED display (SSD1306)

Use the circuit references included in the repository to wire sensor and display to the NodeMCU.

• Detailed setup walkthrough: Getting Started Guide
• Mechanical enclosure CAD: Biometric Box

3. Backend Setup (Local Server)

1. Install XAMPP and start Apache and MySQL.
2. Copy the biometricattendance folder into C:\xampp\htdocs.
3. Run database bootstrap once:
   • http://localhost/biometricattendance/install.php

4. Firmware Configuration

In nodeMCU_Fingerprint/nodeMCU_Fingerprint.ino, set:

• ssid
• password
• link (backend endpoint URL, e.g. http://<server-ip>/biometricattendance/getdata.php)

Install required Arduino libraries from the Libraries directory and ensure ESP8266 board support is installed.

5. Upload and Run

1. Flash firmware to the NodeMCU.
2. Open web pages:
   • http://localhost/biometricattendance/ManageUsers.php
   • http://localhost/biometricattendance/UsersLog.php
3. Enroll fingerprints, assign user metadata, and start tracking attendance.

Results

Current implementation delivers:

• End-to-end biometric attendance capture from scan to persistent log entry.
• Same-day check-in/check-out transitions using server-managed attendance state.
• Live dashboard updates for users and logs (periodic AJAX refresh).
• Operator-ready reporting through date-filtered XLS export.

Representative system outputs include:

• Device feedback: scan accepted/rejected/communication status on OLED.
• API acknowledgments: login<username>, logout<username>, add-id<id>, del-id<id>.
• Web outputs: user table, daily log table, and downloadable report file.

Model Details

This system uses template-based biometric matching provided by the fingerprint module firmware stack (rather than a custom-trained ML model).

• Model type: Embedded fingerprint template extraction and matching.
• Why chosen: Low-latency inference on constrained edge hardware with reliable deterministic behavior.
• Enrollment approach: Two-capture fingerprint enrollment with template storage by ID.
• Evaluation approach: Functional validation via successful enrollment, recognition, and attendance event integrity.