1
Changelog
sq4ind edited this page 2025-09-28 12:48:14 +00:00

📝 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 programmatically
    • update_client - Modify existing client configurations
    • remove_client - Remove clients from AdGuard Home
  • Service Blocking Services:
    • block_services - Block specific services for clients with scheduling support
    • unblock_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 toggle
  • switch.adguard_client_{name} - Per-client protection
  • switch.adguard_client_{name}_service_{service} - Per-client service blocks
  • sensor.adguard_queries_today - DNS query statistics
  • binary_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

  1. Add custom repository: https://your-gitea-domain.com/your-username/adguard-control-hub
  2. Install "AdGuard Control Hub"
  3. Restart Home Assistant
  4. Configure via UI: Settings → Devices & Services

Manual Installation

  1. Download latest release
  2. Extract to custom_components/adguard_hub/
  3. Restart Home Assistant
  4. 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.