home-assistant-blueprints/PACKAGE_SETUP_GUIDE.md

Package Setup Guide

Overview

This guide covers installing the global mode definitions package only. Room configuration is done entirely via Home Assistant UI - see ROOM_CONFIGURATION_GUIDE.md for the UI-driven room setup workflow.

Architecture

The Adaptive Lighting Mode System uses a pure blueprint architecture:

• Global package: Provides shared mode definitions (8 essential modes) as input_text helpers
• Blueprints: Provide automation logic for mode application and weekend mode schedules
• UI-created helpers: Users create room-specific helpers (dropdowns, toggles) via Settings → Helpers
• UI-created automations: Users create automations from blueprints via Settings → Automations

Key principle: Zero YAML editing required for room setup. The global package is the only YAML file you need to install.

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.

Benefits:

• Organize configuration by feature
• Version control specific areas independently
• 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
• Adaptive Lighting integration installed via HACS
• Git installed (optional, for version control)

Installation Steps

Step 1: Import Blueprints

1.1 Navigate to blueprints

Settings → Automations & Scenes → Blueprints → Import Blueprint

1.2 Import the three mode system blueprints

Import these URLs one at a time:

https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/apply_lighting_mode.yaml
https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/weekend_mode_schedule.yaml
https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/weekend_mode_apply_settings.yaml

Optional blueprints (for Inovelli switches and presence-based automation):

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

1.3 Verify blueprints imported

Settings → Automations & Scenes → Blueprints

You should see:

• Apply Lighting Mode Settings
• Weekend Mode Schedule
• Weekend Mode Apply Settings
• (Optional) Inovelli Mode Cycling, Inovelli Button Actions, Presence Mode Reset

Step 2: Enable Packages in Home Assistant

2.1 Edit your configuration.yaml

Add this line to enable packages:

homeassistant:
  packages: !include_dir_named packages/

2.2 Create the packages directory

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

cd /config
mkdir packages

2.3 Restart Home Assistant

Settings → System → Restart Home Assistant

Step 3: Install Global Package

3.1 Copy the global package

Download or copy packages/adaptive_lighting_global.yaml from this repository to your /config/packages/ directory.

3.2 Reload YAML configuration

Developer Tools → YAML → Reload all YAML configuration

3.3 Verify mode entities exist

Developer Tools → States

Search for adaptive_lighting_settings - you should see 8 entities:

• input_text.adaptive_lighting_settings_adaptive
• input_text.adaptive_lighting_settings_relaxing
• input_text.adaptive_lighting_settings_sleep
• input_text.adaptive_lighting_settings_theater
• input_text.adaptive_lighting_settings_party
• input_text.adaptive_lighting_settings_cooking
• input_text.adaptive_lighting_settings_dining
• input_text.adaptive_lighting_settings_cleanup

Step 4: Configure Your First Room

This is done entirely via the UI - no YAML editing required!

See ROOM_CONFIGURATION_GUIDE.md for complete UI-driven room setup instructions.

Quick summary:

1. Create mode selector dropdown via Settings → Helpers
2. Create automation from "Apply Lighting Mode Settings" blueprint
3. Test mode switching via UI
4. Optionally add weekend mode automations

Mode Customization

Understanding the Mode Schema

Each mode in the global package uses a nested JSON schema:

{
  "behavior": "adaptive_lighting",
  "manual_control": false,
  "led_color": 170,
  "al_config": {
    "min_brightness": 20,
    "max_brightness": 80,
    "min_color_temp": 2000,
    "max_color_temp": 4000,
    "transition": 5
  }
}

Top-level fields:

• behavior: "adaptive_lighting", "scene", or "script" - determines how the mode behaves
• manual_control: true or false - if true, pauses Adaptive Lighting for this mode
• led_color: 0-255 hue value for LED feedback on Inovelli switches
• al_config: Nested object with Adaptive Lighting settings

AL config fields (only used for "adaptive_lighting" behavior):

• use_defaults: "configuration" or "current"
• min_brightness, max_brightness: 1-100
• min_color_temp, max_color_temp: Kelvin values (2000-6500)
• sleep_rgb_color: RGB array like [255, 50, 0]
• transition: Seconds

Editing Mode Settings

To customize a mode, edit packages/adaptive_lighting_global.yaml and modify the initial value:

Example: Make "Relaxing" mode dimmer

adaptive_lighting_settings_relaxing:
  name: "AL Settings: Relaxing"
  max: 255
  initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":21,"al_config":{"min_brightness":10,"max_brightness":30,"min_color_temp":2000,"max_color_temp":2200,"transition":5}}'

After editing, reload YAML configuration (Developer Tools → YAML → Reload all YAML configuration).

Adding Custom Modes

See ADDING_MODES.md for complete tutorial on adding custom modes.

Two methods:

1. UI-created modes (recommended): Create input_text helper via Settings → Helpers - no restart required
2. Package-defined modes: Add to adaptive_lighting_global.yaml - version controlled

Both methods work identically with the convention-based blueprint system.

Version Control Setup (Optional)

Initialize git repository

cd /config
git init

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 (optional - UI automations are in .storage)
# - configuration.yaml
EOF

Commit initial setup

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

Add remote (optional)

git remote add origin your-git-repo-url
git push -u origin main

Troubleshooting

Packages not loading

Symptom: Mode entities don't appear after reloading

Solutions:

• Check configuration.yaml has packages line: packages: !include_dir_named packages/
• Verify packages directory exists at /config/packages/
• Check YAML syntax with a validator
• Look for errors in Settings → System → Logs
• Try restarting Home Assistant instead of just reloading YAML

Invalid JSON in mode settings

Symptom: Mode doesn't work or causes errors

Solutions:

• Verify JSON is valid using jsonlint.com
• Check for trailing commas (not allowed in JSON)
• Ensure all strings use double quotes, not single quotes
• Verify al_config is a nested object, not at top level

Blueprints not appearing

Symptom: Blueprints don't show up after import

Solutions:

• Check for import errors in Settings → System → Logs
• Verify blueprint URLs are correct
• Try importing again
• Check YAML syntax of blueprint files if self-hosting

Mode entities exist but automations don't work

Symptom: Can see entities in States but mode switching does nothing

Solutions:

• Verify you created automation from "Apply Lighting Mode Settings" blueprint
• Check automation is enabled
• View automation traces: Settings → Automations → [your automation] → Traces
• Verify AL switch entity ID is correct in automation configuration
• Check mode selector entity ID matches in automation configuration

Next Steps

This package only provides mode definitions. To configure a room, see ROOM_CONFIGURATION_GUIDE.md for the UI-driven workflow.

Additional resources:

• ADDING_MODES.md - Tutorial for creating custom modes
• README.md - Main documentation and architecture overview
• Adaptive Lighting Integration Docs - Reference for AL settings