A comprehensive smart home automation system running on Raspberry Pi CM4 with reTerminal display.

🎯 Perfect for: Home automation enthusiasts, Raspberry Pi tinkerers, and anyone wanting a self-hosted smart home hub with professional monitoring and network management.

This project provides a complete smart home solution featuring real-time monitoring, automation, network management, and hardware control - all running in a secure, containerized environment.

• 🏡 Complete Solution: Everything you need for home automation in one place
• 🔒 Privacy-First: Self-hosted, no cloud dependencies
• 📊 Professional Monitoring: Grafana dashboards rival enterprise solutions
• 🎮 Hardware Integration: Custom GPIO button controls for the reTerminal
• 💾 Disaster Recovery: Automated backup system with restore scripts
• 🛡️ Network Protection: Built-in ad-blocking and DNS filtering
• 🔧 Production-Ready: Watchdog systems, health checks, and auto-recovery

• 🏡 Home Automation: Home Assistant with full supervisor support
• 📊 Real-time Monitoring: Grafana + InfluxDB with custom dashboards
• 🌐 Network Management: Pi-hole DNS filtering and MQTT broker
• 📱 Unified Dashboard: Homepage with service overview
• ⚡ Service Monitoring: Uptime Kuma for availability tracking
• 🔧 Hardware Control: Custom Python scripts for reTerminal
• 💾 Automated Backups: Comprehensive backup and restore system
• 🛡️ System Health: Automated monitoring with email alerts
• 🎮 Kiosk Mode: Full-screen display modes for dashboards

┌─────────────────────────────────────────────────┐
│                 reTerminal Display               │
│        (Hardware Controls & Kiosk Mode)         │
├─────────────────────────────────────────────────┤
│              Homepage Dashboard                 │
│         (Unified Service Overview)              │
├─────────────────────────────────────────────────┤
│  Home Assistant  │  Grafana    │  Pi-hole      │
│  (Automation)    │ (Analytics) │  (DNS/AdBlock)│
├──────────────────┼─────────────┼───────────────┤
│   InfluxDB       │ Uptime Kuma │ MQTT Broker   │
│ (Time Series DB) │ (Monitoring)│ (IoT Messages)│
├─────────────────────────────────────────────────┤
│              Docker Container Layer             │
├─────────────────────────────────────────────────┤
│           Raspberry Pi OS (Debian)              │
└─────────────────────────────────────────────────┘

• Platform: Raspberry Pi CM4 with reTerminal
• Storage: eMMC (no SD card dependencies)
• Display: Built-in touchscreen with custom controls
• Connectivity: Ethernet, WiFi, GPIO access

• Raspberry Pi CM4 with reTerminal
• Docker and Docker Compose installed
• Git configured

# Clone repository
git clone https://github.com/andygmassey/rpi-smart-home-project.git
cd rpi-smart-home-project

# Setup environment
cp .env.example .env
nano .env  # Configure your passwords

# Deploy services
./scripts/system/deploy-all-services.sh

# Access main dashboard
open http://YOUR_DEVICE_IP:3002

• 🔧 Installation Guide - Complete setup instructions
• 📖 Usage Guide - Daily operations and maintenance
• 🛠️ Services Overview - Detailed service documentation
• 📋 Changelog - Version history and release notes
• 🤝 Contributing - How to contribute to this project

• 🔧 Script Reference - All automation scripts
• 🐳 Docker Services - Container configurations
• 💾 Backup System - Data protection
• ⚡ Hardware Control - reTerminal integration

📁 rpi-smart-home-project/
├── 📁 scripts/
│   ├── 📁 backup/          # Backup and restore automation
│   ├── 📁 monitoring/      # System health and metrics
│   ├── 📁 system/          # Service management utilities  
│   └── 📁 hardware/        # reTerminal hardware control
├── 📁 docker/              # Docker Compose configurations
│   ├── 📁 grafana-influx/  # Monitoring stack
│   ├── 📁 pihole/          # DNS and ad-blocking
│   ├── 📁 homepage/        # Unified dashboard
│   ├── 📁 uptime-kuma/     # Service monitoring
│   ├── 📁 mqtt-broker/     # IoT messaging
├── 📁 docs/                # Comprehensive documentation
├── 📄 .env.example         # Environment configuration template
└── 📄 .gitignore          # Security-focused exclusions

