140 lines
4.1 KiB
Markdown
140 lines
4.1 KiB
Markdown
# 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
|