adguard-control-hub/wiki/Installation.md

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
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
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
• Explore available features
• Set up automations

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
2. Review GitHub Issues
3. Create a new issue with:
   • Installation method used
   • Home Assistant version
   • Error messages from logs
   • Steps you've already tried