User Interface

• ✅ Admin Dashboard - Monitor multiple drivers simultaneously
• ✅ Driver Dashboard - Real-time metrics and status display
• ✅ Settings Management - Customizable detection sensitivity and thresholds
• ✅ Alert History - Track and review drowsiness events
• ✅ Multi-Driver Monitoring - Support for concurrent driver sessions

Alert & Notification Systems

• ✅ Visual Alerts - Full-screen overlay with acknowledgment
• ✅ Audio Alerts - Browser-based alarm sounds
• ✅ Arduino Integration - Physical buzzer and LED alerts via USB serial
• ✅ SMS Notifications - Twilio integration for emergency alerts
• ✅ Email Notifications - SMTP support for alert delivery
• ✅ Telegram Bot - Real-time notifications via Telegram API

IoT & Hardware Integration

• ✅ Arduino Uno R3 Support - Serial communication for buzzer/LED control
• ✅ I2C LCD Display - Real-time status display on LCD screen
• ✅ Per-User Arduino Configuration - Individual settings for each driver
• ✅ Heartbeat Monitoring - Maintains connection stability

Deployment & Accessibility

• ✅ Cloudflare Tunnel - Free public access tunneling
• ✅ ngrok Support - Alternative tunneling solution
• ✅ LocalTunnel - Additional deployment option
• ✅ Cross-Platform - Works on Windows, macOS, and Linux

🖥️ Technologies Used

Backend

• Python 3.10+
• Flask 3.0.3 - Web framework
• OpenCV 4.10.0 - Computer vision and image processing
• MediaPipe 0.10.14 - Facial landmark detection
• NumPy 1.26.4 - Numerical computations
• PySerial 3.5 - Arduino serial communication

Frontend

• HTML5 / CSS3
• JavaScript (Vanilla)
• Tailwind CSS - Utility-first CSS framework
• Phosphor Icons - Icon library

External Services

• Twilio - SMS notifications
• SMTP - Email notifications
• Telegram Bot API - Telegram notifications
• Google Maps API - Location services

Hardware

• Arduino Uno R3 - IoT alert system
• I2C LCD Display - Status display
• Active Buzzer - Audio alerts
• LEDs (Red/Green) - Visual indicators

📋 Prerequisites

Before installing, ensure you have:

• Python 3.10 or higher installed
• pip (Python package manager)
• Webcam (USB or built-in camera)
• Arduino Uno R3 (optional, for IoT alerts)
• Internet connection (for deployment and notifications)

For Arduino Integration (Optional)

• Arduino IDE installed
• USB cable to connect Arduino to computer
• Components:
  • Active Buzzer
  • 2x 220Ω Resistors
  • 1x Red LED
  • 1x Green LED
  • I2C LCD Display (16x2)
  • Breadboard and jumper wires

🚀 Installation Guide

1. Clone the Repository

git clone https://github.com/mjrecosana06/AI-Drowsy-Driver-Detection.git
cd AI-Drowsy-Driver-Detection

2. Create and Activate Virtual Environment

Windows:

python -m venv venv
venv\Scripts\activate

macOS/Linux:

python3 -m venv venv
source venv/bin/activate

3. Install Python Dependencies

pip install -r requirements.txt

Note for Apple Silicon (M1/M2 Macs): The requirements.txt automatically handles MediaPipe installation for Apple Silicon. If you encounter issues, you may need to install mediapipe-silicon separately:

pip install mediapipe-silicon

4. Set Up Environment Variables (Optional)

Create a .env file in the project root for custom configuration:

# Camera Settings
CAMERA_INDEX=0
CAM_WIDTH=640
CAM_HEIGHT=480
CAM_FPS=12
CAM_MIRROR=0
JPEG_QUALITY=60

# Detection Thresholds
EAR_THRESHOLD=0.23
MAR_THRESHOLD=0.65
TILT_THRESHOLD_DEG=18
FRAMES_BELOW_THRESH=12
PERCLOS_THRESHOLD=0.2

# Arduino Settings (Optional)
ARDUINO_PORT=/dev/cu.usbserial-10
ARDUINO_BAUD=9600

# Notification Settings (Optional)
TWILIO_ACCOUNT_SID=your_twilio_sid
TWILIO_AUTH_TOKEN=your_twilio_token
TWILIO_PHONE_NUMBER=your_twilio_number

5. Arduino Setup (Optional)

If you want to use Arduino for physical alerts:

1. Install Required Libraries:

   • Open Arduino IDE
   • Go to Tools → Manage Libraries
   • Install LiquidCrystal_I2C library
   • Install Wire library (usually pre-installed)