• backup-manager.sh - Interactive backup management
• create-app-backup.sh - Application data backup
• create-master-backup.sh - Golden master backup
• create-system-backup.sh - Full system backup
• backup-to-external.sh - External drive backup

• rpi_vitals_monitor.sh - System metrics collection
• continuous_monitoring.sh - 24/7 health monitoring
• timezone_monitoring_script.sh - Timezone change tracking

• manage-services.sh - Docker service management
• launch-ha-kiosk.sh - Home Assistant kiosk mode
• control-kiosk.sh - Display control utilities
• setup-vnc-remote.sh - Remote access setup

• multi_button_handler.py - reTerminal button control

Pi-hole provides network-wide DNS and ad-blocking with a bulletproof 3-layer watchdog system:

• Cooldown Protection: 5-minute minimum between restarts, max 3/hour
• Escalation: Cleanup → Soft restart → Hard restart → Alert
• Unlocator SmartDNS: Upstream DNS for geo-unblocking streaming services
• Database Capped: 7-day retention prevents runaway growth

See docs/WATCHDOG_SYSTEM.md for full documentation.

The system runs two concurrent OpenVPN tunnels for geographic traffic routing:

Both tunnels use route-nopull to prevent server-pushed routes, since Unlocator can assign the same IP pair to both tunnels, causing route confusion. Routes are added explicitly with dev tun0/dev tun1 by post-connect scripts:

• Primary VPN: setup-main-vpn-routes.sh pins 0.0.0.0/1 and 128.0.0.0/1 to dev tun0 via OpenVPN route-up
• UK VPN: setup-prime-routing.sh creates the ukvpn policy routing table for device-based routing through dev tun1

Selective traffic routing uses Linux policy routing (ip rule / ip route) to send specific LAN devices through the UK tunnel:

• Dedicated routing table (ukvpn): Separate routing table for UK-bound traffic
• Source-based routing: Specific LAN devices are policy-routed through the UK tunnel via ip rule
• NAT masquerade: Traffic from routed devices is NATed on tun1 for proper return routing

A SOCKS5 proxy (microsocks) runs on port 1080, bound to tun0's IP for VPN-routed access from other devices:

Routing scripts:

• /usr/local/bin/setup-main-vpn-routes.sh — Pins default routes to tun0 (called by OpenVPN route-up)
• /usr/local/bin/setup-prime-routing.sh — Creates policy routing table, ip rules, and NAT on UK VPN start
• /usr/local/bin/cleanup-prime-routing.sh — Removes UK routing rules on VPN stop

# Check status
sudo systemctl status unlocator-vpn uk-vpn-prime vpn-proxy

# Restart all VPN (order matters: main first, then UK, then proxy)
sudo systemctl restart unlocator-vpn && sleep 12 && sudo systemctl restart uk-vpn-prime && sleep 15 && sudo systemctl restart vpn-proxy

# Verify routing
ip route | grep tun           # Default routes should be dev tun0
ip rule list                  # Apple TV policy rule
ip route show table ukvpn     # UK routing table

All services run in isolated Docker containers with persistent data storage:

# Start monitoring stack
cd docker/grafana-influx && docker-compose up -d

# Start network services  
cd ../pihole && docker-compose up -d
cd ../mqtt-broker && docker-compose up -d

# Start dashboards
cd ../homepage && docker-compose up -d
cd ../uptime-kuma && docker-compose up -d

# Check all services
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Monitor resources
docker stats --no-stream

• System Health Monitoring: Every 6 hours with email alerts
• Vitals Collection: Every minute to InfluxDB
• Application Backup: Weekly automated backup
• Configuration Backup: Continuous Git versioning

