# 🛡️ AdGuard Control Hub

**The ultimate Home Assistant integration for AdGuard Home**

Transform your AdGuard Home into a smart network management powerhouse with comprehensive Home Assistant integration featuring client management, service blocking, and real-time monitoring.

## ✨ Features

### 🎯 Smart Client Management
- **Automatic Discovery**: Automatically discover and manage AdGuard clients
- **Individual Controls**: Per-client protection and filtering controls
- **Real-time Statistics**: Monitor client activity and blocking statistics
- **Bulk Operations**: Manage multiple clients simultaneously

### 🛡️ Advanced Service Blocking
- **Granular Control**: Block specific services (YouTube, Netflix, Gaming, etc.) per client
- **Emergency Access**: Quick emergency unblock for critical situations
- **Scheduled Blocking**: Time-based service restrictions via automations
- **Custom Services**: Support for custom service definitions

### 🏠 Rich Home Assistant Integration
- **🔧 Switches**: Global and per-client protection controls
- **📊 Sensors**: DNS queries, blocked queries, processing time, client counts
- **🚨 Binary Sensors**: Protection status, server status, safety features
- **⚙️ Services**: Comprehensive automation-friendly service calls
- **🔌 Device Integration**: Proper device registry with configuration URLs

## 🚀 Quick Start

### Prerequisites
- Home Assistant 2024.12.0 or later
- AdGuard Home with API access enabled
- Network connectivity between Home Assistant and AdGuard Home

### Installation via HACS (Recommended)

1. **Add Custom Repository**
   - Open HACS → Integrations
   - Click the three dots (⋮) → Custom repositories
   - Repository: `https://git.sq4ind.eu/sq4ind/adguard-control-hub`
   - Category: Integration
   - Click "Add"

2. **Install Integration**
   - Search for "AdGuard Control Hub"
   - Click "Download"
   - Restart Home Assistant

3. **Configure Integration**
   - Go to Settings → Devices & Services
   - Click "Add Integration"
   - Search for "AdGuard Control Hub"
   - Follow the configuration wizard

## ⚙️ Configuration

### Basic Configuration
| Field | Description | Default | Required |
|-------|-------------|---------|----------|
| **Host** | AdGuard Home IP or hostname | - | ✅ |
| **Port** | AdGuard Home web interface port | 3000 | ✅ |
| **Username** | Admin username | - | ❌ |
| **Password** | Admin password | - | ❌ |
| **Use SSL** | Enable HTTPS connection | False | ❌ |
| **Verify SSL** | Verify SSL certificates | True | ❌ |

## 📊 Available Entities

### Switches
- `switch.adguard_protection` - Global protection toggle
- `switch.adguard_{client_name}` - Per-client protection toggle

### Sensors
- `sensor.adguard_dns_queries` - Total DNS queries count
- `sensor.adguard_blocked_queries` - Total blocked queries count
- `sensor.adguard_blocking_percentage` - Blocking percentage
- `sensor.adguard_clients_count` - Number of configured clients
- `sensor.adguard_average_processing_time` - Query processing time
- `sensor.adguard_filtering_rules` - Number of filtering rules

### Binary Sensors
- `binary_sensor.adguard_protection_status` - Protection status
- `binary_sensor.adguard_server_running` - Server running status
- `binary_sensor.adguard_safebrowsing` - SafeBrowsing status
- `binary_sensor.adguard_parental_control` - Parental control status
- `binary_sensor.adguard_safe_search` - Safe search status

## 🔧 Available Services

- **`adguard_hub.block_services`**: Block specific services for clients
- **`adguard_hub.unblock_services`**: Unblock services for clients
- **`adguard_hub.emergency_unblock`**: Temporarily disable protection
- **`adguard_hub.add_client`**: Add new client configuration
- **`adguard_hub.remove_client`**: Remove client configuration
- **`adguard_hub.refresh_data`**: Manually refresh data from AdGuard Home

## 🐛 Troubleshooting

### Common Issues

**Connection Failed**
- Verify AdGuard Home is running and accessible
- Check firewall settings on AdGuard Home server
- Ensure correct host and port configuration

**Authentication Errors**
- Verify username and password are correct
- Check if AdGuard Home has authentication enabled

**Missing Clients**
- Wait for next refresh cycle (30 seconds by default)
- Use the "Refresh Data" service to force update

## 🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

## 📄 License

This project is licensed under the MIT License.

---

Made with ❤️ for the Home Assistant community