527
wiki/Advanced-Usage.md
Normal file
527
wiki/Advanced-Usage.md
Normal 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)
|
||||
Reference in New Issue
Block a user