Home Security Monitoring System

A comprehensive home security solution that monitors RTSP-enabled cameras, detects visitors using motion detection, and provides real-time alerts and daily summaries.

📋 Table of Contents

• Features
• System Architecture
• Prerequisites
• Detailed Installation
• Configuration
• Usage
• Development
• Troubleshooting
• Performance Considerations
• Security Considerations
• Version History
• Contributing
• License
• Support

Features

• 📹 Live Streaming: View real-time video feeds from multiple RTSP cameras with minimal latency
• 🚨 Motion Detection: Intelligent detection of movement and visitors using OpenCV image processing
• 📸 Automatic Capture: Save high-quality snapshots (configurable resolution) when motion is detected
• 📊 Dashboard: Web-based interface to monitor and review activity with customizable layouts
• 📧 Daily Reports: Email summaries with visitor timestamps, images, and motion analytics
• 🔍 Searchable History: Easily review past visitor events with advanced filtering options
• 🔔 Real-time Notifications: Instant alerts via email, browser notifications, or webhook integrations
• 📱 Mobile Responsive: Access your security system from any device with a responsive design
• 🌙 Night Mode: Enhanced visibility in low-light conditions with automatic day/night mode switching
• 🔄 Auto-Recovery: System auto-restarts stream connections if cameras disconnect

System Architecture

┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│  RTSP Cameras │────▶│  FFmpeg HLS   │────▶│  Web Browser  │
└───────────────┘     │  Conversion   │     └───────────────┘
                      └───────┬───────┘
                              │
                      ┌───────▼───────┐     ┌───────────────┐
                      │   Node.js     │◀───▶│   MongoDB     │
                      │   Backend     │     │   Database    │
                      └───────┬───────┘     └───────────────┘
                              │
                      ┌───────▼───────┐     ┌───────────────┐
                      │  React.js     │────▶│   Email       │
                      │  Frontend     │     │   Service     │
                      └───────────────┘     └───────────────┘

The system utilizes a microservices architecture with:

• Stream Processing Service: Handles camera connections and video transcoding
• Detection Service: Processes frames for motion detection
• Storage Service: Manages image and video storage with retention policies
• Notification Service: Handles alerts and report generation
• Web Interface: Provides user dashboard and controls

Prerequisites

• Node.js 16+ (v16.15.0 or higher recommended for optimal performance)
• MongoDB 5.0+ (with replica set for production deployments)
• FFmpeg 4.4+ with libx264 and libx265 support
• TP-Link Tapo cameras with RTSP enabled (tested with C200, C310, and C320WS models)
• Minimum hardware requirements:
  • CPU: 4-core processor (Intel i5/AMD Ryzen 5 or better)
  • RAM: 4GB minimum, 8GB recommended
  • Storage: 50GB+ SSD recommended for performance
  • Network: Gigabit Ethernet recommended for multiple camera streams

Detailed Installation

1. System Preparation

For Debian/Ubuntu systems:

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install required dependencies
sudo apt install -y ffmpeg build-essential python3-dev

# Install MongoDB (Community Edition)
wget -qO - https://www.mongodb.org/static/pgp/server-5.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/5.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-5.0.list
sudo apt update
sudo apt install -y mongodb-org
sudo systemctl enable mongod
sudo systemctl start mongod

For macOS systems:

# Install Homebrew if not installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required dependencies
brew install node ffmpeg mongodb-community
brew services start mongodb-community

2. Clone the repository

git clone https://github.com/yourusername/home-security.git
cd home-security

3. Run the setup script

node scripts/setup.js

The setup script performs the following actions:

• Verifies system requirements
• Creates necessary directories
• Initializes the database with default settings
• Sets up initial user accounts
• Tests camera connectivity

4. Configure environment variables

Create a .env file in both the backend and frontend directories using the provided templates:

backend/.env:

# Server Configuration
PORT=5000
NODE_ENV=development
LOG_LEVEL=info
CORS_ORIGIN=http://localhost:3000

# Database
MONGODB_URI=mongodb://localhost:27017/home_security
DB_BACKUP_PATH=./backups

# Camera Configuration
CAMERA1_NAME=Front Door
CAMERA1_URL=rtsp://username:password@camera1-ip:554/stream1
CAMERA1_DETECTION_SENSITIVITY=0.75
CAMERA2_NAME=Backyard
CAMERA2_URL=rtsp://username:password@camera2-ip:554/stream1
CAMERA2_DETECTION_SENSITIVITY=0.60

