public/adguard-control-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit
Some checks failed
Tests / test (3.13) (push) Failing after 23s
Details
Tests / lint (push) Failing after 20s
Details
Tests / hacs (push) Failing after 52s
Details

Browse Source 
Signed-off-by: Rafal Zielinski <sq4ind@gmail.com>
This commit is contained in:
Rafal Zielinski
2025-10-02 16:00:15 +01:00
commit d4cdcc04c0
25 changed files with 2650 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

527
wiki/Advanced-Usage.md Normal file
View File

@@ -0,0 +1,527 @@
# Advanced Usage
This guide covers advanced features, automations, and customizations for AdGuard Control Hub.
## Lovelace Dashboard Cards
Create informative dashboard cards to monitor and control your AdGuard Home instance.
### Protection Status Card
```yaml
type: entities
title: AdGuard Protection
entities:
- switch.adguard_protection
- switch.adguard_dns_filtering
- switch.adguard_safe_browsing
- switch.adguard_parental_control
- switch.adguard_safe_search
- switch.adguard_query_log
show_header_toggle: true
state_color: true
```
### Statistics Overview Card
```yaml
type: glance
title: AdGuard Statistics
entities:
- entity: sensor.adguard_dns_queries
name: Total Queries
- entity: sensor.adguard_blocked_queries
name: Blocked
- entity: sensor.adguard_blocked_percentage
name: Blocked %
- entity: sensor.adguard_average_processing_time
name: Avg Time
columns: 2
show_state: true
show_name: true
```
### Historical Chart Card
```yaml
type: history-graph
title: DNS Activity (24h)
entities:
- sensor.adguard_dns_queries
- sensor.adguard_blocked_queries
hours_to_show: 24
refresh_interval: 60
```
### Protection Control Card
```yaml
type: custom:mushroom-chips-card
chips:
- type: entity
entity: switch.adguard_protection
icon_color: green
tap_action:
action: toggle
- type: entity
entity: switch.adguard_parental_control
icon_color: blue
tap_action:
action: toggle
- type: entity
entity: binary_sensor.adguard_home_running
icon_color: red
```
## Automations
### Basic Automations
#### Enable Parental Controls During School Hours
```yaml
automation:
- alias: "AdGuard: Enable Parental Controls - School Hours"
trigger:
- platform: time
at: "08:00:00"
condition:
- condition: time
weekday:
- mon
- tue
- wed
- thu
- fri
action:
- service: switch.turn_on
target:
entity_id: switch.adguard_parental_control
- service: notify.mobile_app_your_phone
data:
title: "AdGuard"
message: "Parental controls enabled for school hours"
- alias: "AdGuard: Disable Parental Controls - After School"
trigger:
- platform: time
at: "16:00:00"
condition:
- condition: time
weekday:
- mon
- tue
- wed
- thu
- fri
action:
- service: switch.turn_off
target:
entity_id: switch.adguard_parental_control
- service: notify.mobile_app_your_phone
data:
title: "AdGuard"
message: "Parental controls disabled - school day ended"
```
#### Temporarily Disable Filtering
```yaml
automation:
- alias: "AdGuard: Temporary Disable Protection"
trigger:
- platform: event
event_type: call_service
event_data:
domain: script
service: disable_adguard_temporarily
action:
- service: switch.turn_off
target:
entity_id: switch.adguard_protection
- delay: "00:10:00" # 10 minutes
- service: switch.turn_on
target:
entity_id: switch.adguard_protection
- service: notify.mobile_app_your_phone
data:
title: "AdGuard"
message: "Protection re-enabled after temporary disable"
script:
disable_adguard_temporarily:
alias: "Disable AdGuard for 10 minutes"
sequence:
- event: call_service
event_data:
domain: script
service: disable_adguard_temporarily
```
### Advanced Automations
#### Dynamic Protection Based on Network Activity
```yaml
automation:
- alias: "AdGuard: High Activity Alert"
trigger:
- platform: numeric_state
entity_id: sensor.adguard_dns_queries
above: 5000
for: "00:05:00"
action:
- service: notify.mobile_app_your_phone
data:
title: "AdGuard Alert"
message: "High DNS activity detected: {{ states('sensor.adguard_dns_queries') }} queries"
- service: switch.turn_on
target:
entity_id: switch.adguard_safe_browsing
- service: switch.turn_on
target:
entity_id: switch.adguard_dns_filtering
- alias: "AdGuard: Performance Monitoring"
trigger:
- platform: numeric_state
entity_id: sensor.adguard_average_processing_time
above: 100
for: "00:02:00"
action:
- service: persistent_notification.create
data:
title: "AdGuard Performance Warning"
message: |
DNS response time is high: {{ states('sensor.adguard_average_processing_time') }}ms
Current queries: {{ states('sensor.adguard_dns_queries') }}
Active rules: {{ states('sensor.adguard_active_filter_rules') }}
notification_id: adguard_performance
```
#### Guest Network Protection
```yaml
automation:
- alias: "AdGuard: Guest Network - Enable Strict Filtering"
trigger:
- platform: device_tracker
entity_id: device_tracker.guest_device
to: "home"
action:
- service: switch.turn_on
target:
entity_id:
- switch.adguard_safe_browsing
- switch.adguard_parental_control
- switch.adguard_safe_search
- service: notify.mobile_app_your_phone
data:
title: "AdGuard"
message: "Guest device connected - strict filtering enabled"
- alias: "AdGuard: Guest Network - Restore Normal Settings"
trigger:
- platform: device_tracker
entity_id: device_tracker.guest_device
to: "not_home"
for: "00:05:00"
action:
- service: switch.turn_off
target:
entity_id: switch.adguard_parental_control
- service: notify.mobile_app_your_phone
data:
title: "AdGuard"
message: "Guest device disconnected - normal filtering restored"
```
### Monitoring and Alerting
#### AdGuard Home Downtime Alert
```yaml
automation:
- alias: "AdGuard: Downtime Alert"
trigger:
- platform: state
entity_id: binary_sensor.adguard_home_running
to: "off"
for: "00:02:00"
action:
- service: notify.mobile_app_your_phone
data:
title: "AdGuard Home Down"
message: "AdGuard Home is not responding. Check the service status."
data:
priority: high
color: red
- alias: "AdGuard: Service Restored"
trigger:
- platform: state
entity_id: binary_sensor.adguard_home_running
to: "on"
condition:
- condition: state
entity_id: binary_sensor.adguard_home_running
state: "off"
for: "00:01:00"
action:
- service: notify.mobile_app_your_phone
data:
title: "AdGuard Home Restored"
message: "AdGuard Home is responding again."
data:
color: green
```
## Scripts
### Quick Control Scripts
#### Emergency Bypass Script
```yaml
script:
adguard_emergency_bypass:
alias: "AdGuard Emergency Bypass"
description: "Quickly disable all protection for troubleshooting"
sequence:
- service: switch.turn_off
target:
entity_id: switch.adguard_protection
- service: timer.start
target:
entity_id: timer.adguard_bypass
data:
duration: "00:15:00"
- service: persistent_notification.create
data:
title: "AdGuard Bypass Active"
message: "All protection disabled for 15 minutes"
notification_id: adguard_bypass
timer:
adguard_bypass:
duration: "00:15:00"
restore: true
```
#### Weekly Statistics Report
```yaml
script:
adguard_weekly_report:
alias: "AdGuard Weekly Report"
sequence:
- service: notify.mobile_app_your_phone
data:
title: "AdGuard Weekly Report"
message: |
Total Queries: {{ states('sensor.adguard_dns_queries') }}
Blocked: {{ states('sensor.adguard_blocked_queries') }}
Block Rate: {{ states('sensor.adguard_blocked_percentage') }}%
Avg Response Time: {{ states('sensor.adguard_average_processing_time') }}ms
Filter Rules: {{ states('sensor.adguard_active_filter_rules') }}
automation:
- alias: "AdGuard: Weekly Report"
trigger:
- platform: time
at: "09:00:00"
condition:
- condition: time
weekday:
- sun
action:
- service: script.adguard_weekly_report
```
## Custom Templates
### Template Sensors
#### Protection Status Summary
```yaml
template:
- sensor:
- name: "AdGuard Protection Summary"
state: >
{% set protection = states('switch.adguard_protection') %}
{% set filtering = states('switch.adguard_dns_filtering') %}
{% set safebrowsing = states('switch.adguard_safe_browsing') %}
{% set parental = states('switch.adguard_parental_control') %}
{% if protection == 'off' %}
Disabled
{% else %}
{% set active = [filtering, safebrowsing, parental] | select('eq', 'on') | list | length %}
{% if active == 3 %}
Full Protection
{% elif active == 0 %}
Basic Protection
{% else %}
Partial Protection ({{ active }}/3)
{% endif %}
{% endif %}
icon: >
{% set protection = states('switch.adguard_protection') %}
{% if protection == 'off' %}
mdi:shield-off
{% else %}
mdi:shield-check
{% endif %}
```
#### Daily Block Statistics
```yaml
template:
- sensor:
- name: "AdGuard Daily Block Rate"
state: >
{% set queries = states('sensor.adguard_dns_queries') | int(0) %}
{% set blocked = states('sensor.adguard_blocked_queries') | int(0) %}
{% if queries > 0 %}
{{ ((blocked / queries) * 100) | round(1) }}
{% else %}
0
{% endif %}
unit_of_measurement: "%"
device_class: None
attributes:
daily_queries: "{{ states('sensor.adguard_dns_queries') }}"
daily_blocked: "{{ states('sensor.adguard_blocked_queries') }}"
effectiveness: >
{% set rate = states('sensor.adguard_daily_block_rate') | float(0) %}
{% if rate > 20 %}
High
{% elif rate > 10 %}
Medium
{% elif rate > 5 %}
Low
{% else %}
Very Low
{% endif %}
```
## Node-RED Integration
### Flow Examples
#### AdGuard Control Flow
```json
[
{
"id": "adguard-control",
"type": "api-call-service",
"name": "Toggle AdGuard Protection",
"service_domain": "switch",
"service": "toggle",
"entityId": "switch.adguard_protection",
"data": {},
"wires": [["notification-node"]]
},
{
"id": "notification-node",
"type": "api-call-service",
"name": "Send Notification",
"service_domain": "notify",
"service": "mobile_app_your_phone",
"data": {
"title": "AdGuard",
"message": "Protection toggled via Node-RED"
}
}
]
```
## API Integration
### REST Commands
Add REST commands to your configuration.yaml for direct API access:
```yaml
rest_command:
adguard_enable_protection:
url: "http://192.168.1.100:3000/control/dns_config"
method: POST
headers:
Content-Type: application/json
Authorization: "Basic {{ ('admin:password') | b64encode }}"
payload: '{"protection_enabled": true}'
adguard_get_status:
url: "http://192.168.1.100:3000/control/status"
method: GET
headers:
Authorization: "Basic {{ ('admin:password') | b64encode }}"
```
## Troubleshooting Advanced Features
### Automation Issues
**Automations not triggering:**
1. Check automation conditions and triggers
2. Verify entity IDs are correct
3. Check timezone settings
4. Review automation traces in Developer Tools
**State changes not detected:**
1. Verify update intervals
2. Check network connectivity
3. Review entity history
4. Confirm AdGuard Home is responding
### Template Issues
**Templates showing unavailable:**
1. Check template syntax
2. Verify referenced entities exist
3. Test templates in Developer Tools → Template
4. Review Home Assistant logs for template errors
### Performance Optimization
**High resource usage:**
1. Reduce automation frequency
2. Optimize template sensors
3. Use conditions to prevent unnecessary actions
4. Monitor Home Assistant performance
**Slow response times:**
1. Check AdGuard Home performance
2. Verify network latency
3. Reduce update frequency if needed
4. Monitor integration logs
## Best Practices
### Security
- Use HTTPS when possible
- Store credentials in secrets.yaml
- Limit API access to required functions
- Regular security updates
### Reliability
- Add error handling to automations
- Use conditions to prevent conflicts
- Monitor integration health
- Have fallback procedures
### Performance
- Balance update frequency with resources
- Use efficient templates
- Avoid excessive API calls
- Monitor system resources
## Next Steps
- [Review troubleshooting guide](Troubleshooting.md)
- [Learn about API endpoints](API-Reference.md)
- [Contribute to development](Development.md)

