🛡️ ExamShield

AI-Powered Exam Proctoring System with IoT Integration

Real-time AI exam monitoring | Multi-camera support | BLE & WiFi device detection | Intelligent alerting

Features • Quick Start • Documentation • Demo • Contributing

📋 Table of Contents

Overview
Features
System Architecture
Quick Start
Installation
Usage
ESP32 Integration
Configuration
Documentation
Future Roadmap
Contributing
License
Contact

🎯 Overview

ExamShield is a comprehensive AI-powered exam proctoring solution that combines computer vision, deep learning, and IoT sensors to ensure exam integrity. Built with YOLOv8 for object detection and ESP32 microcontrollers for environmental monitoring, ExamShield provides real-time alerts for potential cheating behaviors.

🔑 Key Capabilities

AI Object Detection: Detects phones, earphones, smartwatches in real-time
Behavioral Analysis: Monitors head rotation and suspicious movements
Multi-Student Tracking: Supports multiple students per camera
IoT Integration: ESP32-based BLE and WiFi device monitoring
Multi-Camera Support: Single camera, 4-camera (Pro), and 16-camera

(Enterprise) modes

Intelligent Alerting: Smart cooldown system prevents false positives
GPU Acceleration: CUDA, DirectML, and CPU support
Risk Scoring: Weighted detection confidence with priority levels

✨ Features

🤖 AI Detection Capabilities

Detection Class	Priority	Description	Threshold
📱 Phone	Critical	Mobile phone usage	45%
🎧 Earphone	Critical	Earbuds/headphones (requires 3+ detections)	30%
⌚ Smartwatch	High	Wearable device detection	50%
🔄 Head Rotation	High	Suspicious head movement (sustained 5s)	55%
📄 Paper Passing	Medium	Paper exchange between students	60%

💡 Smart Features

✅ Threaded Camera Capture - Zero frame lag with background processing
✅ Person Tracking - Centroid-based multi-student tracking
✅ Alert Management - Cooldown periods, photo limits, and spacing control
✅ Risk Scoring - Priority-weighted confidence analysis
✅ Session Reporting - Comprehensive CSV logs and summary reports
✅ ESP32 Integration - BLE scanner and WiFi sniffer for device detection
✅ Video Analysis - Process pre-recorded exam footage

🎥 Multi-Camera Modes

Standard Mode (main.py) - Single camera, full features
Pro Mode (Main_Pro.py) - 4 independent cameras
Enterprise Mode (main_Enterprise.py) - Up to 16 cameras, optimized performance

🏗️ System Architecture

graph TB
    subgraph "Camera System"
        CAM[Camera Feed] --> THREAD[Threaded Capture]
        THREAD --> QUEUE[Frame Queue]
    end
    
    subgraph "AI Detection"
        QUEUE --> YOLO[YOLOv8 Model]
        YOLO --> DETECT[Object Detection]
        DETECT --> PERSON[Person Tracking]
    end
    
    subgraph "Behavioral Analysis"
        PERSON --> ANALYZE[Student Analyzer]
        ANALYZE --> RISK[Risk Scoring]
        RISK --> ALERT{Alert Trigger?}
    end
    
    subgraph "Alert System"
        ALERT -->|Yes| PHOTO[Capture Photo]
        PHOTO --> LOG[CSV Logging]
        LOG --> REPORT[Session Report]
    end
    
    subgraph "IoT Monitoring"
        ESP32_BLE[ESP32 BLE Scanner] --> UDP[UDP Stream]
        ESP32_WIFI[ESP32 WiFi Sniffer] --> TCP[TCP Stream]
        UDP --> GUI[Monitor GUI]
        TCP --> GUI
    end
    
    ALERT -->|No| QUEUE

🚀 Quick Start

Prerequisites

Python 3.8+ installed
Webcam or USB camera
(Optional) ESP32 microcontrollers for IoT monitoring
(Optional) NVIDIA GPU for faster processing

One-Command Installation

# Clone the repository
git clone https://github.com/MORSHEDMDMONOARUL/ExamShield.git
cd ExamShield

# Install dependencies
pip install -r requirements.txt

# Run ExamShield
python src/main.py

