# 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](https://hacs.xyz/docs/setup/prerequisites)
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](https://github.com/your-username/adguard-control-hub/releases/latest)
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](Configuration.md)
- [Explore available features](Features.md)
- [Set up automations](Advanced-Usage.md)

## 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](Troubleshooting.md)
2. Review [GitHub Issues](https://github.com/your-username/adguard-control-hub/issues)
3. Create a new issue with:
   - Installation method used
   - Home Assistant version
   - Error messages from logs
   - Steps you've already tried