244
wiki/Configuration.md Normal file
View File

@@ -0,0 +1,244 @@
# Configuration Guide
This guide covers all configuration options for AdGuard Control Hub integration.
## Initial Setup
### Basic Configuration
When adding the integration for the first time, you'll need to provide:
| Field | Description | Required | Default |
|-------|-------------|----------|---------|
| **Host** | IP address or hostname of AdGuard Home | ✅ | - |
| **Port** | Port number AdGuard Home is running on | ✅ | 3000 |
| **Username** | Admin username (if authentication enabled) | ❌ | - |
| **Password** | Admin password (if authentication enabled) | ❌ | - |
| **Use HTTPS** | Enable HTTPS connection | ❌ | false |
| **Verify SSL** | Verify SSL certificates | ❌ | true |
### Step-by-Step Configuration
1. **Navigate to Integration Setup**
- Go to **Settings** → **Devices & Services**
- Click **"+ ADD INTEGRATION"**
- Search for **"AdGuard Control Hub"**
2. **Enter Connection Details**
```
Host: 192.168.1.100
Port: 3000
Username: admin (optional)
Password: your-password (optional)
Use HTTPS: ☐ (check if using HTTPS)
Verify SSL: ☑ (recommended)
```
3. **Test Connection**
- Click **"SUBMIT"**
- Integration will test the connection
- If successful, you'll see a success message
4. **Complete Setup**
- Integration will create all entities
- Device will appear in **Devices & Services**
## Advanced Configuration
### HTTPS Setup
If your AdGuard Home uses HTTPS:
1. **Enable HTTPS in AdGuard Home**
- Open AdGuard Home web interface
- Go to **Settings** → **Encryption**
- Configure SSL certificate
2. **Configure Integration**
- Check **"Use HTTPS"** during setup
- Use HTTPS port (usually 443 or custom)
3. **SSL Certificate Verification**
- **Verify SSL: ON** - Recommended for production
- **Verify SSL: OFF** - Only for self-signed certificates
### Authentication Configuration
AdGuard Home supports optional authentication:
#### Without Authentication
- Leave **Username** and **Password** empty
- AdGuard Home must have authentication disabled
#### With Authentication
- Enter your AdGuard Home admin credentials
- User must have admin privileges
- Credentials are stored securely in Home Assistant
### Network Configuration Examples
#### Local Network
```
Host: 192.168.1.100
Port: 3000
Use HTTPS: false
```
#### Remote Server with SSL
```
Host: adguard.example.com
Port: 443
Use HTTPS: true
Verify SSL: true
Username: admin
Password: secure-password
```
#### Docker Installation
```
Host: adguard-home.local
Port: 3000
Use HTTPS: false
```
## Multiple Instances
You can configure multiple AdGuard Home instances:
1. **Add each instance separately**
- Each gets its own configuration entry
- Entities are prefixed with instance name
- All instances appear as separate devices
2. **Naming Convention**
- Integration automatically names based on hostname
- Example: "AdGuard Home (192.168.1.100)"
- Example: "AdGuard Home (adguard.example.com)"
## Entity Configuration
### Entity Naming
Entities are automatically created with descriptive names:
**Switches:**
- `switch.adguard_protection`
- `switch.adguard_dns_filtering`
- `switch.adguard_safe_browsing`
- `switch.adguard_parental_control`
- `switch.adguard_safe_search`
- `switch.adguard_query_log`
**Sensors:**
- `sensor.adguard_dns_queries`
- `sensor.adguard_blocked_queries`
- `sensor.adguard_blocked_percentage`
- `sensor.adguard_active_filter_rules`
- `sensor.adguard_average_processing_time`
**Binary Sensors:**
- `binary_sensor.adguard_home_running`
### Customizing Entities
You can customize entity names and icons:
1. **Entity Settings**
- Go to **Settings** → **Devices & Services**
- Find AdGuard Control Hub device
- Click on any entity
- Click gear icon (⚙️) to edit
2. **Available Customizations**
- Entity ID
- Friendly name
- Icon
- Device class
- Area assignment
## Update Interval
The integration updates every 30 seconds by default. This provides a good balance between responsiveness and resource usage.
**Note:** Query log must be enabled in AdGuard Home for statistics to update. Disabling query log will stop sensor updates.
## Options Configuration
Currently, there are no additional options to configure after initial setup. All configuration is done during the initial integration setup.
## Configuration Troubleshooting
### Connection Issues
**Cannot connect to AdGuard Home:**
1. Verify AdGuard Home is running
2. Check network connectivity: `ping your-adguard-ip`
3. Test API manually: `curl http://your-adguard-ip:port/control/status`
4. Verify firewall allows connection
**SSL/HTTPS Issues:**
1. Verify certificate is valid
2. Check certificate matches hostname
3. Try with SSL verification disabled temporarily
4. Ensure correct port for HTTPS
### Authentication Issues
**Authentication failed:**
1. Verify credentials in AdGuard Home
2. Check user has admin privileges
3. Test login in AdGuard Home web interface
4. Ensure password doesn't contain special characters that need escaping
**Forbidden access:**
1. User account may not have sufficient privileges
2. Check AdGuard Home access control settings
3. Verify IP is not blocked by AdGuard Home
### Entity Issues
**Entities not created:**
1. Check Home Assistant logs for errors
2. Verify AdGuard Home API is responding
3. Restart Home Assistant
4. Check entity registry for conflicts
**Entities showing unavailable:**
1. Check AdGuard Home is running
2. Verify network connectivity
3. Check authentication status
4. Review integration logs
## Configuration Files
### Example YAML (for reference only)
*Configuration is done via UI, not YAML*
```yaml
# This is for reference only - actual configuration is done via UI
adguard_control_hub:
host: 192.168.1.100
port: 3000
username: admin
password: !secret adguard_password
ssl: false
verify_ssl: true
```
### Secrets Management
Store sensitive information in `secrets.yaml`:
```yaml
# secrets.yaml
adguard_password: "your-secure-password"
adguard_host: "192.168.1.100"
```
## Next Steps
After configuration:
- [Explore available features](Features.md)
- [Set up Lovelace cards](Advanced-Usage.md#lovelace-cards)
- [Create automations](Advanced-Usage.md#automations)
- [Monitor performance](Features.md#sensors)

294
wiki/Features.md Normal file
View File

@@ -0,0 +1,294 @@
# Features Overview
AdGuard Control Hub provides comprehensive control and monitoring of your AdGuard Home instance through Home Assistant.
## Switches
All switches provide instant control over AdGuard Home's protection features with real-time status updates.
### AdGuard Protection
- **Entity ID:** `switch.adguard_protection`
- **Function:** Master switch that controls all AdGuard features
- **Icon:** `mdi:shield-check`
**Behavior:**
- **ON:** All AdGuard features are active
- **OFF:** Bypasses all AdGuard features (DNS queries pass through without filtering)
- Acts as a master override for all other protection features
**Use Cases:**
- Temporarily disable all filtering for troubleshooting
- Emergency bypass for important downloads
- Scheduled maintenance windows
### DNS Filtering
- **Entity ID:** `switch.adguard_dns_filtering`
- **Function:** Enables DNS filtering using configured blocklists
- **Icon:** `mdi:filter`
**Behavior:**
- **ON:** DNS queries are filtered against blocklists
- **OFF:** DNS filtering is disabled, but other features remain active
- Only affects blocklist-based filtering
**Use Cases:**
- Disable filtering for specific time periods
- Allow access to falsely blocked domains temporarily
- Maintenance of filter lists
### Safe Browsing
- **Entity ID:** `switch.adguard_safe_browsing`
- **Function:** Blocks known phishing and malware sites
- **Icon:** `mdi:shield-bug`
**Behavior:**
- **ON:** Queries to malicious domains are blocked
- **OFF:** Safe browsing protection is disabled
- Uses AdGuard's malware and phishing database
**Use Cases:**
- Enhanced security for family networks
- Protection for less tech-savvy users
- Corporate security policies
### Parental Control
- **Entity ID:** `switch.adguard_parental_control`
- **Function:** Blocks adult content and inappropriate websites
- **Icon:** `mdi:account-child-circle`
**Behavior:**
- **ON:** Adult content domains are blocked
- **OFF:** Parental controls are disabled
- Blocks based on content category classification
**Use Cases:**
- Protect children from inappropriate content
- School or educational environments
- Time-based content filtering
### Safe Search
- **Entity ID:** `switch.adguard_safe_search`
- **Function:** Enforces safe search on major search engines
- **Icon:** `mdi:shield-search`
**Behavior:**
- **ON:** Forces safe search mode on Google, Bing, Yandex, etc.
- **OFF:** Search engines operate in normal mode
- Redirects search queries to safe search variants
**Use Cases:**
- Additional layer of content protection
- Compliance with content policies
- Educational institution requirements
### Query Log
- **Entity ID:** `switch.adguard_query_log`
- **Function:** Records DNS queries for statistics and analysis
- **Icon:** `mdi:file-document-multiple`
**Behavior:**
- **ON:** All DNS queries are logged and stored
- **OFF:** Query logging is disabled, statistics stop updating
- Required for sensor data and analytics
**Use Cases:**
- Monitor network activity
- Troubleshoot DNS issues
- Privacy mode (disable logging)
## Sensors
Sensors provide real-time statistics and monitoring data from your AdGuard Home instance.
### DNS Queries
- **Entity ID:** `sensor.adguard_dns_queries`
- **Unit:** queries
- **Function:** Total number of DNS queries processed
- **Icon:** `mdi:dns`
**Data Points:**
- Total queries since last statistics reset
- Updates every 30 seconds
- Includes all query types (A, AAAA, CNAME, etc.)
**Usage:**
- Monitor network activity levels
- Track DNS server load
- Historical trending
### Blocked Queries
- **Entity ID:** `sensor.adguard_blocked_queries`
- **Unit:** queries
- **Function:** Number of queries blocked by filtering
- **Icon:** `mdi:shield-check`
**Data Points:**
- Queries blocked by all filtering mechanisms
- Includes blocklist, parental control, and safe browsing blocks
- Updates every 30 seconds
**Usage:**
- Measure filtering effectiveness
- Identify potential threats blocked
- Compare blocking trends
### Blocked Percentage
- **Entity ID:** `sensor.adguard_blocked_percentage`
- **Unit:** %
- **Function:** Percentage of queries that were blocked
- **Icon:** `mdi:percent`
**Calculation:**
- `(Blocked Queries / Total Queries) × 100`
- Automatically calculated by integration
- Provides ratio view of filtering activity
**Usage:**
- Quick assessment of filtering impact
- Performance monitoring
- Historical comparison
### Active Filter Rules
- **Entity ID:** `sensor.adguard_active_filter_rules`
- **Unit:** rules
- **Function:** Number of active filtering rules loaded
- **Icon:** `mdi:filter-check`
**Data Points:**
- Total rules from all enabled filter lists
- Includes custom rules
- Updated when filter lists are refreshed
**Usage:**
- Monitor filter list size and complexity
- Track filter performance impact
- Troubleshoot over-blocking
### Average Processing Time
- **Entity ID:** `sensor.adguard_average_processing_time`
- **Unit:** ms
- **Function:** Average DNS query processing time
- **Icon:** `mdi:clock-fast`
**Measurement:**
- Time from query receipt to response
- Rolling average over recent queries
- Includes upstream server response time
**Usage:**
- Monitor DNS performance
- Identify performance bottlenecks
- Compare different upstream servers
## Binary Sensors
Binary sensors provide simple on/off status information.
### AdGuard Home Running
- **Entity ID:** `binary_sensor.adguard_home_running`
- **Function:** Shows if AdGuard Home is responsive
- **Icon:** `mdi:shield-check-outline`
**States:**
- **ON:** AdGuard Home is responding to API requests
- **OFF:** AdGuard Home is unreachable or not responding
- **UNAVAILABLE:** Integration cannot determine status
**Usage:**
- Monitor AdGuard Home availability
- Trigger alerts for downtime
- Automation conditions
## Device Information
The integration creates a single device representing your AdGuard Home instance:
**Device Attributes:**
- **Name:** "AdGuard Control Hub"
- **Manufacturer:** "AdGuard"
- **Model:** "AdGuard Home"
- **Software Version:** Detected from AdGuard Home API
- **Configuration URL:** Direct link to AdGuard Home web interface
**Device Identifiers:**
- Unique identifier based on host and port
- Allows multiple instances without conflicts
- Persistent across restarts
## Entity Attributes
Each entity provides additional information in its attributes:
### Switch Attributes
```yaml
friendly_name: "AdGuard Protection"
device_class: switch
icon: "mdi:shield-check"
state: "on"
```
### Sensor Attributes
```yaml
friendly_name: "DNS Queries"
device_class: null
unit_of_measurement: "queries"
state_class: "measurement"
icon: "mdi:dns"
state: 1247
```
## Feature Dependencies
Understanding feature relationships:
1. **Query Log Dependency**
- Most sensors require query log to be enabled
- Disabling query log stops statistics updates
- Binary sensor still works without query log
2. **Master Protection Switch**
- When protection is OFF, individual switches show their configured state
- But filtering is bypassed regardless of individual switch states
- Protection switch overrides all other filtering
3. **Network Connectivity**
- All features require network access to AdGuard Home
- Connection loss makes all entities unavailable
- Integration automatically reconnects when connection is restored
## Feature Limitations
**Current Limitations:**
- Client-specific controls not yet implemented
- Custom filter list management not available
- DNS rewrite rules not supported
- DHCP settings not exposed
**Planned Features:**
- Individual client management
- Custom filtering rules via HA
- DNS rewrite configuration
- Advanced statistics and reporting
## Performance Considerations
**Update Frequency:**
- Default: 30-second intervals
- Balances responsiveness vs. resource usage
- Configurable in future versions
**Resource Usage:**
- Minimal CPU impact on AdGuard Home
- Uses standard AdGuard Home API endpoints
- No additional logging or processing required
**Network Traffic:**
- Small API requests every 30 seconds
- Typical response size: < 1KB per request
- Negligible bandwidth impact
## Next Steps
- [Set up advanced automations](Advanced-Usage.md)
- [Troubleshoot issues](Troubleshooting.md)
- [Learn about the API](API-Reference.md)

82
wiki/Home.md Normal file
View File

@@ -0,0 +1,82 @@
# AdGuard Control Hub Wiki
Welcome to the AdGuard Control Hub integration wiki! This comprehensive guide will help you get the most out of your AdGuard Home integration with Home Assistant.
## Quick Navigation
- [Installation Guide](Installation.md) - Step-by-step installation instructions
- [Configuration](Configuration.md) - Detailed configuration options
- [Features Overview](Features.md) - Complete feature documentation
- [API Reference](API-Reference.md) - AdGuard Home API information
- [Troubleshooting](Troubleshooting.md) - Common issues and solutions
- [Advanced Usage](Advanced-Usage.md) - Automation examples and advanced features
- [Development](Development.md) - Contributing and development setup
## What is AdGuard Control Hub?
AdGuard Control Hub is a comprehensive Home Assistant integration that provides complete control over your AdGuard Home DNS server. It allows you to:
- Monitor DNS statistics and performance
- Control filtering and protection features
- Manage clients and their settings
- Create powerful automations based on DNS activity
- View detailed analytics and reports
## Key Features
### 🛡️ Complete Protection Control
- Master protection switch
- DNS filtering management
- Safe browsing controls
- Parental control settings
- Safe search enforcement
- Query logging control
### 📊 Comprehensive Monitoring
- Real-time DNS query statistics
- Blocked query tracking
- Performance metrics
- Filter rule counts
- Client activity monitoring
### 🏠 Home Assistant Integration
- Native Home Assistant entities
- Lovelace dashboard cards
- Automation support
- Service calls
- Event triggering
### 🔧 Easy Configuration
- GUI-based setup flow
- Automatic discovery
- Connection validation
- Error handling
- Secure credential storage
## Getting Started
1. **Prerequisites**: Ensure you have AdGuard Home v0.107.0+ running
2. **Installation**: Follow the [Installation Guide](Installation.md)
3. **Configuration**: Set up your connection using the [Configuration Guide](Configuration.md)
4. **Features**: Explore available features in the [Features Overview](Features.md)
## Support
If you encounter any issues:
1. Check the [Troubleshooting Guide](Troubleshooting.md)
2. Review the [GitHub Issues](https://github.com/your-username/adguard-control-hub/issues)
3. Join the discussion in [GitHub Discussions](https://github.com/your-username/adguard-control-hub/discussions)
## Contributing
We welcome contributions! See the [Development Guide](Development.md) for information on:
- Setting up a development environment
- Running tests
- Submitting pull requests
- Reporting bugs
---
*This integration is not officially affiliated with AdGuard. AdGuard Home is a trademark of AdGuard Software Ltd.*

139
wiki/Installation.md Normal file
View File

@@ -0,0 +1,139 @@
# Installation Guide
This guide covers all installation methods for AdGuard Control Hub integration.
## Prerequisites
Before installing AdGuard Control Hub, ensure you have:
- **Home Assistant** 2023.5.0 or newer
- **AdGuard Home** v0.107.0 or newer
- Network connectivity between Home Assistant and AdGuard Home
- (Optional) Admin credentials for AdGuard Home if authentication is enabled
## Installation Methods
### Method 1: HACS Installation (Recommended)
HACS (Home Assistant Community Store) is the easiest way to install and manage custom integrations.
#### Step 1: Install HACS
If you don't have HACS installed:
1. Follow the [official HACS installation guide](https://hacs.xyz/docs/setup/prerequisites)
2. Restart Home Assistant after installation
#### Step 2: Add AdGuard Control Hub
1. Open Home Assistant web interface
2. Navigate to **HACS** → **Integrations**
3. Click the **"+ EXPLORE & DOWNLOAD REPOSITORIES"** button
4. Search for **"AdGuard Control Hub"**
5. Click on the integration and then **"DOWNLOAD"**
6. Select the latest version and click **"DOWNLOAD"**
7. Restart Home Assistant
#### Step 3: Add Integration
1. Navigate to **Settings** → **Devices & Services**
2. Click **"+ ADD INTEGRATION"**
3. Search for **"AdGuard Control Hub"**
4. Follow the configuration steps
### Method 2: Manual Installation
For users who prefer manual installation or cannot use HACS.
#### Step 1: Download Integration
1. Go to the [latest release page](https://github.com/your-username/adguard-control-hub/releases/latest)
2. Download the `adguard-control-hub.zip` file
3. Extract the ZIP file
#### Step 2: Copy Files
1. Copy the extracted `custom_components/adguard_control_hub` folder
2. Place it in your Home Assistant's `config/custom_components/` directory
3. The final structure should look like:
```
config/
└── custom_components/
└── adguard_control_hub/
├── __init__.py
├── manifest.json
├── config_flow.py
└── ... (other files)
```
#### Step 3: Restart and Configure
1. Restart Home Assistant
2. Navigate to **Settings** → **Devices & Services**
3. Click **"+ ADD INTEGRATION"**
4. Search for **"AdGuard Control Hub"**
5. Follow the configuration steps
## Verification
After installation, verify everything is working:
1. Check **Settings** → **Devices & Services** for the AdGuard Control Hub integration
2. Verify entities are created under the AdGuard device
3. Test switching protection on/off
4. Check the Home Assistant logs for any errors
## Next Steps
- [Configure the integration](Configuration.md)
- [Explore available features](Features.md)
- [Set up automations](Advanced-Usage.md)
## Troubleshooting Installation
### HACS Issues
**Integration not found in HACS:**
- Ensure you're searching in the "Integrations" section
- Check if HACS is up to date
- Clear HACS cache and refresh
**Download fails:**
- Check your internet connection
- Verify HACS has proper GitHub access
- Try downloading manually and installing via Method 2
### Manual Installation Issues
**Integration not showing up:**
- Verify folder structure is correct
- Check file permissions
- Restart Home Assistant completely (not just config reload)
- Check Home Assistant logs for errors
**Permission errors:**
- Ensure Home Assistant has read/write access to custom_components
- Check file ownership matches Home Assistant user
### General Issues
**Integration fails to load:**
- Check Home Assistant logs: **Settings** → **System** → **Logs**
- Verify Python requirements are met
- Ensure Home Assistant version compatibility
**Cannot add integration:**
- Clear browser cache and cookies
- Try incognito/private browsing mode
- Check for JavaScript errors in browser console
## Getting Help
If you're still having issues:
1. Check the [Troubleshooting Guide](Troubleshooting.md)
2. Review [GitHub Issues](https://github.com/your-username/adguard-control-hub/issues)
3. Create a new issue with:
- Installation method used
- Home Assistant version
- Error messages from logs
- Steps you've already tried