🧠 Overview

SmartAttend-IoT is an automated attendance system that leverages facial recognition technology on an edge IoT device. Running on a Raspberry Pi (or desktop for development), it captures video, identifies registered students in real time, displays status on an I2C OLED screen with buzzer feedback, and syncs attendance data with a central FastAPI backend. A Nuxt.js web dashboard allows administrators to manage students and view attendance reports.

The system follows a client-server architecture where the IoT device acts as a smart edge client — performing face detection and matching locally for speed, while syncing records to the cloud for persistence and administration.

🎯 Key Features

• Real-Time Face Recognition: 128-dimensional face encoding via dlib's face_recognition library, matched against a local database in a dedicated background thread for zero UI blocking
• I2C OLED Status Display: SSD1306 OLED screen connected via I2C shows real-time attendance status — recognized name, timestamp, and system state
• Buzzer Audio Feedback: Audible confirmation when a face is successfully recognized and attendance is logged
• Smart Debounce Logic: Configurable 10-minute debounce prevents duplicate entries even with continuous camera exposure
• Cross-Platform Camera: Factory pattern auto-detects Raspberry Pi (PiCamera2 with XRGB8888) or desktop (USB webcam via OpenCV VideoCapture)
• FastAPI REST Backend: Async API for student CRUD, face encoding generation from uploaded photos, attendance event logging, and device sync
• Nuxt.js Admin Dashboard: Vue 3 + Tailwind CSS interface for student registration (with photo upload), attendance reports, and system management
• SQLAlchemy ORM: Unified database layer supporting SQLite (development) and PostgreSQL (production)

🏗️ System Architecture

┌──────────────────────────────────────────┐
│          IoT Edge Device (Raspberry Pi)  │
│                                          │
│  Camera → Recognition Engine → Matcher   │
│              ↓                    ↓      │
│         OLED Display         API Client  │
│         + Buzzer                 ↓       │
└──────────────────────────────────────────┘
                                   │
                            HTTP REST API
                                   │
┌──────────────────────────────────────────┐
│              Server Side                 │
│                                          │
│  FastAPI Backend ←→ SQLite/PostgreSQL    │
│        ↑                                 │
│  Nuxt.js Dashboard (Admin)               │
└──────────────────────────────────────────┘

🔄 Data Flow

Student Registration

1. Admin uploads a student photo and name via the Nuxt.js Dashboard
2. FastAPI Backend receives the photo
3. Backend detects the face and generates a 128-dimensional encoding using dlib
4. The encoding is serialized (pickled) and stored in the Database

Attendance Marking

1. IoT Device boots up and calls GET /students/sync to download all face encodings
2. Camera captures frames at 640×480 resolution
3. Recognition Engine resizes frames to 1/4 scale and detects faces
4. Encodings are compared using Euclidean distance against the local database
5. On match (with debounce check), attendance is logged and OLED + buzzer confirm
6. API Client syncs the record to POST /attendance

🛠️ Technical Stack

IoT / Edge Device

• Python 3.9+ — Core runtime
• face_recognition (dlib) — 128D face encoding and matching
• OpenCV — Video capture, frame processing, and display
• Adafruit SSD1306 — I2C OLED display driver via Adafruit Blinka
• Pillow — Image rendering for OLED text display
• PiCamera2 — Raspberry Pi Camera Module 3 support (XRGB8888 format)

Backend

• FastAPI — Async Python web framework for REST API
• SQLAlchemy — ORM with aiosqlite (dev) and PostgreSQL (prod)
• Pydantic — Request/response validation schemas

Frontend

• Nuxt.js (Vue 3) — Server-side rendered admin dashboard
• Tailwind CSS — Utility-first responsive styling

Hardware

• Raspberry Pi 4 — Edge computing platform
• Pi Camera Module 3 — Video capture
• SSD1306 OLED (128×64) — I2C status display
• Piezo Buzzer — Audio feedback on recognition
• USB Webcam — Desktop fallback camera

📁 Project Structure

SmartAttend-IoT/
├── backend/              # FastAPI Server
│   ├── main.py           # API entry point & endpoints
│   ├── models.py         # SQLAlchemy DB models (Student, Attendance)
│   └── schemas.py        # Pydantic validation schemas
├── core/                 # IoT Device Logic
│   ├── api_client.py     # HTTP client for backend sync
│   ├── camera.py         # Camera hardware abstraction (Factory pattern)
│   ├── recognition.py    # Face detection & matching (threaded)
│   └── database.py       # Local SQLAlchemy DB connection
├── frontend/             # Nuxt.js Web Dashboard
│   ├── app/              # Vue components & pages
│   └── nuxt.config.ts    # Nuxt configuration
├── tests/                # Unit tests with mock camera
├── main.py               # IoT device entry point
├── train.py              # Batch face encoding trainer
└── requirements.txt      # Python dependencies

🚀 Deployment

The system supports dual deployment:

• Edge Device: Runs main.py on Raspberry Pi with camera, OLED, and buzzer connected — performs local face recognition and syncs to backend
• Server: FastAPI backend deployed separately (supports Docker), serving the Nuxt.js dashboard and REST API for multi-device management