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](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:

```yaml
homeassistant:
  packages: !include_dir_named packages/
```

**2.2 Create the packages directory**

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

```bash
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](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**:

```json
{
  "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**

```yaml
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](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

```bash
cd /config
git init
```

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

### Commit initial setup

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

### Add remote (optional)

```bash
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](ROOM_CONFIGURATION_GUIDE.md) for the UI-driven workflow.

Additional resources:
- [ADDING_MODES.md](ADDING_MODES.md) - Tutorial for creating custom modes
- [README.md](README.md) - Main documentation and architecture overview
- [Adaptive Lighting Integration Docs](https://github.com/basnijholt/adaptive-lighting) - Reference for AL settings