That's it! ExamShield will start monitoring with your default camera.

Keyboard Controls

Key	Action
`Q`	Quit application
`S`	Take screenshot
`H`	Hide/show UI overlay

📦 Installation

Step 1: Clone Repository

git clone https://github.com/MORSHEDMDMONOARUL/ExamShield.git
cd ExamShield

Step 2: Create Virtual Environment (Recommended)

# Create virtual environment
python -m venv .venv

# Activate (Windows)
.venv\Scripts\activate

# Activate (Linux/Mac)
source .venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Dependencies Installed:

ultralytics==8.3.229 - YOLOv8 framework
opencv-python==4.12.0.88 - Computer vision
torch==2.9.1 - Deep learning framework
torchvision==0.24.1 - Vision utilities
numpy==2.2.6 - Numerical computing
psutil==7.1.3 - System monitoring
Pillow==12.0.0 - Image processing

💻 Usage

Standard Mode (Single Camera)

python src/main.py

Best for: Individual exam monitoring, testing, development

Pro Mode (4 Cameras)

python src/Main_Pro.py

Best for: Small exam halls, multiple angle coverage

Enterprise Mode (16 Cameras)

python src/main_Enterprise.py

Best for: Large exam halls, university-scale deployments

Video Analysis Mode

python src/videotodetect.py

Process pre-recorded exam videos for post-exam analysis.

ESP32 Monitor GUI

python src/esp32_monitor_gui.py

Real-time visualization of BLE and WiFi device detection.

📡 ESP32 Integration

BLE Scanner Setup

Flash BLE+WIFI/ble.ino to ESP32

// Update WiFi credentials (lines 14-15)
const char* ssid = "Your-WiFi-SSID";
const char* password = "Your-WiFi-Password";

// Update laptop IP (line 19)
const char* targetIP = "192.168.1.100";  // Your computer's IP

Run BLE Monitor
```
python BLE+WIFI/ble.py
```

WiFi Sniffer Setup

Flash BLE+WIFI/wifi.ino to ESP32
Run WiFi Monitor
```
python BLE+WIFI/wifi.py
```

Combined Monitoring

python src/esp32_monitor_gui.py

Displays both BLE and WiFi detections in a unified interface.

⚙️ Configuration

Camera Settings

Edit configuration in src/main.py (lines 43-128):

class Config:
    # Video settings
    FRAME_WIDTH = 1280
    FRAME_HEIGHT = 720
    TARGET_FPS = 30
    
    # Detection thresholds
    ALERT_THRESHOLD = {
        "phone": 0.45,
        "earphone": 0.30,
        "smartwatch": 0.50,
        "headrotation": 0.55,
        "paperpassing": 0.60
    }
    
    # Alert management
    ALERT_COOLDOWN = 10  # seconds
    MAX_PHOTOS_PER_ALERT = 3
    PHOTO_INTERVAL = 2   # seconds

Model Configuration

ExamShield uses a custom-trained YOLOv8 model:

Path: runs/detect/examshield_yolov8s/weights/best.pt
Size: 22.6 MB
Classes: 5 (phone, earphone, smartwatch, headrotation, paperpassing)

To use your own model:

DETECTION_MODEL = "path/to/your/model.pt"

📚 Documentation

Installation Guide - Detailed setup instructions
ESP32 Setup - Complete ESP32 configuration
API Reference - Class and function documentation
Architecture - System design and diagrams
Troubleshooting - Common issues and solutions
Contributing Guide - How to contribute

🔮 Future Roadmap

v2.3.0 (Short-term)

Web-based dashboard for remote monitoring
Database integration (PostgreSQL / MongoDB)
Email / SMS alert notifications
Mobile app for supervisors
Advanced analytics and reporting

v3.0.0 (Mid-term)

Facial recognition for student identification
Gaze tracking for attention monitoring
Speech detection for verbal cheating
Cloud deployment support (AWS / Azure)
Multi-language support

v4.0.0 (Long-term)

AI behavior prediction models
Blockchain-based tamper-proof logs
AR/VR exam environment support
Integration with Learning Management Systems (LMS)

See FUTURE_ROADMAP.md for detailed plans.

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Ways to Contribute