# HLS Streaming
HLS_SEGMENT_DURATION=4
HLS_OUTPUT_PATH=./storage/hls
HLS_PLAYLIST_SIZE=6

# Motion Detection
MOTION_DETECTION_ENABLED=true
MOTION_SENSITIVITY=0.65
DETECTION_INTERVAL_MS=500
MIN_AREA_PERCENT=0.5
COOL_DOWN_PERIOD_MS=10000

# Storage
STORAGE_PATH=./storage
SCREENSHOT_PATH=./storage/screenshots
RETENTION_DAYS=30

# Email Configuration
EMAIL_SERVICE=gmail
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password
REPORT_RECIPIENT=your-email@example.com
DAILY_REPORT_TIME=08:00
NOTIFICATIONS_ENABLED=true

# Security
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRY=8h
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100

frontend/.env:

REACT_APP_API_URL=http://localhost:5000/api
REACT_APP_SOCKET_URL=http://localhost:5000
REACT_APP_VERSION=1.0.0

5. Install dependencies

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

6. Build the frontend

cd frontend
npm run build

7. Start the application

# Start MongoDB (if not already running)
mongod --dbpath=/path/to/data/directory

# Start the backend (in a new terminal)
cd backend
npm start

# For development mode with auto-reload:
npm run dev

# Start the frontend for development (in a new terminal)
cd frontend
npm start

8. Production Deployment

For production deployment, it's recommended to use process managers:

# Install PM2 globally
npm install -g pm2

# Start the backend with PM2
cd backend
pm2 start server.js --name "home-security-backend"

# Configure PM2 to start on system boot
pm2 startup
pm2 save

Configuration

Camera Setup

TP-Link Tapo Camera Configuration:

1. Download the Tapo app on your mobile device
2. Add your camera to the app
3. Navigate to Settings > Advanced Settings > RTSP
4. Enable RTSP and note down the username, password, and port
5. The RTSP URL format is: rtsp://username:password@camera-ip:554/stream1

Detailed RTSP URL Examples:

• High Definition Stream: rtsp://username:password@camera-ip:554/stream1 (1080p)
• Standard Definition Stream: rtsp://username:password@camera-ip:554/stream2 (720p)
• Low Definition Stream: rtsp://username:password@camera-ip:554/stream3 (360p)

Choose the appropriate stream based on your network bandwidth and processing capabilities.

Motion Detection Configuration

The system uses advanced computer vision techniques for motion detection. Configure the sensitivity in backend/config/detection.js:

// Example settings for different environments
const detectionSettings = {
  indoor: {
    sensitivity: 0.65,
    minArea: 0.02,
    cooldownPeriod: 10000,
    regionMask: [0, 0, 1, 1] // Full frame
  },
  outdoor: {
    sensitivity: 0.55, // Lower sensitivity for outdoor (more noise)
    minArea: 0.03,     // Larger minimum area to reduce false positives
    cooldownPeriod: 15000,
    regionMask: [0, 0.3, 1, 0.7] // Only middle portion of frame
  }
};

Email Notifications

Gmail Configuration:

1. Set up a Gmail account (or other supported email provider)
2. Enable 2-Factor Authentication
3. Generate an app password: Google Account > Security > App Passwords
4. Update email settings in backend/.env

Report Customization:

Edit the email templates in backend/services/email/templates/ to customize the appearance of daily reports and notifications.

Usage

Dashboard Navigation

• Live View: Real-time camera feeds with motion indicators
• History: Timeline of detected events with filtering options
• Analytics: Charts and statistics about motion events
• Settings: System configuration and camera settings
• Alerts: Notification preferences and history

Keyboard Shortcuts

• F - Toggle fullscreen mode
• M - Mute/unmute audio
• 1-9 - Switch between camera views
• S - Take a screenshot of current view
• R - Start/stop recording
• Tab - Cycle through cameras

Mobile Access

The responsive design works on mobile devices. For optimal experience:

1. Use Chrome or Safari on iOS/Android
2. Add to home screen for full-screen experience
3. Enable notifications in browser settings

Development

Project Structure

home-security/
├── backend/                  # Backend server code
│   ├── config/               # Configuration files
│   ├── controllers/          # Request handlers
│   ├── models/               # Database models
│   ├── routes/               # API routes
│   ├── services/             # Business logic
│   ├── utils/                # Utility functions
│   └── server.js             # Express application
├── frontend/                 # Frontend application
│   ├── public/               # Static files
│   └── src/                  # React source code
├── scripts/                  # Utility scripts
├── storage/                  # Data storage
└── tests/                    # Test files

