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