John Ogle
a5a6b9d4b6
- Update README with complete setup guide and all blueprint URLs - Add PACKAGE_SETUP_GUIDE with step-by-step setup instructions - Add ROOM_CONFIGURATION_GUIDE with bedroom, living room, and bathroom examples - Add HARDWARE_TESTING_CHECKLIST for validating with real Inovelli switches - Add CHANGELOG documenting v1.0.0 release - Add validation script for automated YAML testing - Add test configuration example for testing without hardware
221 lines
5.3 KiB
Markdown
221 lines
5.3 KiB
Markdown
# Package Setup Guide
|
|
|
|
## Overview
|
|
|
|
This guide explains how to set up Home Assistant packages for the Adaptive
|
|
Lighting Mode System and configure version control.
|
|
|
|
## What Are Packages?
|
|
|
|
Packages allow you to organize Home Assistant configuration into multiple YAML
|
|
files instead of one giant `configuration.yaml`. Each package file can contain
|
|
automations, helpers, scripts, and other entities related to a specific feature
|
|
or room.
|
|
|
|
**Benefits**:
|
|
- Organize configuration by room or feature
|
|
- Version control specific areas independently
|
|
- Easier to share and reuse configurations
|
|
- Keep `configuration.yaml` clean and minimal
|
|
|
|
## Prerequisites
|
|
|
|
- Home Assistant installed and running
|
|
- SSH or file editor access to your HA configuration directory
|
|
- Git installed (optional, for version control)
|
|
- Adaptive Lighting integration installed via HACS
|
|
|
|
## Step 1: Enable Packages in Home Assistant
|
|
|
|
**1.1 Edit your `configuration.yaml`**
|
|
|
|
Add this line to the top of your `configuration.yaml`:
|
|
|
|
```yaml
|
|
homeassistant:
|
|
packages: !include_dir_named packages/
|
|
```
|
|
|
|
**1.2 Create the packages directory**
|
|
|
|
SSH into your Home Assistant instance or use File Editor add-on:
|
|
|
|
```bash
|
|
cd /config
|
|
mkdir packages
|
|
```
|
|
|
|
**1.3 Restart Home Assistant**
|
|
|
|
Settings → System → Restart Home Assistant
|
|
|
|
## Step 2: Install Global Definitions
|
|
|
|
**2.1 Copy the global package**
|
|
|
|
Download or copy `packages/adaptive_lighting_global.yaml` from this repository
|
|
to your `/config/packages/` directory.
|
|
|
|
**2.2 Reload YAML configuration**
|
|
|
|
Developer Tools → YAML → Reload all YAML configuration
|
|
|
|
**2.3 Verify helpers exist**
|
|
|
|
Settings → Devices & Services → Helpers
|
|
|
|
You should see:
|
|
- `input_text.adaptive_lighting_mode_colors`
|
|
- `input_text.adaptive_lighting_settings_adaptive`
|
|
- `input_text.adaptive_lighting_settings_reading`
|
|
- `input_text.adaptive_lighting_settings_relaxing`
|
|
- `input_text.adaptive_lighting_settings_sleep`
|
|
- And several more mode settings helpers
|
|
|
|
## Step 3: Import Blueprints
|
|
|
|
**3.1 Import via UI**
|
|
|
|
Settings → Automations & Scenes → Blueprints → Import Blueprint
|
|
|
|
Import these URLs:
|
|
```
|
|
https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_mode_cycling.yaml
|
|
https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/inovelli_button_actions.yaml
|
|
https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/presence_mode_reset.yaml
|
|
```
|
|
|
|
**3.2 Verify blueprints imported**
|
|
|
|
Settings → Automations & Scenes → Blueprints
|
|
|
|
You should see all three blueprints listed.
|
|
|
|
## Step 4: Configure Your First Room
|
|
|
|
**4.1 Choose a template**
|
|
|
|
Select the appropriate template for your room type:
|
|
- Bedroom: `packages/adaptive_lighting_bedroom_template.yaml`
|
|
- Living room: `packages/adaptive_lighting_living_room_template.yaml`
|
|
- Simple (bathroom, closet): `packages/adaptive_lighting_simple_template.yaml`
|
|
|
|
**4.2 Copy and customize**
|
|
|
|
```bash
|
|
cd /config/packages
|
|
cp adaptive_lighting_bedroom_template.yaml adaptive_lighting_master_bedroom.yaml
|
|
```
|
|
|
|
Edit the file and update:
|
|
- Replace "bedroom" with "master_bedroom" throughout
|
|
- Update entity IDs (search for # UPDATE THIS comments)
|
|
- Adjust available modes if desired
|
|
- Customize mode settings
|
|
|
|
**4.3 Reload configuration**
|
|
|
|
Developer Tools → YAML → Reload all YAML configuration
|
|
|
|
**4.4 Create blueprint automations**
|
|
|
|
Settings → Automations & Scenes → Create Automation → Use Blueprint
|
|
|
|
Create automations for:
|
|
1. Inovelli Mode Cycling (config button)
|
|
2. Inovelli Button Actions (multi-tap)
|
|
3. Presence Mode Reset (if you have occupancy sensors)
|
|
|
|
## Step 5: Version Control Setup (Optional)
|
|
|
|
**5.1 Initialize git repository**
|
|
|
|
```bash
|
|
cd /config
|
|
git init
|
|
```
|
|
|
|
**5.2 Create .gitignore**
|
|
|
|
```bash
|
|
cat > .gitignore << 'EOF'
|
|
# Secrets and sensitive data
|
|
secrets.yaml
|
|
*.db
|
|
*.db-shm
|
|
*.db-wal
|
|
*.log
|
|
|
|
# Generated files
|
|
*.pyc
|
|
__pycache__/
|
|
.storage/
|
|
.cloud/
|
|
.google.token
|
|
|
|
# Add-on data
|
|
.ssh/
|
|
.vscode/
|
|
|
|
# Keep these version controlled:
|
|
# - packages/
|
|
# - automations.yaml
|
|
# - configuration.yaml
|
|
# - blueprints/
|
|
EOF
|
|
```
|
|
|
|
**5.3 Commit initial setup**
|
|
|
|
```bash
|
|
git add packages/ automations.yaml configuration.yaml
|
|
git commit -m "Initial adaptive lighting mode system setup"
|
|
```
|
|
|
|
**5.4 Add remote (optional)**
|
|
|
|
```bash
|
|
git remote add origin your-git-repo-url
|
|
git push -u origin main
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Packages not loading
|
|
|
|
**Symptom**: Helpers don't appear after reloading
|
|
|
|
**Solutions**:
|
|
- Check `configuration.yaml` has packages line
|
|
- Verify packages directory exists at `/config/packages/`
|
|
- Check YAML syntax: `yamllint /config/packages/*.yaml`
|
|
- Look for errors in Settings → System → Logs
|
|
|
|
### Entity IDs don't match
|
|
|
|
**Symptom**: Automations fail because entities not found
|
|
|
|
**Solutions**:
|
|
- Go to Settings → Devices & Services → MQTT
|
|
- Find your Inovelli switch device
|
|
- Note the exact entity IDs (event.xxx_action,
|
|
number.xxx_led_color_when_on)
|
|
- Update package file with correct entity IDs
|
|
- Reload YAML
|
|
|
|
### Blueprints not working
|
|
|
|
**Symptom**: Automation from blueprint doesn't trigger
|
|
|
|
**Solutions**:
|
|
- Check automation trace: Settings → Automations → [your automation] →
|
|
Traces
|
|
- Verify trigger entity is correct
|
|
- Ensure Inovelli buttonDelay is set to >= 500ms
|
|
- Test button press in Developer Tools → States (watch event.xxx_action)
|
|
|
|
## Next Steps
|
|
|
|
See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for detailed
|
|
room setup examples.
|