adguard-control-hub/wiki/Advanced-Usage.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[
    {
        "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:

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
• Learn about API endpoints
• Contribute to development