Add comprehensive documentation and testing tools
- 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
This commit is contained in:
220
PACKAGE_SETUP_GUIDE.md
Normal file
220
PACKAGE_SETUP_GUIDE.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user