# Quick application backup
./scripts/backup/create-app-backup.sh

# Full system backup
./scripts/backup/create-master-backup.sh

# Interactive backup manager
./scripts/backup/backup-manager.sh

# List available backups
ls ~/backups/

# Restore from backup
./scripts/backup/backup-manager.sh restore

# Start button handler
python3 scripts/hardware/multi_button_handler.py

# Launch kiosk mode
./scripts/system/launch-ha-kiosk.sh

# Control display
./scripts/system/control-kiosk.sh [start|stop|restart]

• Multi-button Control: Custom actions for hardware buttons
• Display Management: Automatic brightness and power control
• GPIO Integration: Full access to Raspberry Pi GPIO
• Touch Interface: Direct touchscreen interaction

• 🔐 Environment Variables: No hardcoded passwords
• 🗂️ Comprehensive .gitignore: Sensitive files excluded
• 🔒 Private Repository: Code safely stored
• 🛡️ Container Isolation: Services run in isolated containers

• 🌐 Pi-hole DNS Filtering: Network-wide ad and malware blocking
• 🔒 Local Network Only: No external dependencies required
• 📊 Traffic Monitoring: Full network visibility

• 📊 Real-time Metrics: System health dashboards
• 📧 Email Alerts: Automated problem notifications
• 📈 Historical Data: Long-term performance tracking

The system automatically monitors:

• Memory Usage: Alerts at >90%
• Swap Usage: Alerts at >50%
• CPU Temperature: Alerts at >80°C
• Load Average: Alerts at >8.0
• Service Status: Container health checks
• Disk Space: Storage monitoring

• Email Notifications: Configurable SMTP alerts
• Dashboard Alerts: Grafana alert rules
• Service Monitoring: Uptime Kuma notifications

# Make changes
git add .
git commit -m "Update configuration"
git push

# Create feature branch
git checkout -b new-feature

# System updates
sudo apt update && sudo apt upgrade -y

# Docker cleanup
docker system prune -f

# Service restart
./scripts/system/manage-services.sh restart

# Check system health
./scripts/monitoring/system-health-check.sh

# View service logs
docker logs <service-name>

# Restart all services
./scripts/system/manage-services.sh restart

# Emergency backup
./scripts/backup/create-app-backup.sh

• 📖 Full Installation Guide
• 📚 Complete Usage Guide
• 🛠️ Service Details

1. Check service logs: docker logs <service>
2. Run system health check: ./scripts/monitoring/system-health-check.sh
3. Review documentation in docs/ directory
4. Check GitHub issues for known problems

✅ Production Ready

• All services deployed and monitored
• Comprehensive backup system active
• Full documentation complete
• Security hardening implemented
• Hardware integration functional

This project is ideal for:

• 🏠 Home Automation Enthusiasts: Complete control over your smart home
• 🔐 Privacy-Conscious Users: Keep your data on your own hardware
• 📊 Data Nerds: Beautiful real-time dashboards for system monitoring
• 🎓 Learning Projects: Great for understanding Docker, networking, and automation
• 🏢 Home Lab: Professional-grade monitoring for your home network
• 🌐 Network Administrators: Family network management with ad-blocking and DNS control

Future enhancements being considered:

• Zigbee/Z-Wave device integration examples
• Energy monitoring dashboards
• Automated offsite backup to cloud storage
• Mobile app companion
• Voice assistant integration (Alexa/Google Home)
• Advanced automation examples
• Kubernetes deployment option
• Multi-device support documentation

Have an idea? Open an issue or discussion to suggest new features!

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Thanks to everyone who has contributed to this project!

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

Third-party Docker images and services retain their respective licenses. See LICENSE for full details.

• Pi-hole - Network-wide ad blocking
• Home Assistant - Open source home automation
• Grafana - Beautiful monitoring dashboards
• SeeedStudio - reTerminal hardware platform
• Raspberry Pi Foundation - Amazing single-board computers

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• ❓ Questions: GitHub Discussions Q&A
• 📢 Announcements: GitHub Discussions