2. Upload Arduino Code:

   • Open arduino_uno_drowsy_alert.ino in Arduino IDE
   • Select your board: Tools → Board → Arduino Uno
   • Select your port: Tools → Port → [Your Arduino Port]
   • Click Upload

3. Connect Components:

   • Follow the circuit diagrams in Images/Arduino Uno R3 Economy Circuits/
   • Connect buzzer to pin 9
   • Connect Red LED to pin 10
   • Connect Green LED to pin 8
   • Connect I2C LCD to SDA/SCL pins

4. Test Connection:

   python test_arduino_connection.py
   

6. Run the Application

Option 1: Using Start Scripts (Recommended)

Windows:

1. Open Command Prompt or PowerShell
2. Navigate to project directory:

   cd "C:\path\to\AI-Drowsy-Driver-Detection"
   

3. Run Flask server:

   start_flask.bat
   

macOS/Linux:

1. Open Terminal
2. Navigate to project directory:

   cd "/path/to/AI-Drowsy-Driver-Detection"
   

3. Make script executable (first time only):

   chmod +x start_flask.sh
   

4. Run Flask server:

   ./start_flask.sh
   

Option 2: Manual Start

Windows (Command Prompt):

set FLASK_HOST=0.0.0.0
set FLASK_PORT=5000
python app.py

Windows (PowerShell):

$env:FLASK_HOST="0.0.0.0"
$env:FLASK_PORT="5000"
python app.py

macOS/Linux:

export FLASK_HOST=0.0.0.0
export FLASK_PORT=5000
python3 app.py

7. Access the Application

• Local Access: Open your browser and go to http://localhost:5000
• Network Access (Same WiFi): Use your computer's IP address: http://[YOUR_IP]:5000
  • Find your IP:
    • Windows: Run ipconfig in Command Prompt, look for IPv4 Address
    • macOS/Linux: Run ifconfig or ip addr, look for inet address

8. Create Admin Account

1. Go to http://localhost:5000/register.html
2. Register with email and password
3. Select Admin role
4. Login at http://localhost:5000/login.html

9. Deploy for Public Access (Optional)

Option A: Using Cloudflare Tunnel (Recommended - Free)

Cloudflare Tunnel provides free, secure public access to your local Flask server without exposing your IP address.

Step 1: Install Cloudflare Tunnel

Windows:

1. Download cloudflared.exe from Cloudflare Releases
2. Place cloudflared.exe in your project folder (already included)
3. Or use the included start_cloudflare.bat script

macOS:

# Install via Homebrew (Recommended)
brew install cloudflared

# Or download manually from GitHub releases
# Place cloudflared in your project folder

Step 2: Start Flask Server

Windows:

# Open Command Prompt or PowerShell
cd "C:\path\to\AI-Drowsy-Driver-Detection"
start_flask.bat

macOS/Linux:

# Open Terminal
cd "/path/to/AI-Drowsy-Driver-Detection"
chmod +x start_flask.sh
./start_flask.sh

Step 3: Start Cloudflare Tunnel (In a NEW Terminal/Command Prompt)

Windows:

# Open a NEW Command Prompt window
cd "C:\path\to\AI-Drowsy-Driver-Detection"
start_cloudflare.bat

# Or manually:
cloudflared tunnel --url http://127.0.0.1:5000

macOS/Linux:

# Open a NEW Terminal window
cd "/path/to/AI-Drowsy-Driver-Detection"
chmod +x start_cloudflare.sh
./start_cloudflare.sh

# Or manually:
cloudflared tunnel --url http://127.0.0.1:5000

Step 4: Get Your Public URL

After starting Cloudflare Tunnel, you'll see output like:

+--------------------------------------------------------------------------------------------+
|  Your quick Tunnel has been created! Visit it at (it may take some time to be reachable): |
|  https://random-words-1234.trycloudflare.com                                               |
+--------------------------------------------------------------------------------------------+

Copy this URL and share it to access your system from anywhere!

Important Notes:

• Keep BOTH terminals open (Flask server + Cloudflare tunnel)
• The URL changes each time you restart the tunnel
• Cloudflare tunnels are free but temporary (session-based)

Option B: Using ngrok (Alternative)

Step 1: Install ngrok

Windows:

1. Download ngrok.exe from ngrok.com
2. Place ngrok.exe in your project folder (already included)
3. Sign up for a free account at ngrok.com to get your auth token
4. Run: ngrok config add-authtoken YOUR_AUTH_TOKEN

macOS:

# Install via Homebrew
brew install ngrok/ngrok