🐛 Report Bugs - Use issue templates
💡 Suggest Features - Share your ideas
📖 Improve Docs - Help make documentation better
💻 Submit PRs - Fix bugs or add features
⭐ Star the Repo - Show your support!

Development Setup

Fork the repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit changes (git commit -m 'Add some AmazingFeature')
Push to branch (git push origin feature/AmazingFeature)
Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 Sejong University
Developed by: Morshed MD Monoarul

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software... (see LICENSE file for full text)

📧 Contact

Morshed MD Monoarul - Sejong University

Project Link: https://github.com/MORSHEDMDMONOARUL/ExamShield

👥 Contributors

Development Team

Morshed MD Monoarul - Lead Developer

Main application development (YOLOv8 integration, multi-camera system)
Dataset preparation and model training in Roboflow
YOLOv8 model training and optimization
ESP32 monitor GUI development (BLE + WiFi)
System architecture and design
Documentation and project management

MIRAJ MD MEJBAH HOSSAIN - ESP32 IoT Developer

BLE scanner implementation (ESP32)
WiFi sniffer development (ESP32)
IoT sensor integration

MANISH - AI Training Contributor

Model training assistance in Roboflow
Training dataset photos contribution
Data annotation support

IKSA - AI Training Contributor

Model training assistance in Roboflow
Training dataset photos contribution
Data annotation support

Institution

Sejong University

Project supervision and resources
Copyright holder

🙏 Acknowledgments

Frameworks & Tools

Ultralytics YOLOv8 - Object detection framework
OpenCV - Computer vision library
Espressif ESP32 - IoT microcontroller
PyTorch - Deep learning framework
Roboflow - Dataset management and model training platform

Training Pipeline

Dataset preparation: Roboflow
Model architecture: YOLOv8s
Training: Custom dataset with 5 cheating detection classes
Annotation: Team collaborative effort

Special Thanks

Sejong University for project support and resources
All contributors for their dedication to academic integrity
Open source community for the amazing tools

📊 Project Stats

Made with ❤️ for academic integrity

If you find ExamShield useful, please consider giving it a ⭐️

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github		.github
BLE+WIFI		BLE+WIFI
docs		docs
logs		logs
models		models
runs/detect/examshield_yolov8s		runs/detect/examshield_yolov8s
src		src
.gitignore		.gitignore
AUTHORS.md		AUTHORS.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DOCUMENTATION.md		DOCUMENTATION.md
FUTURE_ROADMAP.md		FUTURE_ROADMAP.md
LICENSE		LICENSE
PUBLISH_NOW.md		PUBLISH_NOW.md
QUICK_START_GIT.md		QUICK_START_GIT.md
README.md		README.md
requirements.txt		requirements.txt
session_report.txt		session_report.txt

Folders and files

Latest commit

History

Repository files navigation

🛡️ ExamShield

AI-Powered Exam Proctoring System with IoT Integration

📋 Table of Contents

🎯 Overview

🔑 Key Capabilities

✨ Features

🤖 AI Detection Capabilities

💡 Smart Features

🎥 Multi-Camera Modes

🏗️ System Architecture

🚀 Quick Start

Prerequisites

One-Command Installation

Keyboard Controls

📦 Installation

Step 1: Clone Repository

Step 2: Create Virtual Environment (Recommended)

Step 3: Install Dependencies

Dependencies Installed:

💻 Usage

Standard Mode (Single Camera)

Pro Mode (4 Cameras)

Enterprise Mode (16 Cameras)

Video Analysis Mode

ESP32 Monitor GUI

📡 ESP32 Integration

BLE Scanner Setup

WiFi Sniffer Setup

Combined Monitoring

⚙️ Configuration

Camera Settings

Model Configuration

📚 Documentation

🔮 Future Roadmap

v2.3.0 (Short-term)

v3.0.0 (Mid-term)

v4.0.0 (Long-term)

🤝 Contributing

Ways to Contribute

Development Setup

📄 License

📧 Contact

👥 Contributors

Development Team

Institution

🙏 Acknowledgments

Frameworks & Tools

Training Pipeline

Special Thanks

📊 Project Stats

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages