# 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)