# AdGuard Control Hub

[![GitHub Release][releases-shield]][releases]
[![GitHub Activity][commits-shield]][commits]
[![License][license-shield]](LICENSE)
[![hacs][hacsbadge]][hacs]

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](https://hacs.xyz/) 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](https://github.com/your-username/adguard-control-hub/releases)
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](LICENSE) file for details.

## Acknowledgments

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

---

[releases-shield]: https://img.shields.io/github/release/your-username/adguard-control-hub.svg?style=for-the-badge
[releases]: https://github.com/your-username/adguard-control-hub/releases
[commits-shield]: https://img.shields.io/github/commit-activity/y/your-username/adguard-control-hub.svg?style=for-the-badge
[commits]: https://github.com/your-username/adguard-control-hub/commits/main
[license-shield]: https://img.shields.io/github/license/your-username/adguard-control-hub.svg?style=for-the-badge
[hacs]: https://github.com/hacs/integration
[hacsbadge]: https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge