Clone
1
Changelog
sq4ind edited this page 2025-09-28 12:48:14 +00:00
Table of Contents
- 📝 Changelog
- [Unreleased]
- [1.0.0] - 2025-01-XX
- 🎉 Initial Release
- ✨ Added
- Core Integration
- Entity Support
- Services & Automation
- Supported Services
- Advanced Features
- Dashboard Integration
- 🛠️ Technical Features
- 🏠 Home Assistant Integration
- 📱 Dashboard Examples
- 🤖 Automation Examples
- 🎯 Use Cases
- 🔧 Installation & Setup
- 🌟 Highlights
- 📋 Version History Summary
- 🔮 Roadmap
📝 Changelog
All notable changes to AdGuard Control Hub will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]
Added
- Placeholder for upcoming features
Changed
- Placeholder for upcoming changes
Fixed
- Placeholder for upcoming fixes
[1.0.0] - 2025-01-XX
🎉 Initial Release
The first stable release of AdGuard Control Hub, providing comprehensive Home Assistant integration for AdGuard Home.
✨ Added
Core Integration
- Complete AdGuard Home API Integration - Full API wrapper supporting all major endpoints
- Home Assistant Config Flow - User-friendly configuration interface with validation
- Update Coordinator Pattern - Efficient data fetching with configurable intervals
- Multi-Instance Support - Connect to multiple AdGuard Home instances
Entity Support
- Global Protection Switch - Master toggle for AdGuard Home protection
- Client Switches - Individual protection control for each AdGuard client
- Service Blocking Switches - Per-client service blocking controls (YouTube, Netflix, Gaming, etc.)
- Statistics Sensors - Real-time DNS query and blocking statistics
- Binary Sensors - Status indicators for protection and client connectivity
Services & Automation
- Client Management Services:
add_client
- Add new client devices programmaticallyupdate_client
- Modify existing client configurationsremove_client
- Remove clients from AdGuard Home
- Service Blocking Services:
block_services
- Block specific services for clients with scheduling supportunblock_services
- Remove service blocks from clients
- Bulk Operations:
bulk_update_clients
- Update multiple clients using pattern matching
- Emergency Access:
emergency_unblock
- Temporary unblock for urgent internet access
Supported Services
- Social Media: YouTube, Facebook, Instagram, TikTok, Twitter, Snapchat, Reddit
- Entertainment: Netflix, Disney+, Spotify, Twitch
- Gaming: Steam, Epic Games, Roblox, general gaming services
- Shopping: Amazon, eBay
- Communication: WhatsApp, Telegram, Discord
- Security Categories: Adult content, gambling, torrents
Advanced Features
- Time-Based Scheduling - Block services during specific hours/days
- Pattern Matching - Bulk operations using wildcard patterns (
Kids*
,Work*
) - Emergency Override - Temporary access for urgent situations
- Client Auto-Discovery - Automatic entity creation for new clients
- SSL/TLS Support - Secure connections with certificate validation
Dashboard Integration
- Rich Lovelace Cards - Pre-built dashboard examples
- Mobile Optimization - Touch-friendly controls for mobile devices
- Emergency Controls - Quick access buttons for urgent situations
- Statistics Visualization - Real-time charts and graphs
🛠️ Technical Features
Development & Quality
- Comprehensive Test Suite - Unit and integration tests with >90% coverage
- CI/CD Pipeline - Automated testing, security scanning, and releases
- Code Quality Tools - Black, Flake8, isort, MyPy, Bandit integration
- Pre-commit Hooks - Automatic code formatting and validation
- Type Hints - Full type annotation for better IDE support
Security & Performance
- Security Scanning - Automated vulnerability detection with Bandit and Safety
- Rate Limiting - Respectful API usage to prevent server overload
- Error Handling - Comprehensive error recovery and user feedback
- Performance Optimization - Efficient data fetching and caching
- Connection Pooling - Reused HTTP sessions for better performance
Documentation
- Comprehensive Wiki - Complete documentation with examples
- Installation Guides - HACS and manual installation instructions
- Dashboard Examples - Ready-to-use Lovelace configurations
- Automation Examples - Real-world automation scenarios
- Troubleshooting Guide - Solutions for common issues
- API Reference - Technical documentation for developers
🏠 Home Assistant Integration
Compatibility
- Home Assistant 2023.1+ - Full compatibility with modern HA versions
- HACS Support - Easy installation and automatic updates
- Multi-Platform - Supports all major Home Assistant installation methods
Configuration Options
adguard_hub:
scan_interval: 30 # Update frequency in seconds
auto_create_clients: true # Auto-create entities for new clients
enable_statistics: true # Collect detailed statistics
blocked_services_as_switches: true # Create service blocking switches
client_naming_pattern: "adguard_{name}" # Entity naming pattern
Entity Naming
switch.adguard_protection
- Global protection toggleswitch.adguard_client_{name}
- Per-client protectionswitch.adguard_client_{name}_service_{service}
- Per-client service blockssensor.adguard_queries_today
- DNS query statisticsbinary_sensor.adguard_filtering_enabled
- Protection status
📱 Dashboard Examples
Family Control Dashboard
- Kids' device management
- Parental control toggles
- Service blocking controls
- Quick action buttons (Study Mode, Free Time, Bedtime)
Work Productivity Dashboard
- Work device controls
- Distraction blocking
- Focus mode automation
- Break time management
Network Analytics Dashboard
- Real-time statistics
- Query history graphs
- Client activity monitoring
- System health indicators
🤖 Automation Examples
Parental Controls
automation:
- alias: "Kids Bedtime - Block Entertainment"
trigger:
platform: time
at: "20:00:00"
action:
service: adguard_hub.block_services
data:
client_name: "Kids iPad"
services: ["youtube", "netflix", "gaming", "social"]
Work Productivity
automation:
- alias: "Work Focus Mode"
trigger:
platform: state
entity_id: input_boolean.work_focus_mode
to: 'on'
action:
service: adguard_hub.bulk_update_clients
data:
client_pattern: "Work*"
settings:
blocked_services: ["social", "entertainment"]
Presence-Based Rules
automation:
- alias: "Away Mode - Strict Filtering"
trigger:
platform: state
entity_id: group.family
to: 'not_home'
action:
service: adguard_hub.bulk_update_clients
data:
client_pattern: "*"
settings:
parental_enabled: true
safebrowsing_enabled: true
🎯 Use Cases
Family Management
- Bedtime Routines: Automatically block entertainment at bedtime
- Homework Time: Restrict social media during study hours
- Weekend Flexibility: Different rules for weekends vs school days
- Age-Appropriate Content: Parental controls and safe search
Work Productivity
- Focus Sessions: Block distracting websites during work hours
- Meeting Mode: Ensure bandwidth availability during calls
- Break Management: Scheduled access to social media
- Deadline Crunch: Temporary strict blocking for important projects
Network Management
- Guest Controls: Automatic restrictions for visitor devices
- Bandwidth Management: Block heavy services when needed
- Security Enforcement: Mandatory safe browsing and filtering
- Emergency Access: Quick override for urgent internet needs
🔧 Installation & Setup
HACS Installation (Recommended)
- Add custom repository:
https://your-gitea-domain.com/your-username/adguard-control-hub
- Install "AdGuard Control Hub"
- Restart Home Assistant
- Configure via UI: Settings → Devices & Services
Manual Installation
- Download latest release
- Extract to
custom_components/adguard_hub/
- Restart Home Assistant
- Add integration via UI
Configuration Requirements
- AdGuard Home IP address and port
- Admin username and password
- Optional: SSL configuration for secure connections
🌟 Highlights
- 🎯 Comprehensive Control: Complete management of AdGuard Home from Home Assistant
- 🏠 Smart Integration: Native Home Assistant entities and services
- 👨👩👧👦 Family-Friendly: Perfect for parental controls and family internet management
- 💼 Work-Ready: Focus modes and productivity features for remote work
- 🤖 Automation-First: Designed for advanced Home Assistant automations
- 📱 Mobile-Optimized: Touch-friendly controls for phones and tablets
- 🔒 Security-Focused: Comprehensive security scanning and safe defaults
- 🛠️ Developer-Friendly: Well-documented API and extensive development tools
📋 Version History Summary
Version | Release Date | Key Features |
---|---|---|
[1.0.0] | 2025-01-XX | Initial release with full AdGuard Home integration |
🔮 Roadmap
Planned Features
Version 1.1.0
- Enhanced Statistics: Detailed per-client analytics and reporting
- Mobile App Integration: Control from Home Assistant mobile app
- Advanced Scheduling: Recurring schedules and holiday exceptions
- Notification Integration: Smart alerts for rule changes and activities
Version 1.2.0
- Multi-Language Support: Translations for major languages
- Theme Integration: Support for Home Assistant themes
- Backup & Restore: Configuration backup and migration tools
- Performance Dashboard: Integration health and performance metrics
Version 2.0.0
- AdGuard Home v2 API: Support for new API features
- Machine Learning: Intelligent blocking suggestions
- Cloud Sync: Multi-instance configuration synchronization
- Advanced Analytics: Usage patterns and optimization recommendations
Community Requests
Based on user feedback, we're considering:
- DNS-over-HTTPS Configuration: Advanced DNS settings management
- Custom Block Lists: Integration with custom filtering lists
- Geolocation Blocking: Country-based access restrictions
- Bandwidth Monitoring: Network usage tracking and limiting
- VPN Integration: Automatic VPN controls for different clients
Want to contribute to the next release? Check out our Contributing Guide and Development Setup!
Having issues? See our Troubleshooting Guide or report a bug.
Questions about features? Visit our Service Reference or ask in Discussions.