SecureHome Vision

Advanced Multi-Camera Fall Detection System for the Elderly

SecureHome Vision is a real-time fall detection system that uses multiple Android phones as camera nodes and a central Python server with AI processing. It follows a "Dumb Node / Smart Server" architecture: Android devices only stream video and broadcast their existence, while the PC handles all AI processing.

---

Table of Contents

1. Architecture Overview
2. System Requirements
3. Quick Start
4. Android App Setup
5. Python Server Setup
6. AI Pipeline
7. State Management & Crash Recovery
8. CI/CD & Auto-Build
9. Troubleshooting

---

Architecture Overview

+---------------------+        UDP Discovery          +-------------------+
|  Android Phone #1   |  ------ 5005 (Broadcast) -->  |                   |
|  - Camera Stream    | ------ MJPEG Stream ------->  |  Python Server    |
|  - UDP Beacon       |                               |  (The "Brain")    |
+---------------------+                               |                   |
                                                      |  - YOLO11-Pose    |
+---------------------+ ------ MJPEG Stream ------->  |  - YOLO11-Seg     |
|  Android Phone #2   |                               |  - Floor Detect   |
|  - Camera Stream    |                               |  - Fall Analysis  |
|  - UDP Beacon       |                               |  - Blood Detect   |
+---------------------+                               +-------------------+
                                                      |       |
                                                      |  Alerts
                                                      v       v
                                               +-------+      +--------+
                                               | SMS   |      | Push   |
                                               | Alert |      | Notify |
                                               +-------+      +--------+

AI Pipeline Stages

1. Presence Detection - YOLO11-Pose detects people in the frame
2. Environment Mapping - YOLO11-Seg identifies floor level
3. Fall Detection - Keypoint velocity + height analysis detects sudden drops
4. Temporal Analysis - Post-fall behavior classification (still, sitting, struggling)
5. Blood Detection - OpenCV color masking for blood-like pixels

---

System Requirements

Android Device (Camera Node)

Requirement	Minimum	Recommended
Android Version	5.0 (API 21)	8.0+
RAM	1 GB	2 GB
Storage	50 MB free	100 MB free
Camera	Rear camera	Rear camera (1080p)
Network	Wi-Fi (2.4/5 GHz)	Wi-Fi (5 GHz)

Python Server (The "Brain")

Cameras	Minimum Hardware	Recommended Hardware
4 cameras	CPU: Intel i5-10400 / AMD Ryzen 5 3600 RAM: 8 GB GPU: NVIDIA GTX 1660 (6GB)	CPU: Intel i7-12700 / AMD Ryzen 7 5800X RAM: 16 GB GPU: NVIDIA RTX 3060 (12GB)
8 cameras	CPU: Intel i7-10700 / AMD Ryzen 7 3700X RAM: 16 GB GPU: NVIDIA RTX 3060 (12GB)	CPU: Intel i7-12700 / AMD Ryzen 7 5800X RAM: 32 GB GPU: NVIDIA RTX 4060 (16GB)
12 cameras	CPU: Intel i7-12700 / AMD Ryzen 7 5800X RAM: 32 GB GPU: NVIDIA RTX 4060 (16GB)	CPU: Intel i9-13900 / AMD Ryzen 9 7900X RAM: 64 GB GPU: NVIDIA RTX 4070 (12GB)
16 cameras	CPU: Intel i9-13900 / AMD Ryzen 9 7900X RAM: 64 GB GPU: NVIDIA RTX 4070 (12GB)	CPU: Intel i9-14900 / AMD Ryzen 9 7950X RAM: 128 GB GPU: NVIDIA RTX 4080 (16GB)

Software Requirements:

• Python 3.9+
• CUDA 11.8+ (for GPU acceleration)
• OpenCV 4.8+
• Ultralytics 8.3+

---

Quick Start

# 1. Clone the repository
git clone https://github.com/your-org/SecureHomeVision.git
cd SecureHomeVision

# 2. Build the Android APK
chmod +x build_android.sh
./build_android.sh

# 3. Set up the Python server
cd server
chmod +x setup_server.sh
./setup_server.sh

# 4. Start the server
python server.py

# 5. Install the APK on an Android device
adb install ../SecureHomeVision-debug.apk

---

Android App Setup

Building the APK

# From project root
./build_android.sh

This produces SecureHomeVision-debug.apk in the project root.

Installing on a Device

# Via ADB (recommended for development)
adb install SecureHomeVision-debug.apk

# Or via Android Studio:
# 1. Connect device via USB
# 2. Enable Developer Options + USB Debugging
# 3. Run the app from Android Studio

