johno/home-assistant-blueprints
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add custom mode tutorial and update docs for pure blueprint architecture

Browse Source 
Add ADDING_MODES.md tutorial covering:
- UI-created modes (recommended) and package-defined modes
- Complete schema reference with nested al_config
- Behavior types (adaptive_lighting, scene, script)
- Manual control support and advanced examples

Update all documentation to reflect:
- Zero YAML editing for room setup (UI-driven workflow)
- Convention-based mode lookup pattern
- Pure blueprint architecture (3 core + 3 optional blueprints)
- Extensibility via helpers instead of template copying
This commit is contained in:
John Ogle
2025-12-21 17:44:47 -08:00
parent a5ed6c6340
commit 14fadbe44e
5 changed files with 1553 additions and 339 deletions
Download Patch File Download Diff File Expand all files Collapse all files

253
PACKAGE_SETUP_GUIDE.md
View File

@@ -2,41 +2,84 @@
## Overview
This guide explains how to set up Home Assistant packages for the Adaptive
Lighting Mode System and configure version control.
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
or room.
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 room or feature
- Organize configuration by feature
- Version control specific areas independently
- Easier to share and reuse configurations
- 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
- Git installed (optional, for version control)
## Step 1: Enable Packages in Home Assistant
## Installation Steps
**1.1 Edit your `configuration.yaml`**
### Step 1: Import Blueprints
Add this line to the top of your `configuration.yaml`:
**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/
```
**1.2 Create the packages directory**
**2.2 Create the packages directory**
SSH into your Home Assistant instance or use File Editor add-on:
@@ -45,97 +88,115 @@ cd /config
mkdir packages
```
**1.3 Restart Home Assistant**
**2.3 Restart Home Assistant**
Settings → System → Restart Home Assistant
## Step 2: Install Global Definitions
### Step 3: Install Global Package
**2.1 Copy the global package**
**3.1 Copy the global package**
Download or copy `packages/adaptive_lighting_global.yaml` from this repository
to your `/config/packages/` directory.
Download or copy `packages/adaptive_lighting_global.yaml` from this repository to your `/config/packages/` directory.
**2.2 Reload YAML configuration**
**3.2 Reload YAML configuration**
Developer Tools → YAML → Reload all YAML configuration
**2.3 Verify helpers exist**
**3.3 Verify mode entities exist**
Settings → Devices & Services → Helpers
Developer Tools → States
You should see:
- `input_text.adaptive_lighting_mode_colors`
Search for `adaptive_lighting_settings` - you should see 8 entities:
- `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
- `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 3: Import Blueprints
### Step 4: Configure Your First Room
**3.1 Import via UI**
**This is done entirely via the UI** - no YAML editing required!
Settings → Automations & Scenes → Blueprints → Import Blueprint
See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for complete UI-driven room setup instructions.
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
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
}
}
```
**3.2 Verify blueprints imported**
**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
Settings → Automations & Scenes → Blueprints
**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
You should see all three blueprints listed.
### Editing Mode Settings
## Step 4: Configure Your First Room
To customize a mode, edit `packages/adaptive_lighting_global.yaml` and modify the `initial` value:
**4.1 Choose a template**
**Example: Make "Relaxing" mode dimmer**
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
```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}}'
```
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
After editing, reload YAML configuration (Developer Tools → YAML → Reload all YAML configuration).
**4.3 Reload configuration**
### Adding Custom Modes
Developer Tools → YAML → Reload all YAML configuration
See [ADDING_MODES.md](ADDING_MODES.md) for complete tutorial on adding custom modes.
**4.4 Create blueprint automations**
**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
Settings → Automations & Scenes → Create Automation → Use Blueprint
Both methods work identically with the convention-based blueprint system.
Create automations for:
1. Inovelli Mode Cycling (config button)
2. Inovelli Button Actions (multi-tap)
3. Presence Mode Reset (if you have occupancy sensors)
## Version Control Setup (Optional)
## Step 5: Version Control Setup (Optional)
**5.1 Initialize git repository**
### Initialize git repository
```bash
cd /config
git init
```
**5.2 Create .gitignore**
### Create .gitignore
```bash
cat > .gitignore << 'EOF'
@@ -159,20 +220,19 @@ __pycache__/
# Keep these version controlled:
# - packages/
# - automations.yaml
# - automations.yaml (optional - UI automations are in .storage)
# - configuration.yaml
# - blueprints/
EOF
```
**5.3 Commit initial setup**
### Commit initial setup
```bash
git add packages/ automations.yaml configuration.yaml
git add packages/ configuration.yaml
git commit -m "Initial adaptive lighting mode system setup"
```
**5.4 Add remote (optional)**
### Add remote (optional)
```bash
git remote add origin your-git-repo-url
@@ -183,38 +243,51 @@ git push -u origin main
### Packages not loading
**Symptom**: Helpers don't appear after reloading
**Symptom**: Mode entities don't appear after reloading
**Solutions**:
- Check `configuration.yaml` has packages line
- Check `configuration.yaml` has packages line: `packages: !include_dir_named packages/`
- Verify packages directory exists at `/config/packages/`
- Check YAML syntax: `yamllint /config/packages/*.yaml`
- Check YAML syntax with a validator
- Look for errors in Settings → System → Logs
- Try restarting Home Assistant instead of just reloading YAML
### Entity IDs don't match
### Invalid JSON in mode settings
**Symptom**: Automations fail because entities not found
**Symptom**: Mode doesn't work or causes errors
**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
- 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 working
### Blueprints not appearing
**Symptom**: Automation from blueprint doesn't trigger
**Symptom**: Blueprints don't show up after import
**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)
- 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
See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for detailed
room setup examples.
**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