A real-time home security application that uses YOLOv8 computer vision to detect predefined targets (people, objects) and automatically triggers MQTT notifications when matches are detected.
This system monitors video feeds in real-time, detects objects or persons using YOLOv8, and publishes MQTT messages when configured targets are detected. Perfect for home automation, security monitoring, and IoT integration.
- Real-time Detection: Process video feeds from webcams, RTSP streams, or video files
- YOLOv8 Integration: State-of-the-art object detection with multiple model options
- Target Matching: Configure specific objects or people to monitor
- MQTT Publishing: Automatic notifications to your MQTT broker with detection metadata
- Intuitive UI: Streamlit-based interface for easy configuration and monitoring
- Live Visualization: See detections in real-time with bounding boxes
- Detection Logging: Track all detection events with timestamps and confidence scores
- Home security monitoring
- Package delivery detection
- Pet monitoring
- Specific object tracking
- Integration with Home Assistant, Node-RED, or other home automation platforms
- Python 3.10 or higher
- Webcam, RTSP camera, or video file
- MQTT broker (local or remote)
-
Clone the repository
git clone <repository-url> cd customIOTSecurity
-
Create a virtual environment (recommended)
python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
-
Install dependencies
pip install -r requirements.txt
The first time you run the application, YOLOv8 will automatically download the selected model.
streamlit run app.pyThe application will open in your default web browser at http://localhost:8501
In the sidebar, select your video source:
- Webcam: Choose camera index (usually 0 for built-in camera)
- RTSP Stream: Enter RTSP URL (e.g.,
rtsp://192.168.1.100:554/stream) - Video File: Provide path to local video file
Choose a YOLOv8 model based on your needs:
- yolov8n.pt: Nano - Fastest, lowest accuracy
- yolov8s.pt: Small - Balanced (recommended)
- yolov8m.pt: Medium - More accurate
- yolov8l.pt: Large - Most accurate, slower
- Custom: Provide path to your custom trained model
Click "Load Model & Get Classes" to see available detection classes.
- Target Class: Select the object/person class to monitor (e.g., "person", "cell phone", "bottle")
- Confidence Threshold: Set minimum confidence (0.0-1.0) for valid detections
Configure your MQTT broker:
- Broker Address: Hostname or IP address
- Port: Usually 1883 for standard MQTT
- Topic: Default is
irvine/home/bedroom/item(customize as needed) - Username/Password: Optional authentication credentials
- Include Image: Optionally include base64-encoded detection crop in payload
Click "Start Detection" to begin monitoring. The system will:
- Connect to your video source
- Load the YOLOv8 model
- Start processing frames in real-time
- Display live feed with bounding boxes
- Publish MQTT messages when targets are detected
When a target is detected, the system publishes a JSON message to the configured topic:
{
"class": "person",
"confidence": 0.92,
"timestamp": "2025-11-16T12:34:56.789",
"bbox": [120, 45, 340, 580],
"frame_id": 1034,
"image": "<base64-encoded-jpeg-optional>"
}- class: Detected object class name
- confidence: Detection confidence score (0.0-1.0)
- timestamp: ISO 8601 formatted timestamp
- bbox: Bounding box coordinates [x1, y1, x2, y2]
- frame_id: Sequential frame identifier
- image: Optional base64-encoded JPEG of detection crop
┌─────────────────────────────────────────────────────────┐
│ Streamlit UI (app.py) │
│ - Configuration Controls - Live Video Display │
│ - Statistics Dashboard - Detection Logs │
└──────────────┬──────────────────────────────────────────┘
│
┌───────┴───────┐
│ │
┌──────▼─────┐ ┌──────▼─────────┐
│ Video │ │ Detection │
│ Source │─▶│ Engine │
│ │ │ (YOLOv8) │
└────────────┘ └────────┬───────┘
│
┌──────▼────────┐
│ MQTT │
│ Publisher │
└───────────────┘
- app.py: Main Streamlit application and UI
- video_source.py: Video capture handler (webcam, RTSP, file)
- detection_engine.py: YOLOv8 detection and target matching
- mqtt_publisher.py: MQTT client with retry logic
- utils.py: Image processing and annotation utilities
You can set default values using environment variables:
export MQTT_BROKER="localhost"
export MQTT_PORT="1883"
export MQTT_TOPIC="irvine/home/bedroom/item"
export DEFAULT_MODEL="yolov8s.pt"To use a custom trained YOLOv8 model:
- Train your model using Ultralytics YOLOv8
- Save the
.ptfile - Select "Custom" in the model dropdown
- Provide the path to your model file
- Camera not detected: Try different camera indices (0, 1, 2...)
- RTSP connection fails: Verify URL format and network connectivity
- Video file won't load: Check file path and format (MP4, AVI supported)
- Connection refused: Verify broker is running and accessible
- Authentication failed: Check username/password
- Messages not received: Verify topic name matches subscriber
- Low FPS: Use a smaller model (yolov8n.pt) or reduce video resolution
- High CPU usage: Consider using GPU acceleration (install
torchwith CUDA) - Detection latency: Lower confidence threshold or use faster model
Expected performance on standard hardware:
| Model | FPS (CPU) | FPS (GPU) | Accuracy |
|---|---|---|---|
| yolov8n | 25-30 | 100+ | Good |
| yolov8s | 15-20 | 80+ | Better |
| yolov8m | 8-12 | 50+ | Great |
| yolov8l | 4-8 | 30+ | Best |
- Network Security: Use TLS/SSL for MQTT connections in production
- Authentication: Always use MQTT username/password in production
- Camera Access: Limit network exposure of camera feeds
- Data Privacy: Be mindful of privacy when capturing video
Future enhancements (v2.0+):
- Multi-camera support
- Multiple simultaneous targets
- Face recognition integration
- Push notifications (Pushover, Telegram)
- Historical event database
- Web API for integration
- Mobile app support
- Cloud deployment options
[Specify your license here]
Contributions are welcome! Please feel free to submit pull requests or open issues.
For issues, questions, or suggestions, please open an issue on GitHub.
- Ultralytics YOLOv8 for the detection model
- Streamlit for the UI framework
- Paho MQTT for MQTT client library
Version: 1.0 Last Updated: 2025-11-16