Permissions

The app requires the following permissions (auto-declared in AndroidManifest.xml):

• INTERNET - For streaming
• CAMERA - For camera access
• FOREGROUND_SERVICE - For background streaming
• WAKE_LOCK - To keep the screen alive

Network Configuration

Ensure the Android device and the Python server are on the same local network. The Android app broadcasts UDP discovery packets to port 5005, and the server listens for them.

Firewall rules on the server:

# Allow UDP 5005 (discovery)
sudo ufw allow 5005/udp

# Allow TCP 8080 (MJPEG streams from each camera)
sudo ufw allow 8080/tcp

---

Python Server Setup

Installation

cd server
./setup_server.sh

This will:

1. Create a virtual environment
2. Install all Python dependencies
3. Download YOLO11 models
4. Verify the installation

Running the Server

cd server
source venv/bin/activate
python server.py

Server Configuration

Edit server/config.yaml (or the CONFIG dict in server.py):

CONFIG = {
    "discovery_port": 5005,     # UDP port for camera discovery
    "ai_interval": 2.0,         # AI processing interval (seconds)
    "pose_conf": 0.5,           # YOLO pose confidence threshold
    "alert_interval": 60,       # Min seconds between alerts
    "model_dir": "./models",    # YOLO model directory
}

Server Logs

The server logs to stdout with the following levels:

• INFO - Normal operation
• WARNING - Stream loss, camera timeouts
• CRITICAL - Fall alerts

---

AI Pipeline

Fall Detection Logic

1. Sudden Velocity Detection: A rapid drop in keypoint height (shoulders/hips) exceeding 15% of frame height per second
2. Floor Intersection: Keypoints cross the detected floor level
3. Combined Confidence: Both conditions must be met for a fall alert

Post-Fall Classification

State	Description	Priority
still	No movement detected (potentially unconscious)	HIGH
struggling	Oscillating up-down movements but not rising	HIGH
sitting	Some movement, appears seated	MEDIUM
recovering	Successfully standing up	LOW (auto-resolve)

Blood Detection

The system uses HSV color masking to detect blood-like colors near the fallen person:

• Dark red / burgundy range: HSV(0-10, 50-255, 50-200)
• Deep red range: HSV(140-170, 50-255, 50-200)
• Threshold: >3% of the search area shows blood-like pixels

---

State Management & Crash Recovery

The system uses SQLite for persistent state and a JSON checkpoint file for quick recovery.

State Database

Located at server/state/state.db, it stores:

• Discovered cameras and their status
• Fall events and their resolution
• Temporal analysis state per person
• System health metrics

Checkpoint File

Located at server/state/checkpoint.json, it stores:

• Current processing phase
• Conversation ID
• Phase number
• Last successful state

Recovery Procedure

In case of a crash, simply restart the server:

cd server
python server.py

The server will:

1. Load the last checkpoint
2. Resume from the last known phase
3. Reconnect to any active cameras
4. Restore temporal analysis state

Manual State Reset

To clear all state and start fresh:

cd server/state
rm -rf state.db checkpoint.json

---

CI/CD & Auto-Build

GitHub Actions

Every push to main or develop triggers:

1. Android Build - Builds the APK and uploads as an artifact
2. Server Tests - Runs Python unit tests

Local Build

# Build Android APK
./build_android.sh

# Test Python server
cd server
python -m pytest tests/ -v

---

Troubleshooting

Android App Issues

App crashes on startup:

• Ensure Android 5.0+ (API 21+)
• Check device storage space
• Verify camera permission is granted

Camera not discovered by server:

• Ensure both devices are on the same network
• Check firewall rules (UDP port 5005)
• Verify the app's foreground service is running

Stream drops frequently:

• Reduce camera resolution in CameraStreamingService
• Use 5GHz Wi-Fi for less congestion
• Ensure stable power supply (use charger)

Server Issues

Server fails to start:

• Verify Python 3.9+
• Check CUDA installation for GPU support
• Verify YOLO models are downloaded in server/models/

High CPU usage:

• Reduce ai_interval in config
• Use GPU acceleration (ensure CUDA is installed)
• Reduce camera resolution

False fall alerts:

• Increase pose_conf threshold
• Adjust FALL_VELOCITY_THRESHOLD in TemporalTracker
• Calibrate floor detection for each camera angle

Missed fall detections:

• Decrease FALL_VELOCITY_THRESHOLD
• Ensure camera has full body in frame
• Verify lighting conditions

---

License

This project is provided as-is for the safety of the elderly. Thorough testing is required before deployment in a production environment.