Add custom mode tutorial and update docs for pure blueprint architecture

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
2025-12-21 17:44:47 -08:00
parent a5ed6c6340
commit 14fadbe44e
5 changed files with 1553 additions and 339 deletions
--- a/ADDING_MODES.md
+++ b/ADDING_MODES.md
@@ -0,0 +1,453 @@
+# Adding Custom Lighting Modes
+
+This guide teaches you how to add custom lighting modes to your Adaptive Lighting setup. The mode system is **convention-based** - you can add new modes by creating helpers via the UI or editing the global package, with no blueprint code changes required.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Quick Start: Adding "Reading" Mode](#quick-start-adding-reading-mode)
+- [Method 1: UI-Created Modes (Recommended)](#method-1-ui-created-modes-recommended)
+- [Method 2: Package-Defined Modes](#method-2-package-defined-modes)
+- [Schema Reference](#schema-reference)
+- [Behavior Types](#behavior-types)
+- [Manual Control](#manual-control)
+- [Advanced Examples](#advanced-examples)
+- [Troubleshooting](#troubleshooting)
+- [Extensibility](#extensibility)
+
+## Overview
+
+The Adaptive Lighting Mode System uses **convention-based entity lookup** to find mode settings. When you switch to a mode (e.g., "Reading"), the blueprint automatically looks for an entity named:
+
+```
+input_text.adaptive_lighting_settings_reading
+```
+
+This means adding a new mode requires:
+1. Creating a helper with the correct naming convention
+2. Adding the mode name to your room's mode selector dropdown
+3. That's it! No blueprint code changes needed.
+
+### Why "Reading" Mode Was Excluded
+
+The default installation includes 8 essential modes: Adaptive, Relaxing, Sleep, Theater, Party, Cooking, Dining, and Cleanup. "Reading" mode was intentionally excluded as a pedagogical example - this tutorial uses it to teach you how to create custom modes yourself.
+
+## Quick Start: Adding "Reading" Mode
+
+Let's add a "Reading" mode with bright, cool white light ideal for reading.
+
+### Step 1: Create the Settings Entity
+
+1. Go to **Settings → Devices & Services → Helpers**
+2. Click **+ Create Helper → Text**
+3. Configure the helper:
+   - **Name**: `Mode: Reading`
+   - **Entity ID**: `input_text.adaptive_lighting_settings_reading`
+   - **Max length**: `255`
+   - **Initial value**:
+   ```json
+   {"behavior":"adaptive_lighting","manual_control":false,"led_color":42,"al_config":{"min_brightness":80,"max_brightness":100,"min_color_temp":4500,"max_color_temp":5500,"transition":2}}
+   ```
+4. Click **Create**
+
+### Step 2: Add to Mode Selector
+
+1. Go to **Settings → Devices & Services → Helpers**
+2. Find your room's lighting mode dropdown (e.g., `input_select.bedroom_lighting_mode`)
+3. Click **Edit**
+4. Add option: `Reading`
+5. Click **Update**
+
+### Step 3: Test
+
+1. Go to your room's mode selector in the UI
+2. Select **Reading**
+3. Verify:
+   - Lights change to bright, cool white (80-100% brightness, 4500-5500K color temp)
+   - LED on Inovelli switch turns yellow (hue 42)
+   - No blueprint modifications were needed!
+
+## Method 1: UI-Created Modes (Recommended)
+
+Creating modes via the UI is recommended because:
+- No restart required (immediate availability)
+- Easy to test and iterate
+- No risk of YAML syntax errors
+- Perfect for experimenting with custom modes
+
+### Naming Convention
+
+The entity ID must follow this pattern:
+```
+input_text.adaptive_lighting_settings_<mode_name_lowercase_underscores>
+```
+
+Examples:
+- Mode name: "Reading" → Entity ID: `input_text.adaptive_lighting_settings_reading`
+- Mode name: "Movie Night" → Entity ID: `input_text.adaptive_lighting_settings_movie_night`
+- Mode name: "Bowling" → Entity ID: `input_text.adaptive_lighting_settings_bowling`
+
+### UI Creation Steps
+
+1. **Settings → Devices & Services → Helpers**
+2. **+ Create Helper → Text**
+3. Configure:
+   - **Name**: `Mode: <Your Mode Name>` (e.g., "Mode: Reading")
+   - **Entity ID**: Follow naming convention above
+   - **Max length**: `255`
+   - **Initial value**: JSON with your mode settings (see Schema Reference below)
+
+### Example: "Focus" Mode
+
+Create a mode for focused work with bright, neutral light:
+
+```json
+{"behavior":"adaptive_lighting","manual_control":false,"led_color":85,"al_config":{"min_brightness":90,"max_brightness":100,"min_color_temp":4000,"max_color_temp":5000,"transition":1}}
+```
+
+## Method 2: Package-Defined Modes
+
+For version-controlled, permanent modes, add them to the global package.
+
+### Editing the Global Package
+
+1. Open `packages/adaptive_lighting_global.yaml`
+2. Add a new `input_text` entity under the existing modes:
+
+```yaml
+input_text:
+  # ... existing modes ...
+
+  # Your custom mode
+  adaptive_lighting_settings_reading:
+    name: "AL Settings: Reading"
+    max: 255
+    initial: '{"behavior":"adaptive_lighting","manual_control":false,"led_color":42,"al_config":{"min_brightness":80,"max_brightness":100,"min_color_temp":4500,"max_color_temp":5500,"transition":2}}'
+```
+
+3. Save the file
+4. **Developer Tools → YAML → Reload all YAML configuration**
+5. Verify the entity appears in **Developer Tools → States**
+
+### When to Use Package-Defined Modes
+
+Use this method when:
+- You want modes version-controlled with Git
+- The mode is permanent (not experimental)
+- You're deploying to multiple Home Assistant instances
+- You want modes available immediately after fresh install
+
+## Schema Reference
+
+Every mode must have a JSON value with this nested structure:
+
+```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
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `behavior` | string | Yes | N/A | Mode behavior type: "adaptive_lighting", "scene", or "script" |
+| `manual_control` | boolean | No | `false` | If `true`, pauses Adaptive Lighting manual control for this mode |
+| `led_color` | number | No | `170` | LED hue value (0-255) for Inovelli switches |
+| `al_config` | object | Yes* | `{}` | Adaptive Lighting settings (*required for "adaptive_lighting" behavior) |
+
+### AL Config Fields (adaptive_lighting behavior)
+
+These settings are passed directly to `adaptive_lighting.change_switch_settings`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `use_defaults` | string | "configuration" or "current" - whether to use AL defaults |
+| `min_brightness` | number | Minimum brightness percentage (1-100) |
+| `max_brightness` | number | Maximum brightness percentage (1-100) |
+| `min_color_temp` | number | Minimum color temperature in Kelvin (2000-6500) |
+| `max_color_temp` | number | Maximum color temperature in Kelvin (2000-6500) |
+| `sleep_rgb_color` | array | RGB array for sleep mode, e.g., `[255, 50, 0]` |
+| `transition` | number | Transition time in seconds |
+
+See [Adaptive Lighting documentation](https://github.com/basnijholt/adaptive-lighting) for all available AL settings.
+
+### LED Color Values (ROYGBIV Scheme)
+
+LED colors use hue values (0-255) for Zigbee2MQTT `ledColorWhenOn` parameter:
+
+| Color | Hue | Used By Default Modes |
+|-------|-----|----------------------|
+| Red | 0 | Sleep |
+| Orange | 21 | Relaxing, Dining |
+| Yellow | 42 | Cooking |
+| Green | 85 | (none - good for Focus mode) |
+| Cyan | 170 | Adaptive, Cleanup |
+| Purple | 127 | Theater |
+| Magenta | 234 | Party |
+| Pink | 212 | (none - good for Manual Override) |
+
+## Behavior Types
+
+The mode system supports three behavior types:
+
+### 1. Adaptive Lighting (Standard)
+
+Applies Adaptive Lighting settings to lights:
+
+```json
+{
+  "behavior": "adaptive_lighting",
+  "manual_control": false,
+  "led_color": 42,
+  "al_config": {
+    "min_brightness": 80,
+    "max_brightness": 100,
+    "min_color_temp": 4500,
+    "max_color_temp": 5500,
+    "transition": 2
+  }
+}
+```
+
+Use for: Most lighting modes where you want automated color temperature and brightness.
+
+### 2. Scene-Based Mode
+
+Activates a Home Assistant scene:
+
+```json
+{
+  "behavior": "scene",
+  "manual_control": false,
+  "scene_entity": "scene.movie_night",
+  "led_color": 127,
+  "al_config": {}
+}
+```
+
+Use for: Complex lighting setups with multiple lights, specific colors, or other device states.
+
+### 3. Script-Based Mode
+
+Runs a Home Assistant script:
+
+```json
+{
+  "behavior": "script",
+  "manual_control": false,
+  "script_entity": "script.party_lights",
+  "led_color": 234,
+  "al_config": {}
+}
+```
+
+Use for: Dynamic lighting effects, light shows, or complex automation sequences.
+
+## Manual Control
+
+The `manual_control` field controls whether Adaptive Lighting is paused for the mode.
+
+### Pausing Adaptive Lighting
+
+Set `manual_control: true` to pause AL and prevent automatic adjustments:
+
+```json
+{
+  "behavior": "adaptive_lighting",
+  "manual_control": true,
+  "led_color": 212,
+  "al_config": {}
+}
+```
+
+This is useful for:
+- **Manual Override mode**: Let users manually control lights without AL interference
+- **Scene-based modes**: Prevent AL from overriding scene settings
+- **Script-based modes**: Prevent AL from interfering with light effects
+
+### How Manual Control Works
+
+The blueprint **always** calls `adaptive_lighting.set_manual_control` with the mode's `manual_control` value:
+- `manual_control: false` (default): AL remains active and adjusts lights automatically
+- `manual_control: true`: AL is paused and won't adjust lights until mode changes
+
+## Advanced Examples
+
+### Example 1: "Movie Night" Scene Mode
+
+Combines multiple devices (lights, media player, etc.) via a scene:
+
+**Step 1**: Create the scene in Home Assistant (Settings → Scenes)
+**Step 2**: Create mode helper with scene behavior:
+
+```json
+{"behavior":"scene","manual_control":false,"scene_entity":"scene.movie_night","led_color":127,"al_config":{}}
+```
+
+### Example 2: "Disco" Script Mode
+
+Runs a script that cycles through colors:
+
+```json
+{"behavior":"script","manual_control":false,"script_entity":"script.disco_lights","led_color":234,"al_config":{}}
+```
+
+### Example 3: "Manual Override" Mode
+
+Pauses AL completely for manual light control:
+
+```json
+{"behavior":"adaptive_lighting","manual_control":true,"led_color":212,"al_config":{}}
+```
+
+### Example 4: "Sunrise Alarm" Mode
+
+Gradual brightness increase with warm colors:
+
+```json
+{"behavior":"adaptive_lighting","manual_control":false,"led_color":21,"al_config":{"min_brightness":1,"max_brightness":100,"min_color_temp":2000,"max_color_temp":2500,"transition":600}}
+```
+
+Note: 600-second transition = 10-minute gradual wake-up.
+
+### Example 5: "Bowling" Mode (From Documentation)
+
+Bright, energizing light for recreational activities:
+
+```json
+{"behavior":"adaptive_lighting","manual_control":false,"led_color":148,"al_config":{"min_brightness":70,"max_brightness":100,"min_color_temp":4000,"max_color_temp":5500,"transition":1}}
+```
+
+## Troubleshooting
+
+### Mode Not Working
+
+**Problem**: Selected mode but lights didn't change.
+
+**Solutions**:
+1. Check entity ID matches naming convention: `input_text.adaptive_lighting_settings_<mode_lowercase>`
+2. Verify JSON is valid (use a JSON validator)
+3. Check Home Assistant logs for errors: **Settings → System → Logs**
+4. Verify mode name in dropdown exactly matches entity ID (case-sensitive)
+
+### JSON Syntax Errors
+
+**Problem**: Mode causes errors in logs.
+
+**Common mistakes**:
+```json
+// BAD - trailing comma
+{"behavior":"adaptive_lighting","manual_control":false,}
+
+// BAD - missing quotes
+{behavior:"adaptive_lighting"}
+
+// BAD - single quotes
+{'behavior':'adaptive_lighting'}
+
+// GOOD
+{"behavior":"adaptive_lighting","manual_control":false}
+```
+
+**Solution**: Use a JSON validator (e.g., jsonlint.com) before saving.
+
+### Entity ID Naming Mistakes
+
+**Problem**: Mode selector has "Movie Night" but blueprint can't find settings.
+
+**Issue**: Spaces in mode name must become underscores in entity ID.
+
+**Correct mapping**:
+- "Movie Night" → `input_text.adaptive_lighting_settings_movie_night`
+- "Reading" → `input_text.adaptive_lighting_settings_reading`
+- "Focus Mode" → `input_text.adaptive_lighting_settings_focus_mode`
+
+### Schema Validation Errors
+
+**Problem**: Error like "extra keys not allowed" in logs.
+
+**Cause**: Putting AL settings at top level instead of in `al_config`.
+
+**Wrong**:
+```json
+{"behavior":"adaptive_lighting","min_brightness":20,"max_brightness":40}
+```
+
+**Correct**:
+```json
+{"behavior":"adaptive_lighting","manual_control":false,"led_color":170,"al_config":{"min_brightness":20,"max_brightness":40}}
+```
+
+### Mode Works But LED Doesn't Change
+
+**Problem**: AL settings apply but LED stays same color.
+
+**Solutions**:
+1. Verify LED entity configured in "Apply Lighting Mode Settings" blueprint automation
+2. Check LED entity supports `number.set_value` service
+3. Verify `led_color` value is 0-255
+4. Test LED manually: **Developer Tools → Services → number.set_value**
+
+## Extensibility
+
+### Adding New Behavior Types (Future)
+
+The blueprint can be extended to support new behaviors beyond AL, scene, and script.
+
+**Example**: Add "webhook" behavior to trigger external services:
+
+1. Edit `blueprints/automation/apply_lighting_mode.yaml`
+2. Add new condition to `choose` block:
+
+```yaml
+- conditions: "{{ behavior == 'webhook' }}"
+  sequence:
+    - service: rest_command.trigger_webhook
+      data:
+        url: "{{ settings.webhook_url }}"
+```
+
+3. Create mode with webhook behavior:
+
+```json
+{"behavior":"webhook","manual_control":false,"webhook_url":"https://example.com/hook","led_color":85,"al_config":{}}
+```
+
+**Note**: This is a **one-time blueprint change** that enables infinite webhook modes via helpers.
+
+### Convention Over Configuration
+
+The key principle: **Extend the blueprint once to add a capability, then use that capability unlimited times via helpers.**
+
+- Want 100 adaptive_lighting modes? Create 100 helpers (no blueprint changes)
+- Want scene-based modes? Blueprint already supports it (no changes needed)
+- Want webhook behavior? Add once to blueprint, then create unlimited webhook modes via helpers
+
+This is the power of convention-based design.
+
+---
+
+## Next Steps
+
+Now that you understand custom modes:
+
+1. **Experiment**: Create a "Reading" mode following the Quick Start
+2. **Iterate**: Try different brightness/color temp combinations
+3. **Share**: Document your favorite modes for others
+4. **Extend**: Consider new behavior types for your use case
+
+For more information:
+- [Room Configuration Guide](ROOM_CONFIGURATION_GUIDE.md) - Setting up rooms
+- [Package Setup Guide](PACKAGE_SETUP_GUIDE.md) - Installing global package
+- [README](README.md) - Main documentation
+- [Adaptive Lighting Docs](https://github.com/basnijholt/adaptive-lighting) - AL integration reference