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

Add custom mode tutorial and update docs for pure blueprint architecture

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

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

605
ROOM_CONFIGURATION_GUIDE.md
View File

@@ -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**:
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`
- Mode Input Select: `input_select.living_room_lighting_mode`
- Default Mode: `Adaptive`
**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
## Example 3: Bathroom (Simple)
**Goal**: Always Adaptive, brightness boost only
**Hardware**:
- Inovelli Blue Dimmer: `bathroom_switch`
- Lights: `light.bathroom_ceiling`, `light.bathroom_vanity`
- Presence: `binary_sensor.bathroom_occupancy`
**Package File** (`packages/adaptive_lighting_bathroom.yaml`):
Copy from `adaptive_lighting_simple_template.yaml`
- No modes (Adaptive only)
- No weekend mode
- Simple reset on presence end
**Blueprint Automations**:
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: living_room
lights:
- light.living_room_ceiling
- light.living_room_lamp_1
- light.living_room_lamp_2
interval: 90
transition: 30
```
2. Add color mapping to global package (or use existing color)
### 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`
- 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"
**Weekend Mode**: Optional for living room - use if you want different behavior on weekends
### Testing
- [ ] 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)
## Example 3: Simple Bathroom
**Goal**: Always adaptive, no mode switching needed
**Room Type**: Utility space with simple lighting needs
### Adaptive Lighting Configuration
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
adaptive_lighting:
- name: bathroom
lights:
- light.bathroom_ceiling
- light.bathroom_vanity
interval: 60
transition: 20
```
4. Reload YAML configuration
### UI Configuration Steps
### Change Auto-Reset Timeout
**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
Edit blueprint automation via UI:
- Settings → Automations → [Your button action automation]
- Click Edit
- Adjust "Auto-Reset Timeout" slider
**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"
**Weekend Mode**: Not needed for bathroom
### 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