Running Tests

# Run backend unit tests
cd backend
npm test

# Run backend integration tests
npm run test:integration

# Run frontend tests
cd frontend
npm test

# Run end-to-end tests
npm run test:e2e

Code Style and Linting

The project follows Airbnb JavaScript Style Guide. Run linting with:

# Backend linting
cd backend
npm run lint

# Frontend linting
cd frontend
npm run lint

Creating a Backup

node scripts/backup.js --output=/path/to/backup/directory

This will create a backup of:

• MongoDB database (full dump)
• Captured screenshots (with metadata)
• Generated reports (PDF and HTML formats)
• System configuration

Database Migrations

cd backend
npm run migrate

Troubleshooting

Common Issues

Camera Connection Failures

1. Verify camera is powered on and connected to network
2. Check RTSP URL, username, and password
3. Ensure port 554 is not blocked by firewall
4. Try connecting with VLC player to verify RTSP stream
5. Check logs: backend/logs/camera.log

Motion Detection Problems

1. Adjust sensitivity in settings
2. Check camera position for moving objects (trees, etc.)
3. Verify adequate lighting conditions
4. Review detection zones configuration
5. Check logs: backend/logs/detection.log

Database Errors

1. Verify MongoDB is running: systemctl status mongod
2. Check connection string in .env
3. Ensure database permissions are correct
4. Run repair if database was not shutdown properly:

   mongod --repair --dbpath=/path/to/data/directory

5. Check logs: backend/logs/database.log

Log Files

Important log files for troubleshooting:

• backend/logs/app.log - Main application logs
• backend/logs/error.log - Error-level logs
• backend/logs/camera.log - Camera connection details
• backend/logs/http.log - API request logs

Getting Support

For more advanced troubleshooting:

1. Run diagnostic script: node scripts/diagnostics.js
2. Include diagnostics output when seeking support
3. Open an issue in the GitHub repository with detailed steps to reproduce

Performance Considerations

Hardware Recommendations

• Each 1080p camera stream requires approximately 2Mbps bandwidth
• CPU usage scales with number of cameras and detection sensitivity
• Consider dedicated hardware for 4+ cameras

Optimization Tips

1. Use lower resolution streams for detection (720p or lower)
2. Adjust motion detection interval based on CPU capability
3. Set appropriate retention periods to manage disk usage
4. Use network QoS to prioritize camera traffic
5. Consider edge processing if cameras support it

Scalability

The system has been tested with:

• Up to 8 cameras on a quad-core 3.5GHz CPU with 16GB RAM
• Up to 90 days of history with 1TB storage
• Up to 10 concurrent dashboard users

Security Considerations

1. Network Security

   • Use HTTPS in production (SSL certificates provided via Let's Encrypt)
   • Keep RTSP streams on a separate VLAN or subnet
   • Change default camera credentials
   • Use a VPN for remote access instead of direct port forwarding

2. Data Protection

   • Encrypt sensitive data at rest using MongoDB encryption
   • Implement proper access controls with role-based permissions
   • Regular database backups with encryption
   • Implement data retention policies to comply with privacy regulations

3. Authentication

   • Use JWT for API authentication with short expiration times
   • Implement rate limiting to prevent brute force attacks
   • Enforce strong password policies (minimum length, complexity)
   • Support multi-factor authentication for admin accounts
   • Implement IP-based access restrictions for sensitive operations

4. Updating Dependencies

   • Regularly run npm audit to check for vulnerabilities
   • Set up automated dependency updates via dependabot
   • Follow security best practices for Node.js applications

Version History

• v1.0.0 (2023-05-15) - Initial release
• v1.1.0 (2023-06-30) - Added multi-camera support and email notifications
• v1.2.0 (2023-08-15) - Improved motion detection algorithm and mobile UI
• v1.3.0 (2023-10-20) - Added analytics dashboard and performance optimizations
• v1.4.0 (2023-12-10) - Added HLS streaming support and browser notifications
• v1.5.0 (2024-02-28) - Added customizable detection zones and event filtering
• v1.6.0 (2024-04-15) - Added AI-based object detection (persons, vehicles, animals)

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Create a Pull Request

Please read CONTRIBUTING.md for detailed guidelines.

License

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

Support

For support, please:

1. Check the FAQ
2. Search for similar issues in the issue tracker
3. Open a new issue with detailed description and steps to reproduce
4. For urgent matters, contact: support@example.com