AdGuard Control Hub

A comprehensive Home Assistant integration for managing your AdGuard Home instance with advanced control and monitoring capabilities.

Features

Switches

• AdGuard Protection: Master switch that controls all AdGuard features
• DNS Filtering: Enables DNS filtering using blocklists
• Safe Browsing: Blocks known phishing and malware sites
• Parental Control: Blocks adult content
• Safe Search: Enforces safe search on search engines
• Query Log: Records DNS queries for statistics

Sensors

• DNS Queries: Total number of DNS queries processed
• Blocked Queries: Number of queries blocked by filtering
• Blocked Percentage: Percentage of queries that were blocked
• Active Filter Rules: Number of active filtering rules loaded
• Average Processing Time: Average DNS query processing time

Binary Sensors

• AdGuard Home Running: Shows if AdGuard Home is responsive

Installation

HACS (Recommended)

1. Install HACS if you haven't already
2. In HACS, go to "Integrations"
3. Click the "+" button and search for "AdGuard Control Hub"
4. Click "Install"
5. Restart Home Assistant

Manual Installation

1. Download the latest release from the releases page
2. Extract the adguard-control-hub.zip file
3. Copy the custom_components/adguard_control_hub folder to your Home Assistant's custom_components directory
4. Restart Home Assistant

Configuration

1. In Home Assistant, go to Settings → Devices & Services
2. Click "+ ADD INTEGRATION"
3. Search for "AdGuard Control Hub" and select it
4. Fill in your AdGuard Home connection details:
   • Host: IP address or hostname of your AdGuard Home instance
   • Port: Port number (default: 3000)
   • Username: Admin username (if authentication is enabled)
   • Password: Admin password (if authentication is enabled)
   • Use HTTPS: Enable if using HTTPS
   • Verify SSL: Verify SSL certificates

Requirements

• AdGuard Home v0.107.0 or newer
• Home Assistant 2023.5.0 or newer
• Network access to your AdGuard Home instance

Supported AdGuard Home Versions

This integration has been tested with:

• AdGuard Home v0.107.50+
• AdGuard Home v0.108.x
• AdGuard Home v0.109.x

Troubleshooting

Connection Issues

• Ensure AdGuard Home is running and accessible from Home Assistant
• Check firewall settings on the AdGuard Home host
• Verify the correct port is being used
• Test connection manually using curl: curl http://your-adguard-ip:port/control/status

Authentication Issues

• Verify username and password are correct
• Ensure the user account has admin privileges in AdGuard Home
• Try connecting without authentication first to isolate the issue

Feature Not Working

• Check AdGuard Home logs for any error messages
• Verify the specific feature is enabled in AdGuard Home
• Some features require specific AdGuard Home configurations

Development

Setting up Development Environment

1. Clone the repository
2. Install development dependencies: pip install -r requirements_test.txt
3. Run tests: pytest tests/
4. Run linting: black custom_components/ && isort custom_components/

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

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

Acknowledgments

• AdGuard Team for creating AdGuard Home
• Home Assistant community for the integration framework
• All contributors and testers

---