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
This commit is contained in:
453
ADDING_MODES.md
Normal file
453
ADDING_MODES.md
Normal file
@@ -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
|
||||
445
CLAUDE.md
445
CLAUDE.md
@@ -4,66 +4,231 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
||||
|
||||
## Repository Overview
|
||||
|
||||
This is a Home Assistant blueprints repository containing automation blueprints for Home Assistant. The repository follows a simple structure with individual YAML blueprint files in the root directory alongside comprehensive documentation.
|
||||
This is a Home Assistant blueprints repository containing automation blueprints and a global package for Adaptive Lighting mode management. The repository uses a **pure blueprint architecture** with **convention-based entity lookup** for extensibility.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Blueprint Structure
|
||||
- **Blueprint files**: YAML files defining Home Assistant automation blueprints
|
||||
- **Documentation**: README.md provides detailed usage examples and configuration guidance
|
||||
- Each blueprint is self-contained with embedded metadata (name, description, domain, inputs)
|
||||
- **3 core blueprints** for Adaptive Lighting mode system (mode application + 2 weekend mode blueprints)
|
||||
- **3 optional blueprints** for Inovelli switch integration and presence-based automation
|
||||
- **Convention-based entity lookup**: Blueprints dynamically discover mode settings using naming convention (`adaptive_lighting_settings_{{mode}}`)
|
||||
- **Optional input handling**: Blueprints use `default: {}` pattern for optional inputs
|
||||
|
||||
### Current Blueprints
|
||||
### Package Structure
|
||||
- **1 global package** with 8 mode definitions (`adaptive_lighting_global.yaml`)
|
||||
- **Nested JSON schema**: Each mode contains `behavior`, `manual_control`, `led_color`, and `al_config` fields
|
||||
- **No room templates**: Room configuration done entirely via Home Assistant UI
|
||||
|
||||
#### Multi-Press Action Blueprint (`multi_press_action.yaml`)
|
||||
- **Purpose**: Trigger different actions based on rapid entity state changes (single, double, triple, quad press)
|
||||
- **Key features**:
|
||||
- Configurable time window for press detection
|
||||
- Immediate vs delayed single-press modes
|
||||
- Support for complex action sequences with conditions
|
||||
- **Architecture patterns**:
|
||||
- Uses Home Assistant blueprint format with input selectors
|
||||
- Implements state machine logic with press counting
|
||||
- Uses `mode: restart` to handle overlapping triggers
|
||||
- Template-based conditional logic for press count evaluation
|
||||
### User Workflow
|
||||
- **Zero YAML editing** for room setup
|
||||
- Create helpers via Settings → Helpers (dropdowns, toggles, text inputs)
|
||||
- Import blueprints via Settings → Blueprints
|
||||
- Create automations from blueprints via UI
|
||||
- Add custom modes by creating helpers following naming convention
|
||||
|
||||
## Core Blueprints
|
||||
|
||||
### Apply Lighting Mode Blueprint (`apply_lighting_mode.yaml`)
|
||||
**Purpose**: Data-driven mode application using convention-based entity lookup
|
||||
|
||||
**Key features**:
|
||||
- Convention-based entity lookup: `adaptive_lighting_settings_{{mode | lower | replace(' ', '_')}}`
|
||||
- Behavior polymorphism: Supports "adaptive_lighting", "scene", and "script" behaviors
|
||||
- Manual control support: Top-level `manual_control` attribute controls AL manual control state
|
||||
- Optional LED color integration for Inovelli switches
|
||||
- Mode: restart for debouncing rapid state changes
|
||||
|
||||
**Architecture patterns**:
|
||||
- Dynamic entity ID construction from mode name
|
||||
- Nested al_config extraction to avoid service validation errors
|
||||
- Conditional execution based on behavior type
|
||||
- Optional input handling with `default: {}`
|
||||
|
||||
### Weekend Mode Schedule Blueprint (`weekend_mode_schedule.yaml`)
|
||||
**Purpose**: Auto-enable/disable weekend mode based on day of week
|
||||
|
||||
**Key features**:
|
||||
- Single automation combines enable + disable logic using choose action
|
||||
- Time trigger checks day of week
|
||||
- Toggles input_boolean based on weekday condition
|
||||
- Mode: single to prevent overlapping executions
|
||||
|
||||
### Weekend Mode Apply Settings Blueprint (`weekend_mode_apply_settings.yaml`)
|
||||
**Purpose**: Apply AL adjustments when weekend mode toggles
|
||||
|
||||
**Key features**:
|
||||
- Delayed sunrise time for sleeping in on weekends
|
||||
- Extended sunset time for staying up later
|
||||
- Reduced max brightness
|
||||
- Reset to defaults when weekend mode turns off
|
||||
- Triggers on boolean state change + HA restart
|
||||
- Mode: restart for debouncing
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Adding New Blueprints
|
||||
1. Create new `.yaml` file in repository root
|
||||
2. Follow Home Assistant blueprint format:
|
||||
- `blueprint:` section with metadata
|
||||
- `input:` section with user-configurable parameters
|
||||
- `trigger:` and `action:` sections for automation logic
|
||||
3. Update README.md with new blueprint documentation
|
||||
4. Test blueprint by importing into Home Assistant development environment
|
||||
### Adding New Modes
|
||||
|
||||
**Two methods**:
|
||||
|
||||
1. **UI-created modes** (recommended):
|
||||
- Create input_text helper via Settings → Helpers
|
||||
- Follow naming convention: `input_text.adaptive_lighting_settings_{{mode}}`
|
||||
- Use nested schema: `{"behavior":"adaptive_lighting","manual_control":false,"led_color":170,"al_config":{...}}`
|
||||
- No restart required
|
||||
- Reference: ADDING_MODES.md tutorial
|
||||
|
||||
2. **Package-defined modes** (version controlled):
|
||||
- Edit `adaptive_lighting_global.yaml`
|
||||
- Add new input_text entity following existing patterns
|
||||
- Use nested schema with behavior, manual_control, led_color, al_config
|
||||
- Reload YAML configuration
|
||||
|
||||
**Key principle**: Modes are discovered by convention, not hardcoded. Adding a mode doesn't require blueprint changes.
|
||||
|
||||
### Blueprint Testing
|
||||
|
||||
Manual testing workflow (no automated testing framework for HA blueprints):
|
||||
1. Import blueprint to Home Assistant
|
||||
2. Create test helpers via UI
|
||||
3. Create automation from blueprint
|
||||
4. Test all input combinations
|
||||
5. Verify automation traces for debugging
|
||||
6. Check Home Assistant logs for errors
|
||||
|
||||
### Blueprint Best Practices
|
||||
- **Convention-based entity naming** for extensibility (modes, devices)
|
||||
- **Optional input handling** with `default: {}` for flexible configuration
|
||||
- **Mode: restart** for debouncing state changes
|
||||
- **Mode: single** for preventing overlapping executions
|
||||
- **Nested JSON schema** to satisfy service validation constraints
|
||||
- **Integration filters** (`domain: switch, integration: adaptive_lighting`) for user-friendly entity selection
|
||||
- Use descriptive names and clear descriptions for inputs
|
||||
- Provide sensible defaults for optional parameters
|
||||
- Include comprehensive selector types for user inputs
|
||||
- Use `mode: restart` or `mode: single` appropriately based on use case
|
||||
- Implement proper variable scoping within actions
|
||||
- Include detailed documentation with usage examples
|
||||
- Include comprehensive documentation in blueprint metadata
|
||||
|
||||
### Testing
|
||||
- No automated testing framework (blueprints are tested in Home Assistant directly)
|
||||
- Manual testing involves:
|
||||
1. Importing blueprint into Home Assistant
|
||||
2. Creating automation from blueprint
|
||||
3. Testing various input combinations and edge cases
|
||||
4. Verifying automation traces for debugging
|
||||
### Home Assistant Blueprint Format
|
||||
|
||||
### Import URLs
|
||||
- Repository uses custom Git hosting at `git.johnogle.info`
|
||||
- Import URL pattern: `https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/{blueprint_name}.yaml`
|
||||
Blueprints follow this structure:
|
||||
```yaml
|
||||
blueprint:
|
||||
name: Blueprint Name
|
||||
description: Clear description of what this blueprint does
|
||||
domain: automation
|
||||
|
||||
input:
|
||||
input_name:
|
||||
name: User-Facing Name
|
||||
description: Clear description of this input
|
||||
default: {} # For optional inputs
|
||||
selector:
|
||||
entity:
|
||||
domain: switch
|
||||
integration: adaptive_lighting # Optional filter
|
||||
|
||||
mode: restart # or single, queued, parallel
|
||||
max_exceeded: silent
|
||||
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: !input input_name
|
||||
|
||||
variables:
|
||||
var_name: !input input_name
|
||||
derived_var: "{{ template_expression }}"
|
||||
|
||||
action:
|
||||
- service: some.service
|
||||
target:
|
||||
entity_id: "{{ var_name }}"
|
||||
data:
|
||||
setting: "{{ derived_var }}"
|
||||
```
|
||||
|
||||
### Input Selectors
|
||||
|
||||
Common selector types used in this repository:
|
||||
|
||||
**Entity selectors**:
|
||||
```yaml
|
||||
selector:
|
||||
entity:
|
||||
domain: input_select # Dropdown helpers
|
||||
# or
|
||||
domain: input_boolean # Toggle helpers
|
||||
# or
|
||||
domain: switch
|
||||
integration: adaptive_lighting # Filter by integration
|
||||
# or
|
||||
domain: number # Number entities (LED color)
|
||||
```
|
||||
|
||||
**Time selector**:
|
||||
```yaml
|
||||
selector:
|
||||
time: # HH:MM:SS time picker
|
||||
```
|
||||
|
||||
**Number selector**:
|
||||
```yaml
|
||||
selector:
|
||||
number:
|
||||
min: 1
|
||||
max: 100
|
||||
step: 1
|
||||
unit_of_measurement: "%"
|
||||
```
|
||||
|
||||
**Action selector**:
|
||||
```yaml
|
||||
selector:
|
||||
action: # Full action sequence builder
|
||||
```
|
||||
|
||||
### Mode Settings Schema
|
||||
|
||||
Each mode uses this nested JSON structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"behavior": "adaptive_lighting", // or "scene", "script"
|
||||
"manual_control": false, // Controls AL manual control state
|
||||
"led_color": 170, // 0-255 hue value for Inovelli LED
|
||||
"al_config": { // Nested object for AL settings
|
||||
"min_brightness": 20,
|
||||
"max_brightness": 80,
|
||||
"min_color_temp": 2000,
|
||||
"max_color_temp": 4000,
|
||||
"transition": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Why nested?**: The `adaptive_lighting.change_switch_settings` service performs strict key validation, rejecting unknown keys. The nested structure isolates AL-specific settings in `al_config`, while metadata like `behavior` and `led_color` remain at the top level.
|
||||
|
||||
**Manual control**: The `manual_control` attribute (defaults to `false`) controls whether AL manual control is enabled for the mode. When `true`, AL is paused and won't adjust lights. The blueprint always calls `adaptive_lighting.set_manual_control` with this value.
|
||||
|
||||
## File Organization
|
||||
|
||||
```
|
||||
/
|
||||
├── README.md # Comprehensive documentation
|
||||
├── multi_press_action.yaml # Multi-press detection blueprint
|
||||
├── blueprints/
|
||||
│ └── automation/
|
||||
│ ├── apply_lighting_mode.yaml # Core: Data-driven mode application
|
||||
│ ├── weekend_mode_schedule.yaml # Core: Auto-enable/disable weekend mode
|
||||
│ ├── weekend_mode_apply_settings.yaml # Core: Apply weekend AL adjustments
|
||||
│ ├── inovelli_mode_cycling.yaml # Optional: Config button mode cycling
|
||||
│ ├── inovelli_button_actions.yaml # Optional: Multi-tap button actions
|
||||
│ ├── presence_mode_reset.yaml # Optional: Auto-reset on room exit
|
||||
│ └── occupancy_controlled_lights.yaml # Standalone: Occupancy-based lighting
|
||||
├── packages/
|
||||
│ └── adaptive_lighting_global.yaml # Global mode definitions (8 modes)
|
||||
├── hardware/
|
||||
│ └── inovelli/
|
||||
│ └── blue-dimmer-2-in-1-vzt31.md # Inovelli Blue Dimmer documentation
|
||||
├── README.md # Main documentation
|
||||
├── PACKAGE_SETUP_GUIDE.md # Global package installation
|
||||
├── ROOM_CONFIGURATION_GUIDE.md # UI-driven room setup
|
||||
├── ADDING_MODES.md # Custom mode creation tutorial
|
||||
└── CLAUDE.md # This file
|
||||
```
|
||||
|
||||
@@ -75,13 +240,211 @@ This is a Home Assistant blueprints repository containing automation blueprints
|
||||
- `number`: Numeric input with min/max/step validation
|
||||
- `boolean`: True/false toggle
|
||||
- `text`: String input fields
|
||||
- `time`: Time picker (HH:MM:SS format)
|
||||
|
||||
### Template Usage
|
||||
- Use `!input` to reference blueprint inputs
|
||||
- Template conditions with `{{ }}` syntax for dynamic logic
|
||||
- Variable assignment and reference within action sequences
|
||||
- Jinja2 filters for string manipulation (`lower`, `replace`, `from_json`)
|
||||
|
||||
### Automation Modes
|
||||
- `restart`: Stops current execution and restarts on new trigger
|
||||
- `restart`: Stops current execution and restarts on new trigger (used for debouncing)
|
||||
- `single`: Ignores new triggers while running
|
||||
- `parallel`: Allows multiple simultaneous executions
|
||||
- `queued`: Queues triggers and executes sequentially
|
||||
|
||||
### Pattern References
|
||||
|
||||
**Optional input handling** (`presence_mode_reset.yaml:98-116`):
|
||||
```yaml
|
||||
input:
|
||||
optional_entity:
|
||||
default: {}
|
||||
selector:
|
||||
entity:
|
||||
domain: input_select
|
||||
|
||||
# Later in action:
|
||||
- if:
|
||||
- condition: template
|
||||
value_template: "{{ optional_entity not in [none, {}, ''] }}"
|
||||
then:
|
||||
- service: some.service
|
||||
target:
|
||||
entity_id: "{{ optional_entity }}"
|
||||
```
|
||||
|
||||
**Integration filter** (`inovelli_button_actions.yaml:36-42`):
|
||||
```yaml
|
||||
selector:
|
||||
entity:
|
||||
domain: switch
|
||||
integration: adaptive_lighting
|
||||
```
|
||||
|
||||
**Choose action pattern** (for behavior polymorphism):
|
||||
```yaml
|
||||
- choose:
|
||||
- conditions: "{{ behavior == 'adaptive_lighting' }}"
|
||||
sequence:
|
||||
- service: adaptive_lighting.change_switch_settings
|
||||
data: "{{ al_config }}"
|
||||
|
||||
- conditions: "{{ behavior == 'scene' }}"
|
||||
sequence:
|
||||
- service: scene.turn_on
|
||||
target:
|
||||
entity_id: "{{ settings.scene_entity }}"
|
||||
|
||||
- conditions: "{{ behavior == 'script' }}"
|
||||
sequence:
|
||||
- service: script.turn_on
|
||||
target:
|
||||
entity_id: "{{ settings.script_entity }}"
|
||||
```
|
||||
|
||||
## Import URLs
|
||||
|
||||
Blueprints are hosted at:
|
||||
- Base URL: `https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/`
|
||||
- Pattern: `{base_url}/blueprints/automation/{blueprint_name}.yaml`
|
||||
|
||||
Example: `https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/blueprints/automation/apply_lighting_mode.yaml`
|
||||
|
||||
## Design Principles
|
||||
|
||||
### Convention Over Configuration
|
||||
|
||||
**Key insight**: Extend the blueprint once to add a capability, then use that capability unlimited times via helpers.
|
||||
|
||||
Examples:
|
||||
- Want 100 adaptive_lighting modes? Create 100 helpers following naming convention (no blueprint changes)
|
||||
- Want scene-based modes? Blueprint already supports it (no changes needed)
|
||||
- Want custom "Bowling" mode? Create one helper with correct entity ID (no changes needed)
|
||||
|
||||
**This is the power of convention-based design.**
|
||||
|
||||
### Zero YAML Editing for Users
|
||||
|
||||
Room configuration workflow:
|
||||
1. Create helpers via UI (dropdowns, toggles)
|
||||
2. Create automations from blueprints via UI
|
||||
3. Test by switching modes via UI
|
||||
4. Add custom modes by creating text helpers via UI
|
||||
|
||||
No template copying, no YAML editing, no search/replace, no package files per room.
|
||||
|
||||
### Nested Schema for Service Validation
|
||||
|
||||
Why nested `al_config`?
|
||||
- Home Assistant services perform strict validation
|
||||
- Unknown keys cause errors
|
||||
- Nested structure separates metadata from service parameters
|
||||
- Only `al_config` is passed to `adaptive_lighting.change_switch_settings`
|
||||
- Top-level fields (`behavior`, `manual_control`, `led_color`) used by blueprint logic
|
||||
|
||||
### Behavior Polymorphism
|
||||
|
||||
Modes can have different behaviors:
|
||||
- **adaptive_lighting**: Apply AL settings (default)
|
||||
- **scene**: Activate Home Assistant scene
|
||||
- **script**: Run Home Assistant script
|
||||
|
||||
This enables complex use cases (movie scenes, light shows) without modifying blueprint core logic.
|
||||
|
||||
## Migration Notes
|
||||
|
||||
**No migration needed** - repository contains only blueprints and one global package, no deployed room configurations.
|
||||
|
||||
**For future users**: If this becomes public, users would migrate from template packages to blueprint + UI workflow by:
|
||||
1. Creating helpers via UI matching their room names
|
||||
2. Importing blueprints
|
||||
3. Creating automations from blueprints
|
||||
4. Deleting old package files
|
||||
5. Reloading YAML configuration
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
No performance concerns:
|
||||
- Automations trigger only on mode changes (user-initiated, infrequent)
|
||||
- JSON parsing is fast and cached by Home Assistant
|
||||
- Convention-based lookup is simple string templating
|
||||
- No polling, no external services, no heavy computation
|
||||
- Mode: restart prevents rapid-fire executions
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Service Validation Errors
|
||||
|
||||
**Symptom**: "extra keys not allowed" in logs
|
||||
|
||||
**Cause**: Passing top-level fields to `adaptive_lighting.change_switch_settings`
|
||||
|
||||
**Solution**: Only pass `al_config` nested object to service
|
||||
|
||||
### Missing Mode Entities
|
||||
|
||||
**Symptom**: Blueprint fails to find mode settings
|
||||
|
||||
**Cause**: Entity ID doesn't match naming convention
|
||||
|
||||
**Solution**: Verify entity ID follows pattern `input_text.adaptive_lighting_settings_{{mode | lower | replace(' ', '_')}}`
|
||||
|
||||
### LED Color Not Updating
|
||||
|
||||
**Symptom**: Mode changes but LED stays same color
|
||||
|
||||
**Causes**:
|
||||
1. LED entity not configured (left empty)
|
||||
2. Incorrect entity ID
|
||||
3. Inovelli switch firmware issue
|
||||
|
||||
**Solution**: Check automation configuration, verify entity ID, test LED manually
|
||||
|
||||
## Testing Guidelines
|
||||
|
||||
Since Home Assistant blueprints have no automated testing framework, all testing is manual:
|
||||
|
||||
1. **Blueprint Import**: Verify imports without errors in HA
|
||||
2. **Helper Creation**: Create test helpers via UI
|
||||
3. **Automation Creation**: Create test automations from blueprints
|
||||
4. **Mode Switching**: Test all mode combinations
|
||||
5. **Custom Modes**: Create custom mode and verify convention-based lookup
|
||||
6. **LED Integration**: Verify LED colors update (if configured)
|
||||
7. **Weekend Mode**: Test schedule and AL adjustments
|
||||
8. **HA Restart**: Verify persistence across restarts
|
||||
9. **Error Handling**: Test missing entities, invalid JSON, etc.
|
||||
10. **Logs**: Check for errors in Settings → System → Logs
|
||||
|
||||
Always check automation traces (Settings → Automations → [automation] → Traces) for debugging.
|
||||
|
||||
## Key Differences from Traditional Approach
|
||||
|
||||
**Old approach** (template packages):
|
||||
- Copy package file per room
|
||||
- Search/replace entity IDs
|
||||
- Edit YAML to add modes
|
||||
- Hardcoded choose blocks for each mode
|
||||
- Adding mode requires editing every room
|
||||
|
||||
**New approach** (pure blueprints):
|
||||
- Create helpers via UI
|
||||
- Create automations via UI
|
||||
- Zero YAML editing for rooms
|
||||
- Convention-based mode lookup
|
||||
- Adding mode = create ONE helper
|
||||
|
||||
**Benefits**:
|
||||
- Lower friction for users
|
||||
- No YAML syntax errors from manual editing
|
||||
- Extensible without code changes
|
||||
- Easier to maintain
|
||||
- Better user experience
|
||||
|
||||
## Resources
|
||||
|
||||
- [Home Assistant Blueprint Documentation](https://www.home-assistant.io/docs/blueprint/)
|
||||
- [Adaptive Lighting Integration](https://github.com/basnijholt/adaptive-lighting)
|
||||
- [Jinja2 Template Reference](https://jinja.palletsprojects.com/)
|
||||
- [YAML Specification](https://yaml.org/)
|
||||
|
||||
@@ -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
|
||||
|
||||
130
README.md
130
README.md
@@ -2,70 +2,110 @@
|
||||
|
||||
## Adaptive Lighting Mode System
|
||||
|
||||
A comprehensive mode-based lighting control system for Inovelli Blue Dimmer
|
||||
Switches with Adaptive Lighting integration.
|
||||
A comprehensive mode-based lighting control system with **pure blueprint architecture** and **zero YAML editing** for room setup. Features convention-based mode lookup allowing unlimited custom modes with no code changes.
|
||||
|
||||
### Features
|
||||
|
||||
- **Room-specific modes**: Define custom lighting modes per room (Reading,
|
||||
Theater, Sleep, etc.)
|
||||
- **Visual LED feedback**: LED bar color indicates current mode
|
||||
- **Config button control**: Press config button to cycle through modes
|
||||
- **Multi-tap actions**: Double-tap boost, triple-tap max/night light
|
||||
- **Adaptive Lighting integration**: Dynamic brightness and color following sun
|
||||
position
|
||||
- **Version controlled**: All configuration in git-trackable package files
|
||||
- **Convention-based mode lookup**: Add "Bowling" mode by creating one helper - no code changes needed
|
||||
- **UI-driven room configuration**: Setup entire rooms via Home Assistant UI - zero YAML editing required
|
||||
- **Weekend mode blueprints**: Automatic schedule adjustments for weekends (delayed sunrise, extended sunset)
|
||||
- **Extensible behavior system**: Supports Adaptive Lighting, scene-based, and script-based modes
|
||||
- **Manual control support**: Any mode can pause AL with `manual_control` attribute
|
||||
- **Visual LED feedback**: LED bar color indicates current mode (optional Inovelli integration)
|
||||
- **8 essential modes**: Adaptive, Relaxing, Sleep, Theater, Party, Cooking, Dining, Cleanup
|
||||
|
||||
### System Components
|
||||
### Architecture
|
||||
|
||||
**Blueprints** (Reusable):
|
||||
- `inovelli_mode_cycling.yaml` - Config button cycles modes with LED feedback
|
||||
- `inovelli_button_actions.yaml` - Multi-tap brightness controls
|
||||
- `presence_mode_reset.yaml` - Auto-reset on room exit
|
||||
**Pure blueprint architecture** with global mode definitions:
|
||||
|
||||
**Packages** (Templates):
|
||||
- `adaptive_lighting_global.yaml` - Shared mode definitions and colors
|
||||
- `adaptive_lighting_bedroom_template.yaml` - Complete bedroom example
|
||||
- `adaptive_lighting_living_room_template.yaml` - Living room example
|
||||
- `adaptive_lighting_simple_template.yaml` - Minimal single-mode room
|
||||
- **3 core blueprints**: Mode application + 2 weekend mode blueprints
|
||||
- **1 global package**: 8 shipped modes with nested JSON schema
|
||||
- **UI-created helpers**: Room-specific dropdowns and toggles created via Settings → Helpers
|
||||
- **UI-created automations**: No package copying or YAML editing required
|
||||
|
||||
### Setup Guide
|
||||
**Key principle**: **Convention over configuration** - modes are discovered by naming convention, not hardcoded logic.
|
||||
|
||||
**Quick Start**:
|
||||
1. Install Adaptive Lighting integration via HACS
|
||||
2. Follow [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) to enable packages
|
||||
3. Copy templates from `packages/` directory
|
||||
4. Import blueprints via UI
|
||||
5. See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for examples
|
||||
### Quick Start
|
||||
|
||||
**Documentation**:
|
||||
- [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) - Initial setup and version
|
||||
control
|
||||
- [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) - Room-by-room
|
||||
examples
|
||||
- [ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md](ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md) -
|
||||
Complete system design
|
||||
**Step 1: Install Adaptive Lighting integration via HACS**
|
||||
|
||||
**Files**:
|
||||
- `packages/adaptive_lighting_global.yaml` - Required for all rooms
|
||||
- `packages/adaptive_lighting_bedroom_template.yaml` - Template for bedrooms
|
||||
- `packages/adaptive_lighting_living_room_template.yaml` - Template for common
|
||||
areas
|
||||
- `packages/adaptive_lighting_simple_template.yaml` - Template for simple rooms
|
||||
- `blueprints/automation/inovelli_mode_cycling.yaml` - Config button mode
|
||||
cycling
|
||||
- `blueprints/automation/inovelli_button_actions.yaml` - Multi-tap actions
|
||||
- `blueprints/automation/presence_mode_reset.yaml` - Auto-reset on room exit
|
||||
**Step 2: Import blueprints**
|
||||
|
||||
Settings → Automations & Scenes → Blueprints → Import Blueprint
|
||||
|
||||
Import URLs (see below for full list)
|
||||
|
||||
**Step 3: Install global package**
|
||||
|
||||
Follow [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) to install `adaptive_lighting_global.yaml`
|
||||
|
||||
**Step 4: Create helpers and automations via UI**
|
||||
|
||||
Follow [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for complete UI workflow
|
||||
|
||||
**Step 5: (Optional) Add custom modes**
|
||||
|
||||
Follow [ADDING_MODES.md](ADDING_MODES.md) to create "Reading" mode or any custom mode
|
||||
|
||||
### Documentation
|
||||
|
||||
- [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) - Installing global package and blueprints
|
||||
- [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) - UI-driven room setup (no YAML editing)
|
||||
- [ADDING_MODES.md](ADDING_MODES.md) - Tutorial for creating custom modes
|
||||
- [ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md](ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md) - System architecture design
|
||||
|
||||
### File Inventory
|
||||
|
||||
**Blueprints** (3 core + 3 optional):
|
||||
|
||||
**Core blueprints** (required for mode system):
|
||||
- `blueprints/automation/apply_lighting_mode.yaml` - Data-driven mode application with convention-based entity lookup
|
||||
- `blueprints/automation/weekend_mode_schedule.yaml` - Auto-enable/disable weekend mode based on day of week
|
||||
- `blueprints/automation/weekend_mode_apply_settings.yaml` - Apply AL adjustments when weekend mode toggles
|
||||
|
||||
**Optional blueprints** (for Inovelli switches and presence-based automation):
|
||||
- `blueprints/automation/inovelli_mode_cycling.yaml` - Config button cycles modes with LED feedback
|
||||
- `blueprints/automation/inovelli_button_actions.yaml` - Multi-tap brightness controls
|
||||
- `blueprints/automation/presence_mode_reset.yaml` - Auto-reset mode on room exit
|
||||
|
||||
**Packages** (1 file):
|
||||
- `packages/adaptive_lighting_global.yaml` - Global mode definitions (8 modes with nested schema)
|
||||
|
||||
**Documentation** (6 files):
|
||||
- `README.md` - Main documentation (this file)
|
||||
- `PACKAGE_SETUP_GUIDE.md` - Global package installation
|
||||
- `ROOM_CONFIGURATION_GUIDE.md` - UI-driven room setup
|
||||
- `ADDING_MODES.md` - Custom mode creation tutorial
|
||||
- `CLAUDE.md` - Claude Code instructions
|
||||
- `ADAPTIVE_LIGHTING_CONTROL_SYSTEM_DESIGN.md` - Architecture design doc
|
||||
|
||||
### Import URLs
|
||||
|
||||
**Blueprints**:
|
||||
**Core mode system blueprints**:
|
||||
```
|
||||
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 Inovelli and presence blueprints**:
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
### Extensibility Example
|
||||
|
||||
**Traditional approach** (hardcoded): Adding "Bowling" mode requires editing blueprint code, modifying choose blocks, updating all rooms.
|
||||
|
||||
**Convention-based approach** (this system): Create ONE helper via UI:
|
||||
1. Settings → Helpers → Create Text input
|
||||
2. Name: `input_text.adaptive_lighting_settings_bowling`
|
||||
3. Value: `{"behavior":"adaptive_lighting","manual_control":false,"led_color":148,"al_config":{...}}`
|
||||
4. Add "Bowling" to your room's mode dropdown
|
||||
5. Done! No blueprint changes, works immediately in all rooms.
|
||||
|
||||
---
|
||||
|
||||
## Occupancy Controlled Lights Blueprint
|
||||
|
||||
@@ -1,200 +1,485 @@
|
||||
# Room Configuration Guide
|
||||
|
||||
Complete examples of configuring different room types with the Adaptive
|
||||
Lighting Mode System.
|
||||
This guide walks you through configuring rooms using the **pure blueprint architecture**. All configuration is done via the Home Assistant UI - **no YAML editing required**.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Basic Room Setup (UI Workflow)](#basic-room-setup-ui-workflow)
|
||||
- [Advanced: Weekend Mode](#advanced-weekend-mode-optional)
|
||||
- [Example 1: Master Bedroom](#example-1-master-bedroom)
|
||||
- [Example 2: Living Room](#example-2-living-room)
|
||||
- [Example 3: Simple Bathroom](#example-3-simple-bathroom)
|
||||
- [Testing Checklist](#testing-checklist)
|
||||
- [Customization](#customization)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before configuring a room:
|
||||
|
||||
- ✅ Global package loaded (`adaptive_lighting_global.yaml`)
|
||||
- ✅ 3 blueprints imported (apply_lighting_mode, weekend_mode_schedule, weekend_mode_apply_settings)
|
||||
- ✅ Adaptive Lighting integration configured
|
||||
- ✅ Adaptive Lighting switch created for your room
|
||||
|
||||
If you haven't done these steps, see [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) first.
|
||||
|
||||
## Basic Room Setup (UI Workflow)
|
||||
|
||||
This is the core workflow for every room. All steps are done in the Home Assistant UI.
|
||||
|
||||
### Step 1: Create Mode Selector Helper
|
||||
|
||||
**1.1 Navigate to Helpers**
|
||||
|
||||
Settings → Devices & Services → Helpers
|
||||
|
||||
**1.2 Create Dropdown Helper**
|
||||
|
||||
- Click **+ Create Helper → Dropdown**
|
||||
- Configure:
|
||||
- **Name**: `{Room} Lighting Mode` (e.g., "Master Bedroom Lighting Mode")
|
||||
- **Icon**: `mdi:lightbulb-multiple` (optional)
|
||||
- **Options**: Add the modes you want (from the 8 shipped modes)
|
||||
- Adaptive
|
||||
- Relaxing
|
||||
- Sleep
|
||||
- Theater
|
||||
- Party
|
||||
- Cooking
|
||||
- Dining
|
||||
- Cleanup
|
||||
- **Initial option**: `Adaptive`
|
||||
|
||||
**1.3 Note the Entity ID**
|
||||
|
||||
After creation, click the helper to see its entity ID (e.g., `input_select.master_bedroom_lighting_mode`). You'll need this for the next step.
|
||||
|
||||
### Step 2: Create Mode Application Automation
|
||||
|
||||
**2.1 Navigate to Blueprints**
|
||||
|
||||
Settings → Automations & Scenes → Blueprints
|
||||
|
||||
**2.2 Create Automation from Blueprint**
|
||||
|
||||
- Find "Apply Lighting Mode Settings" blueprint
|
||||
- Click **Create Automation**
|
||||
|
||||
**2.3 Configure Inputs**
|
||||
|
||||
- **Mode Input Select**: Select your dropdown helper (e.g., `input_select.master_bedroom_lighting_mode`)
|
||||
- **Adaptive Lighting Switch**: Select your room's AL switch (e.g., `switch.adaptive_lighting_master_bedroom`)
|
||||
- **LED Color Entity (Optional)**:
|
||||
- Leave empty if you don't have Inovelli switches
|
||||
- Select `number.{device_name}_led_color_when_on` if you have an Inovelli switch
|
||||
|
||||
**2.4 Name the Automation**
|
||||
|
||||
- Suggested name: `{Room}: Apply Lighting Mode` (e.g., "Master Bedroom: Apply Lighting Mode")
|
||||
- Click **Save**
|
||||
|
||||
### Step 3: Test Mode Switching
|
||||
|
||||
**3.1 Find Your Mode Selector**
|
||||
|
||||
- Go to Overview dashboard
|
||||
- Or Settings → Devices & Services → Helpers → Find your dropdown
|
||||
|
||||
**3.2 Switch Between Modes**
|
||||
|
||||
- Select different modes from the dropdown
|
||||
- Verify lights change appropriately:
|
||||
- **Adaptive**: Follows AL defaults
|
||||
- **Relaxing**: Dim, warm (20-40% brightness, 2000-2500K)
|
||||
- **Sleep**: Very dim red/amber (1-5% brightness)
|
||||
- **Theater**: Dim, cool (5-20% brightness)
|
||||
- **Party**: Bright, dynamic (60-90% brightness)
|
||||
- **Cooking**: Bright, cool task lighting (90-100% brightness)
|
||||
- **Dining**: Medium, warm (40-70% brightness)
|
||||
- **Cleanup**: Bright, standard (80-100% brightness)
|
||||
|
||||
**3.3 Verify LED Updates (If Configured)**
|
||||
|
||||
- If you configured an LED entity, verify the Inovelli switch LED changes color with each mode
|
||||
|
||||
**Congratulations!** You've configured basic mode switching for your room with zero YAML editing.
|
||||
|
||||
## Advanced: Weekend Mode (Optional)
|
||||
|
||||
Weekend mode automatically adjusts Adaptive Lighting settings on weekends (delayed sunrise, extended sunset, reduced brightness).
|
||||
|
||||
### Step 1: Create Weekend Mode Toggle
|
||||
|
||||
**1.1 Navigate to Helpers**
|
||||
|
||||
Settings → Devices & Services → Helpers
|
||||
|
||||
**1.2 Create Toggle Helper**
|
||||
|
||||
- Click **+ Create Helper → Toggle**
|
||||
- Configure:
|
||||
- **Name**: `{Room} Weekend Mode` (e.g., "Master Bedroom Weekend Mode")
|
||||
- **Icon**: `mdi:calendar-weekend` (optional)
|
||||
- **Initial state**: Off
|
||||
|
||||
**1.3 Note the Entity ID**
|
||||
|
||||
Example: `input_boolean.master_bedroom_weekend_mode`
|
||||
|
||||
### Step 2: Create Schedule Automation
|
||||
|
||||
**2.1 Create from Blueprint**
|
||||
|
||||
Settings → Automations & Scenes → Blueprints → "Weekend Mode Schedule"
|
||||
|
||||
**2.2 Configure Inputs**
|
||||
|
||||
- **Weekend Mode Boolean**: Select your toggle helper
|
||||
- **Toggle Time**: When to check and toggle weekend mode (default: 22:00:00)
|
||||
- Recommended: Late evening (e.g., 22:00 / 10:00 PM)
|
||||
|
||||
**2.3 Save**
|
||||
|
||||
Name: `{Room}: Weekend Mode Schedule`
|
||||
|
||||
**How it works**:
|
||||
- Friday/Saturday at toggle time → Turns ON weekend mode
|
||||
- Sunday-Thursday at toggle time → Turns OFF weekend mode
|
||||
|
||||
### Step 3: Create Apply Settings Automation
|
||||
|
||||
**3.1 Create from Blueprint**
|
||||
|
||||
Settings → Automations & Scenes → Blueprints → "Weekend Mode Apply Settings"
|
||||
|
||||
**3.2 Configure Inputs**
|
||||
|
||||
- **Weekend Mode Boolean**: Select your toggle helper (same as Step 2)
|
||||
- **Adaptive Lighting Switch**: Select your room's AL switch
|
||||
- **Weekend Sunrise Time**: When sunrise should be on weekends (default: 10:00:00)
|
||||
- **Weekend Sunset Time**: When sunset should be on weekends (default: 01:00:00)
|
||||
- **Weekend Max Brightness**: Maximum brightness on weekends (default: 60%)
|
||||
|
||||
**3.3 Save**
|
||||
|
||||
Name: `{Room}: Weekend Mode Apply Settings`
|
||||
|
||||
**How it works**:
|
||||
- When weekend mode turns ON → Applies delayed sunrise, extended sunset, reduced brightness
|
||||
- When weekend mode turns OFF → Resets to AL default settings
|
||||
|
||||
### Step 4: Test Weekend Mode
|
||||
|
||||
**4.1 Manual Toggle Test**
|
||||
|
||||
- Toggle your weekend mode boolean ON manually
|
||||
- Verify AL settings change (check Developer Tools → States → your AL switch attributes)
|
||||
- Toggle OFF
|
||||
- Verify AL settings reset
|
||||
|
||||
**4.2 Schedule Test (Optional)**
|
||||
|
||||
- Temporarily change toggle time to 1 minute in future
|
||||
- Wait for trigger
|
||||
- Verify boolean toggles based on current day of week
|
||||
|
||||
## Example 1: Master Bedroom
|
||||
|
||||
**Goal**: Full control with optional AL, reading/sleep modes, weekend mode
|
||||
**Goal**: Full mode control with weekend mode, optional Inovelli integration
|
||||
|
||||
**Hardware**:
|
||||
- Inovelli Blue Dimmer: `bedroom_switch` (Zigbee2MQTT name)
|
||||
- Lights: `light.bedroom_ceiling`, `light.bedroom_lamp_1`,
|
||||
`light.bedroom_lamp_2`
|
||||
- No presence sensor (privacy)
|
||||
**Room Type**: Private bedroom with comprehensive lighting control
|
||||
|
||||
### Adaptive Lighting Configuration
|
||||
|
||||
In `configuration.yaml` (if not already done):
|
||||
|
||||
**Adaptive Lighting Configuration** (in `configuration.yaml`):
|
||||
```yaml
|
||||
adaptive_lighting:
|
||||
- name: bedroom
|
||||
- name: master_bedroom
|
||||
lights:
|
||||
- light.bedroom_ceiling
|
||||
- light.bedroom_lamp_1
|
||||
- light.bedroom_lamp_2
|
||||
- light.master_bedroom_ceiling
|
||||
- light.master_bedroom_lamp_1
|
||||
- light.master_bedroom_lamp_2
|
||||
interval: 90
|
||||
transition: 45
|
||||
take_over_control: true
|
||||
autoreset_control_seconds: 3600 # 1 hour gentle reset
|
||||
```
|
||||
|
||||
**Package File** (`packages/adaptive_lighting_master_bedroom.yaml`):
|
||||
Restart Home Assistant after editing configuration.yaml.
|
||||
|
||||
Copy from `adaptive_lighting_bedroom_template.yaml`, customize:
|
||||
- Modes: Adaptive, Reading, Relaxing, Sleep, Manual Override
|
||||
- Weekend mode enabled
|
||||
- Default mode: Adaptive
|
||||
### UI Configuration Steps
|
||||
|
||||
**Blueprint Automations** (create via UI):
|
||||
**Step 1: Create Mode Selector**
|
||||
- Name: "Master Bedroom Lighting Mode"
|
||||
- Entity ID: `input_select.master_bedroom_lighting_mode`
|
||||
- Options: Adaptive, Relaxing, Sleep, Theater (for movies in bed), Party (rare, but available)
|
||||
- Initial: Adaptive
|
||||
|
||||
1. **Config Button Mode Cycling**:
|
||||
- Blueprint: Inovelli Mode Cycling
|
||||
- Switch Action Event: `event.bedroom_switch_action`
|
||||
- Mode Input Select: `input_select.bedroom_lighting_mode`
|
||||
- LED Color Entity: `number.bedroom_switch_led_color_when_on`
|
||||
- Zigbee2MQTT Device Name: `bedroom_switch`
|
||||
**Step 2: Create Mode Application Automation**
|
||||
- Blueprint: Apply Lighting Mode Settings
|
||||
- Mode Input Select: `input_select.master_bedroom_lighting_mode`
|
||||
- AL Switch: `switch.adaptive_lighting_master_bedroom`
|
||||
- LED Entity: `number.master_bedroom_switch_led_color_when_on` (if Inovelli)
|
||||
- Name: "Master Bedroom: Apply Lighting Mode"
|
||||
|
||||
2. **Button Actions**:
|
||||
- Blueprint: Inovelli Button Actions
|
||||
- Switch Action Event: `event.bedroom_switch_action`
|
||||
- AL Switch: `switch.adaptive_lighting_bedroom`
|
||||
- Target Lights: `light.bedroom_ceiling`, `light.bedroom_lamp_1`,
|
||||
`light.bedroom_lamp_2`
|
||||
- Auto-Reset: 30 minutes
|
||||
**Step 3: Create Weekend Mode Helpers and Automations**
|
||||
- Toggle: `input_boolean.master_bedroom_weekend_mode`
|
||||
- Schedule automation: Toggle at 22:00
|
||||
- Apply settings automation:
|
||||
- Sunrise: 10:00 (sleep in on weekends)
|
||||
- Sunset: 01:00 (stay up later)
|
||||
- Max brightness: 60%
|
||||
|
||||
**Testing**:
|
||||
- [ ] Press config button → mode cycles through all 5 modes
|
||||
- [ ] LED changes color for each mode
|
||||
- [ ] Double-tap up → brightness boosts
|
||||
- [ ] Weekend mode enables Friday 10pm
|
||||
- [ ] Sunrise shifts to 10am on weekend
|
||||
### Testing
|
||||
|
||||
## Example 2: Living Room (Common Area)
|
||||
- [ ] Mode selector cycles through all modes via UI
|
||||
- [ ] Lights change appropriately for each mode
|
||||
- [ ] LED changes color for each mode (if Inovelli)
|
||||
- [ ] Weekend mode enables Friday evening
|
||||
- [ ] Sunrise shifts to 10am when weekend mode active
|
||||
- [ ] Weekend mode disables Sunday evening
|
||||
|
||||
**Goal**: Entertainment modes (Theater, Party), presence control
|
||||
## Example 2: Living Room
|
||||
|
||||
**Hardware**:
|
||||
- Inovelli Blue Dimmer: `living_room_switch`
|
||||
- Lights: `light.living_room_ceiling`, `light.living_room_lamp_1`
|
||||
- Presence: `binary_sensor.living_room_occupancy`
|
||||
**Goal**: Entertainment modes (Theater, Party), standard adaptive lighting
|
||||
|
||||
**Package File** (`packages/adaptive_lighting_living_room.yaml`):
|
||||
**Room Type**: Common area with social and entertainment use
|
||||
|
||||
Copy from `adaptive_lighting_living_room_template.yaml`
|
||||
- Modes: Adaptive, Theater, Party, Reading
|
||||
- Auto-reset mode to Adaptive when lights turn off
|
||||
### Adaptive Lighting Configuration
|
||||
|
||||
**Blueprint Automations**:
|
||||
```yaml
|
||||
adaptive_lighting:
|
||||
- name: living_room
|
||||
lights:
|
||||
- light.living_room_ceiling
|
||||
- light.living_room_lamp_1
|
||||
- light.living_room_lamp_2
|
||||
interval: 90
|
||||
transition: 30
|
||||
```
|
||||
|
||||
1. **Config Button Mode Cycling** (same as bedroom)
|
||||
2. **Button Actions** (same as bedroom, adjust auto-reset to 15 min)
|
||||
3. **Presence Mode Reset**:
|
||||
- Occupancy Sensors: `binary_sensor.living_room_occupancy`
|
||||
- Empty Delay: 5 minutes
|
||||
- AL Switch: `switch.adaptive_lighting_living_room`
|
||||
### UI Configuration Steps
|
||||
|
||||
**Step 1: Create Mode Selector**
|
||||
- Name: "Living Room Lighting Mode"
|
||||
- Entity ID: `input_select.living_room_lighting_mode`
|
||||
- Options: Adaptive, Theater, Party, Relaxing
|
||||
- Initial: Adaptive
|
||||
|
||||
**Step 2: Create Mode Application Automation**
|
||||
- Blueprint: Apply Lighting Mode Settings
|
||||
- Mode Input Select: `input_select.living_room_lighting_mode`
|
||||
- Default Mode: `Adaptive`
|
||||
- AL Switch: `switch.adaptive_lighting_living_room`
|
||||
- LED Entity: `number.living_room_switch_led_color_when_on` (if Inovelli)
|
||||
- Name: "Living Room: Apply Lighting Mode"
|
||||
|
||||
**Testing**:
|
||||
- [ ] Enter room → lights turn on (via separate occupancy automation)
|
||||
- [ ] Press config button → cycles through 4 modes
|
||||
- [ ] Set to Theater mode, leave room → after 5 min, resets to Adaptive
|
||||
- [ ] Manual boost → leave room → manual control clears
|
||||
**Weekend Mode**: Optional for living room - use if you want different behavior on weekends
|
||||
|
||||
## Example 3: Bathroom (Simple)
|
||||
### Testing
|
||||
|
||||
**Goal**: Always Adaptive, brightness boost only
|
||||
- [ ] Switch to Theater mode → lights dim for movie watching
|
||||
- [ ] Switch to Party mode → lights bright and dynamic
|
||||
- [ ] Switch to Adaptive → normal adaptive behavior
|
||||
- [ ] LED colors match modes (if Inovelli)
|
||||
|
||||
**Hardware**:
|
||||
- Inovelli Blue Dimmer: `bathroom_switch`
|
||||
- Lights: `light.bathroom_ceiling`, `light.bathroom_vanity`
|
||||
- Presence: `binary_sensor.bathroom_occupancy`
|
||||
## Example 3: Simple Bathroom
|
||||
|
||||
**Package File** (`packages/adaptive_lighting_bathroom.yaml`):
|
||||
**Goal**: Always adaptive, no mode switching needed
|
||||
|
||||
Copy from `adaptive_lighting_simple_template.yaml`
|
||||
- No modes (Adaptive only)
|
||||
- No weekend mode
|
||||
- Simple reset on presence end
|
||||
**Room Type**: Utility space with simple lighting needs
|
||||
|
||||
**Blueprint Automations**:
|
||||
### Adaptive Lighting Configuration
|
||||
|
||||
1. **Button Actions ONLY**:
|
||||
- Double-tap up: Boost brightness
|
||||
- Triple-tap down: Night light
|
||||
- Auto-reset: 10 minutes
|
||||
|
||||
2. **Presence Mode Reset**:
|
||||
- Reset manual control when empty 5 minutes
|
||||
- No mode reset (no input_select)
|
||||
|
||||
**Testing**:
|
||||
- [ ] Double-tap up → brightness boosts
|
||||
- [ ] Leave bathroom 5 min → manual control clears
|
||||
- [ ] Triple-tap down → night light mode
|
||||
- [ ] No config button action (not configured)
|
||||
|
||||
## Entity ID Quick Reference
|
||||
|
||||
### Finding Your Entities
|
||||
|
||||
**Inovelli Switch Entities** (via Zigbee2MQTT):
|
||||
```
|
||||
event.{device_name}_action # Button presses (event entity)
|
||||
number.{device_name}_led_color_when_on
|
||||
number.{device_name}_led_color_when_off
|
||||
number.{device_name}_led_intensity_when_on
|
||||
select.{device_name}_smart_bulb_mode
|
||||
select.{device_name}_button_delay
|
||||
```
|
||||
|
||||
**Adaptive Lighting Entities**:
|
||||
```
|
||||
switch.adaptive_lighting_{name}
|
||||
switch.adaptive_lighting_sleep_mode_{name}
|
||||
switch.adaptive_lighting_adapt_brightness_{name}
|
||||
switch.adaptive_lighting_adapt_color_{name}
|
||||
```
|
||||
|
||||
**Your Input Helpers**:
|
||||
```
|
||||
input_select.{room}_lighting_mode
|
||||
input_boolean.{room}_weekend_mode
|
||||
```
|
||||
|
||||
## Common Customizations
|
||||
|
||||
### Add a New Mode
|
||||
|
||||
1. Edit package file, add mode to `input_select`:
|
||||
```yaml
|
||||
input_select:
|
||||
bedroom_lighting_mode:
|
||||
options:
|
||||
- "Adaptive"
|
||||
- "Reading"
|
||||
- "NEW MODE HERE" # Add this
|
||||
adaptive_lighting:
|
||||
- name: bathroom
|
||||
lights:
|
||||
- light.bathroom_ceiling
|
||||
- light.bathroom_vanity
|
||||
interval: 60
|
||||
transition: 20
|
||||
```
|
||||
|
||||
2. Add color mapping to global package (or use existing color)
|
||||
### UI Configuration Steps
|
||||
|
||||
3. Add mode application to automation:
|
||||
```yaml
|
||||
- conditions: "{{ mode == 'NEW MODE HERE' }}"
|
||||
sequence:
|
||||
- service: adaptive_lighting.change_switch_settings
|
||||
data:
|
||||
min_brightness: 50
|
||||
max_brightness: 80
|
||||
# ... settings
|
||||
```
|
||||
**Step 1: Create Mode Selector (Minimal)**
|
||||
- Name: "Bathroom Lighting Mode"
|
||||
- Entity ID: `input_select.bathroom_lighting_mode`
|
||||
- Options: Adaptive, Sleep (for night use)
|
||||
- Initial: Adaptive
|
||||
|
||||
4. Reload YAML configuration
|
||||
**Step 2: Create Mode Application Automation**
|
||||
- Blueprint: Apply Lighting Mode Settings
|
||||
- Mode Input Select: `input_select.bathroom_lighting_mode`
|
||||
- AL Switch: `switch.adaptive_lighting_bathroom`
|
||||
- LED Entity: Leave empty (likely no Inovelli in bathroom)
|
||||
- Name: "Bathroom: Apply Lighting Mode"
|
||||
|
||||
### Change Auto-Reset Timeout
|
||||
**Weekend Mode**: Not needed for bathroom
|
||||
|
||||
Edit blueprint automation via UI:
|
||||
- Settings → Automations → [Your button action automation]
|
||||
- Click Edit
|
||||
- Adjust "Auto-Reset Timeout" slider
|
||||
### Alternative: No Mode Selector At All
|
||||
|
||||
If you want **only** adaptive lighting with no manual modes:
|
||||
- Skip creating mode selector
|
||||
- Skip creating mode application automation
|
||||
- Just use Adaptive Lighting integration directly
|
||||
- This is the simplest possible setup
|
||||
|
||||
### Testing
|
||||
|
||||
- [ ] Lights follow adaptive lighting automatically
|
||||
- [ ] Optional: Switch to Sleep mode for night bathroom trips
|
||||
- [ ] Adaptive mode uses AL defaults
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
After configuring any room, verify:
|
||||
|
||||
### Basic Functionality
|
||||
- [ ] All modes switch correctly via UI dropdown
|
||||
- [ ] AL settings apply as expected for each mode
|
||||
- [ ] Lights change brightness and color temperature appropriately
|
||||
- [ ] Mode changes are smooth (transitions work)
|
||||
|
||||
### LED Integration (If Inovelli Configured)
|
||||
- [ ] LED color updates match mode
|
||||
- [ ] LED colors are visible and distinct
|
||||
- [ ] LED updates happen immediately after mode change
|
||||
|
||||
### Weekend Mode (If Configured)
|
||||
- [ ] Weekend mode toggle works manually
|
||||
- [ ] Weekend mode enables automatically on Friday/Saturday
|
||||
- [ ] Weekend mode disables automatically on Sunday-Thursday
|
||||
- [ ] AL adjustments apply when weekend mode turns on
|
||||
- [ ] AL settings reset when weekend mode turns off
|
||||
|
||||
### Home Assistant Restart
|
||||
- [ ] Restart Home Assistant
|
||||
- [ ] Verify mode settings persist and apply on startup
|
||||
- [ ] Verify weekend mode settings persist and apply on startup
|
||||
|
||||
### Error Checking
|
||||
- [ ] No errors in Home Assistant logs (Settings → System → Logs)
|
||||
- [ ] Automation traces show successful execution (Settings → Automations → [automation] → Traces)
|
||||
|
||||
## Customization
|
||||
|
||||
### Add Custom Modes to a Room
|
||||
|
||||
Want to add "Reading" mode to your bedroom?
|
||||
|
||||
**Step 1**: Create the mode settings (see [ADDING_MODES.md](ADDING_MODES.md))
|
||||
|
||||
**Step 2**: Edit your room's mode selector helper
|
||||
- Settings → Devices & Services → Helpers
|
||||
- Find your room's dropdown (e.g., `input_select.master_bedroom_lighting_mode`)
|
||||
- Click **Edit**
|
||||
- Add "Reading" to options list
|
||||
- Save
|
||||
|
||||
### Disable Weekend Mode
|
||||
**Step 3**: Test
|
||||
- Switch to Reading mode via UI
|
||||
- Verify it works without any blueprint changes!
|
||||
|
||||
Comment out weekend mode automations in package file:
|
||||
```yaml
|
||||
# - id: bedroom_weekend_mode_auto_enable
|
||||
# alias: "Bedroom: Enable Weekend Mode Friday/Saturday"
|
||||
# # ... entire automation
|
||||
```
|
||||
### Change Weekend Mode Times
|
||||
|
||||
Reload YAML configuration.
|
||||
**Edit the automation**:
|
||||
- Settings → Automations & Scenes
|
||||
- Find "{Room}: Weekend Mode Apply Settings"
|
||||
- Click **Edit**
|
||||
- Adjust sunrise time, sunset time, or max brightness
|
||||
- Save
|
||||
|
||||
Changes apply immediately (no restart needed).
|
||||
|
||||
### Remove Weekend Mode
|
||||
|
||||
If you no longer want weekend mode:
|
||||
|
||||
**Step 1**: Disable automations
|
||||
- Settings → Automations & Scenes
|
||||
- Find weekend mode automations
|
||||
- Toggle them OFF (or delete them)
|
||||
|
||||
**Step 2**: Delete helpers (optional)
|
||||
- Settings → Devices & Services → Helpers
|
||||
- Find weekend mode boolean
|
||||
- Delete
|
||||
|
||||
### Use Scene-Based Modes
|
||||
|
||||
Want a mode that activates a complex scene?
|
||||
|
||||
See [ADDING_MODES.md - Advanced Examples](ADDING_MODES.md#advanced-examples) for scene and script-based mode creation.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Mode Doesn't Change Lights
|
||||
|
||||
**Symptom**: Selected mode but lights stayed the same
|
||||
|
||||
**Solutions**:
|
||||
1. Check automation is enabled: Settings → Automations → "{Room}: Apply Lighting Mode"
|
||||
2. View automation trace: Click automation → Traces tab
|
||||
3. Verify AL switch entity ID is correct in automation config
|
||||
4. Verify mode selector entity ID matches automation config
|
||||
5. Check mode settings entity exists: Developer Tools → States → `input_text.adaptive_lighting_settings_{mode}`
|
||||
|
||||
### LED Doesn't Change Color
|
||||
|
||||
**Symptom**: Mode changes work but LED stays same color
|
||||
|
||||
**Solutions**:
|
||||
1. Verify LED entity configured in automation (not left empty)
|
||||
2. Check LED entity ID is correct (should be `number.{device}_led_color_when_on`)
|
||||
3. Test LED manually: Developer Tools → Services → `number.set_value`
|
||||
4. Verify Inovelli switch firmware is up to date
|
||||
|
||||
### Weekend Mode Doesn't Apply
|
||||
|
||||
**Symptom**: Boolean toggles but AL settings don't change
|
||||
|
||||
**Solutions**:
|
||||
1. Check "Weekend Mode Apply Settings" automation is enabled
|
||||
2. View automation trace to see what happened
|
||||
3. Verify AL switch entity ID is correct
|
||||
4. Manually trigger automation: Developer Tools → Services → `automation.trigger`
|
||||
5. Check for errors in logs
|
||||
|
||||
### Modes Work But Automation Triggers Too Often
|
||||
|
||||
**Symptom**: Automation runs many times for single mode change
|
||||
|
||||
**Solutions**:
|
||||
- This is expected behavior - automation uses `mode: restart`
|
||||
- Check automation traces - should see restart behavior
|
||||
- If causing issues, automation is working as designed (debounces rapid changes)
|
||||
- No action needed unless you see actual problems
|
||||
|
||||
### Can't Find Mode Selector in UI
|
||||
|
||||
**Symptom**: Created helper but can't find it on dashboard
|
||||
|
||||
**Solutions**:
|
||||
1. Check entity was created: Settings → Devices & Services → Helpers
|
||||
2. Add to dashboard manually: Edit Dashboard → Add Card → Entities → Select your input_select
|
||||
3. Or use in automations/scripts without dashboard visibility
|
||||
4. Verify entity ID in Developer Tools → States
|
||||
|
||||
## Next Steps
|
||||
|
||||
After configuring your first room:
|
||||
|
||||
1. **Add more rooms**: Repeat the basic workflow for each room
|
||||
2. **Customize modes**: See [ADDING_MODES.md](ADDING_MODES.md) to create custom modes
|
||||
3. **Add Inovelli integration**: Use optional blueprints for button control
|
||||
4. **Add presence control**: Use presence_mode_reset blueprint for occupancy-based automation
|
||||
|
||||
For more information:
|
||||
- [ADDING_MODES.md](ADDING_MODES.md) - Custom mode creation tutorial
|
||||
- [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) - Global package installation
|
||||
- [README.md](README.md) - Main documentation
|
||||
- [Adaptive Lighting Docs](https://github.com/basnijholt/adaptive-lighting) - AL integration reference
|
||||
|
||||
Reference in New Issue
Block a user