home-assistant-blueprints/PACKAGE_SETUP_GUIDE.md

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:

homeassistant:
  packages: !include_dir_named packages/

1.2 Create the packages directory

SSH into your Home Assistant instance or use File Editor add-on:

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

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

cd /config
git init

5.2 Create .gitignore

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

git add packages/ automations.yaml configuration.yaml
git commit -m "Initial adaptive lighting mode system setup"

5.4 Add remote (optional)

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 for detailed room setup examples.