Add comprehensive documentation and testing tools

- Update README with complete setup guide and all blueprint URLs - Add PACKAGE_SETUP_GUIDE with step-by-step setup instructions - Add ROOM_CONFIGURATION_GUIDE with bedroom, living room, and bathroom examples - Add HARDWARE_TESTING_CHECKLIST for validating with real Inovelli switches - Add CHANGELOG documenting v1.0.0 release - Add validation script for automated YAML testing - Add test configuration example for testing without hardware
2025-12-21 14:30:53 -08:00
parent 5eec41a43c
commit a5a6b9d4b6
7 changed files with 722 additions and 18 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to the Adaptive Lighting Mode System will be documented in
+this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [1.0.0] - 2025-12-20
+
+### Added
+
+**Blueprints**:
+- `inovelli_mode_cycling.yaml` - Config button cycles through lighting modes
+  with LED feedback
+- `inovelli_button_actions.yaml` - Multi-tap brightness controls with
+  auto-reset
+- `presence_mode_reset.yaml` - Auto-reset modes and manual control when room
+  empty
+
+**Package Templates**:
+- `adaptive_lighting_global.yaml` - Shared mode definitions and color mappings
+- `adaptive_lighting_bedroom_template.yaml` - Complete bedroom example with 5
+  modes
+- `adaptive_lighting_living_room_template.yaml` - Living room example with
+  entertainment modes
+- `adaptive_lighting_simple_template.yaml` - Minimal template for simple rooms
+
+**Documentation**:
+- `PACKAGE_SETUP_GUIDE.md` - Setup instructions and version control guide
+- `ROOM_CONFIGURATION_GUIDE.md` - Room-by-room configuration examples
+- `HARDWARE_TESTING_CHECKLIST.md` - Comprehensive testing checklist
+- Updated `README.md` with system overview and quick start
+
+**Features**:
+- Room-specific mode definitions (Adaptive, Reading, Theater, Sleep, etc.)
+- Visual LED feedback using ROYGBIV color scheme
+- Weekend mode with automatic sunrise/sunset adjustments
+- Multi-tap button actions (boost, max, night light)
+- Presence-based auto-reset
+- Version-controlled package-based configuration
+
+### Technical Details
+
+- Zigbee2MQTT integration for Inovelli Blue VZM31-SN switches
+- Home Assistant Adaptive Lighting integration required
+- Package-based architecture for easy version control
+- Template-driven room setup for scalability
+
+### Known Limitations
+
+- Zigbee2MQTT only (Z-Wave JS requires different MQTT topics)
+- Settings from `adaptive_lighting.change_switch_settings` reset on HA restart
+- Requires manual Inovelli switch configuration (Smart Bulb Mode, buttonDelay)
--- a/HARDWARE_TESTING_CHECKLIST.md
+++ b/HARDWARE_TESTING_CHECKLIST.md
@@ -0,0 +1,110 @@
+# Hardware Testing Checklist
+
+## Prerequisites
+
+- [ ] Inovelli Blue Dimmer VZM31-SN paired with Zigbee2MQTT
+- [ ] Switch in Smart Bulb Mode (select.xxx_smart_bulb_mode = "Smart Bulb
+  Mode")
+- [ ] buttonDelay set to 500ms or 700ms (select.xxx_button_delay)
+- [ ] Smart bulbs powered and responsive
+- [ ] Adaptive Lighting integration installed and configured
+- [ ] All packages and blueprints loaded
+
+## Switch Configuration Tests
+
+- [ ] Smart Bulb Mode enabled: Load always powered
+- [ ] LED bar displays color correctly
+- [ ] LED intensity acceptable (adjust if too bright/dim)
+- [ ] Button presses detected: event.xxx_action updates
+- [ ] Single tap: Shows "up_single" or "down_single"
+- [ ] Double tap: Shows "up_double" or "down_double" reliably
+- [ ] Triple tap: Shows "up_triple" or "down_triple" reliably
+- [ ] Config button: Shows "config_single"
+
+## Mode Cycling Tests
+
+- [ ] Config button press triggers automation
+- [ ] Mode cycles through all available modes
+- [ ] Mode cycles back to first after last mode
+- [ ] input_select updates in UI
+- [ ] LED color changes to match mode
+- [ ] LED flash pulse visible (3 seconds)
+- [ ] Colors distinguishable for each mode
+- [ ] Cycle works from any starting mode
+
+## Mode Application Tests
+
+For each mode:
+- [ ] Adaptive: AL settings reset to configuration defaults
+- [ ] Reading: Brightness increases, color cools
+- [ ] Theater: Brightness decreases, color warms
+- [ ] Sleep: Very dim, red/amber color
+- [ ] Manual Override: AL paused, manual control enabled
+
+## Button Action Tests
+
+- [ ] Double tap up: Brightness boosts +50%
+- [ ] Double tap up: Color temperature increases +1000K
+- [ ] Double tap down: Returns to AL control immediately
+- [ ] Triple tap up: Sets 100% brightness, 4000K (neutral)
+- [ ] Triple tap down: Sets 5% brightness, warm red
+- [ ] Auto-reset: Returns to AL after configured timeout
+- [ ] Auto-reset: Works after boost action
+- [ ] Auto-reset: Works after max brightness
+- [ ] Auto-reset: Works after night light
+
+## Weekend Mode Tests (if configured)
+
+- [ ] Enables automatically Friday 10pm
+- [ ] Disables automatically Sunday 10pm
+- [ ] Sunrise time shifts when enabled
+- [ ] Max brightness reduces when enabled
+- [ ] Settings restore when disabled
+- [ ] Triple-tap toggle works (if configured)
+- [ ] LED flash confirms toggle
+
+## Presence Integration Tests (if configured)
+
+- [ ] Presence sensor triggers correctly
+- [ ] Lights turn on when occupied
+- [ ] Lights stay on while occupied
+- [ ] Manual control resets after room empty
+- [ ] Mode resets after room empty (if configured)
+- [ ] Delay timing is appropriate
+- [ ] Works with multiple sensors (OR logic)
+
+## Edge Cases and Failure Modes
+
+- [ ] Rapid button presses don't cause errors
+- [ ] Mode change while lights off doesn't error
+- [ ] Switching modes rapidly doesn't break AL
+- [ ] Zigbee network congestion doesn't cause issues
+- [ ] Home Assistant restart preserves mode
+- [ ] AL switch off doesn't break mode system
+- [ ] Invalid mode name doesn't crash automation
+- [ ] Missing entity gracefully fails
+
+## Performance Tests
+
+- [ ] Mode change response < 1 second
+- [ ] LED update response < 1 second
+- [ ] Button action response < 1 second
+- [ ] AL adaptation smooth (no flicker)
+- [ ] No automation trace errors
+- [ ] No excessive log warnings
+
+## Multi-Room Tests
+
+- [ ] Multiple rooms work independently
+- [ ] Mode cycling doesn't affect other rooms
+- [ ] LED colors consistent across rooms
+- [ ] Performance acceptable with many rooms
+- [ ] Global package shared correctly
+
+## Documentation Accuracy
+
+- [ ] All entity IDs in examples are correct format
+- [ ] Zigbee2MQTT topics match actual topics
+- [ ] Service calls work as documented
+- [ ] Examples produce expected behavior
+- [ ] Troubleshooting guide solves real issues
--- a/PACKAGE_SETUP_GUIDE.md
+++ b/PACKAGE_SETUP_GUIDE.md
@@ -0,0 +1,220 @@
+# Package Setup Guide
+
+## Overview
+
+This guide explains how to set up Home Assistant packages for the Adaptive
+Lighting Mode System and configure version control.
+
+## 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.
+
+**Benefits**:
+- Organize configuration by room or feature
+- Version control specific areas independently
+- Easier to 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
+
+## Step 1: Enable Packages in Home Assistant
+
+**1.1 Edit your `configuration.yaml`**
+
+Add this line to the top of your `configuration.yaml`:
+
+```yaml
+homeassistant:
+  packages: !include_dir_named packages/
+```
+
+**1.2 Create the packages directory**
+
+SSH into your Home Assistant instance or use File Editor add-on:
+
+```bash
+cd /config
+mkdir packages
+```
+
+**1.3 Restart Home Assistant**
+
+Settings → System → Restart Home Assistant
+
+## Step 2: Install Global Definitions
+
+**2.1 Copy the global package**
+
+Download or copy `packages/adaptive_lighting_global.yaml` from this repository
+to your `/config/packages/` directory.
+
+**2.2 Reload YAML configuration**
+
+Developer Tools → YAML → Reload all YAML configuration
+
+**2.3 Verify helpers exist**
+
+Settings → Devices & Services → Helpers
+
+You should see:
+- `input_text.adaptive_lighting_mode_colors`
+- `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
+
+## Step 3: Import Blueprints
+
+**3.1 Import via UI**
+
+Settings → Automations & Scenes → Blueprints → Import Blueprint
+
+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
+```
+
+**3.2 Verify blueprints imported**
+
+Settings → Automations & Scenes → Blueprints
+
+You should see all three blueprints listed.
+
+## Step 4: Configure Your First Room
+
+**4.1 Choose a template**
+
+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
+```
+
+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
+
+**4.3 Reload configuration**
+
+Developer Tools → YAML → Reload all YAML configuration
+
+**4.4 Create blueprint automations**
+
+Settings → Automations & Scenes → Create Automation → Use Blueprint
+
+Create automations for:
+1. Inovelli Mode Cycling (config button)
+2. Inovelli Button Actions (multi-tap)
+3. Presence Mode Reset (if you have occupancy sensors)
+
+## Step 5: Version Control Setup (Optional)
+
+**5.1 Initialize git repository**
+
+```bash
+cd /config
+git init
+```
+
+**5.2 Create .gitignore**
+
+```bash
+cat > .gitignore << 'EOF'
+# Secrets and sensitive data
+secrets.yaml
+*.db
+*.db-shm
+*.db-wal
+*.log
+
+# Generated files
+*.pyc
+__pycache__/
+.storage/
+.cloud/
+.google.token
+
+# Add-on data
+.ssh/
+.vscode/
+
+# Keep these version controlled:
+# - packages/
+# - automations.yaml
+# - configuration.yaml
+# - blueprints/
+EOF
+```
+
+**5.3 Commit initial setup**
+
+```bash
+git add packages/ automations.yaml configuration.yaml
+git commit -m "Initial adaptive lighting mode system setup"
+```
+
+**5.4 Add remote (optional)**
+
+```bash
+git remote add origin your-git-repo-url
+git push -u origin main
+```
+
+## Troubleshooting
+
+### Packages not loading
+
+**Symptom**: Helpers don't appear after reloading
+
+**Solutions**:
+- Check `configuration.yaml` has packages line
+- Verify packages directory exists at `/config/packages/`
+- Check YAML syntax: `yamllint /config/packages/*.yaml`
+- Look for errors in Settings → System → Logs
+
+### Entity IDs don't match
+
+**Symptom**: Automations fail because entities not found
+
+**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
+
+### Blueprints not working
+
+**Symptom**: Automation from blueprint doesn't trigger
+
+**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)
+
+## Next Steps
+
+See [ROOM_CONFIGURATION_GUIDE.md](ROOM_CONFIGURATION_GUIDE.md) for detailed
+room setup examples.
--- a/README.md
+++ b/README.md
@@ -2,49 +2,68 @@

 ## 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 for Inovelli Blue Dimmer
+Switches with Adaptive Lighting integration.

 ### Features

- **Room-specific modes**: Define custom lighting modes per room (Reading, Theater, Sleep, etc.)
+- **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
+- **Adaptive Lighting integration**: Dynamic brightness and color following sun
+  position
 - **Version controlled**: All configuration in git-trackable package files

 ### System Components

 **Blueprints** (Reusable):
 - `inovelli_mode_cycling.yaml` - Config button cycles modes with LED feedback
- `inovelli_button_actions.yaml` - Multi-tap brightness controls (coming soon)
- `presence_mode_reset.yaml` - Auto-reset on room exit (coming soon)
+- `inovelli_button_actions.yaml` - Multi-tap brightness controls
+- `presence_mode_reset.yaml` - Auto-reset on room exit

 **Packages** (Templates):
 - `adaptive_lighting_global.yaml` - Shared mode definitions and colors
- `adaptive_lighting_bedroom_template.yaml` - Complete bedroom example (coming soon)
- `adaptive_lighting_living_room_template.yaml` - Living room example (coming soon)
+- `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

-### Quick Start
+### Setup Guide

-See [PACKAGE_SETUP_GUIDE.md](PACKAGE_SETUP_GUIDE.md) for detailed setup instructions.
+**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

-**Prerequisites**:
- Home Assistant with Adaptive Lighting integration installed
- Inovelli Blue Dimmer Switches (VZM31-SN) via Zigbee2MQTT
- Switches configured in Smart Bulb Mode
+**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

-**Installation**:
-1. Enable packages in `configuration.yaml`
-2. Copy `packages/adaptive_lighting_global.yaml` to your `config/packages/` directory
-3. Import blueprints via Home Assistant UI
-4. Create automations from blueprints for each room
+**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

 ### Import URLs

 **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
 ```

 ---
--- a/ROOM_CONFIGURATION_GUIDE.md
+++ b/ROOM_CONFIGURATION_GUIDE.md
@@ -0,0 +1,200 @@
+# Room Configuration Guide
+
+Complete examples of configuring different room types with the Adaptive
+Lighting Mode System.
+
+## Example 1: Master Bedroom
+
+**Goal**: Full control with optional AL, reading/sleep modes, weekend mode
+
+**Hardware**:
+- Inovelli Blue Dimmer: `bedroom_switch` (Zigbee2MQTT name)
+- Lights: `light.bedroom_ceiling`, `light.bedroom_lamp_1`,
+  `light.bedroom_lamp_2`
+- No presence sensor (privacy)
+
+**Adaptive Lighting Configuration** (in `configuration.yaml`):
+```yaml
+adaptive_lighting:
+  - name: bedroom
+    lights:
+      - light.bedroom_ceiling
+      - light.bedroom_lamp_1
+      - light.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`):
+
+Copy from `adaptive_lighting_bedroom_template.yaml`, customize:
+- Modes: Adaptive, Reading, Relaxing, Sleep, Manual Override
+- Weekend mode enabled
+- Default mode: Adaptive
+
+**Blueprint Automations** (create via UI):
+
+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`
+
+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
+
+**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
+
+## Example 2: Living Room (Common Area)
+
+**Goal**: Entertainment modes (Theater, Party), presence control
+
+**Hardware**:
+- Inovelli Blue Dimmer: `living_room_switch`
+- Lights: `light.living_room_ceiling`, `light.living_room_lamp_1`
+- Presence: `binary_sensor.living_room_occupancy`
+
+**Package File** (`packages/adaptive_lighting_living_room.yaml`):
+
+Copy from `adaptive_lighting_living_room_template.yaml`
+- Modes: Adaptive, Theater, Party, Reading
+- Auto-reset mode to Adaptive when lights turn off
+
+**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
+```
+
+2. Add color mapping to global package (or use existing color)
+
+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
+```
+
+4. Reload YAML configuration
+
+### Change Auto-Reset Timeout
+
+Edit blueprint automation via UI:
+- Settings → Automations → [Your button action automation]
+- Click Edit
+- Adjust "Auto-Reset Timeout" slider
+- Save
+
+### Disable Weekend Mode
+
+Comment out weekend mode automations in package file:
+```yaml
+#  - id: bedroom_weekend_mode_auto_enable
+#    alias: "Bedroom: Enable Weekend Mode Friday/Saturday"
+#    # ... entire automation
+```
+
+Reload YAML configuration.
--- a/examples/test_room_config.yaml
+++ b/examples/test_room_config.yaml
@@ -0,0 +1,66 @@
+---
+# examples/test_room_config.yaml
+#
+# Test configuration for validating the Adaptive Lighting Mode System
+# without real Inovelli hardware or Adaptive Lighting integration.
+#
+# This uses template sensors and manual input helpers to simulate the system.
+
+input_select:
+  test_room_lighting_mode:
+    name: "Test Room Lighting Mode"
+    options:
+      - "Adaptive"
+      - "Reading"
+      - "Sleep"
+    initial: "Adaptive"
+
+sensor:
+  - platform: template
+    sensors:
+      test_switch_action:
+        friendly_name: "Test Switch Action"
+        value_template: "{{ states('input_text.test_switch_action_sim') }}"
+
+input_text:
+  test_switch_action_sim:
+    name: "Simulate Switch Action"
+    initial: "none"
+
+input_number:
+  test_led_color:
+    name: "Test LED Color"
+    min: 0
+    max: 255
+    step: 1
+    initial: 170
+
+# Automation to test mode cycling logic
+automation:
+  - id: test_mode_cycling
+    alias: "Test: Mode Cycling"
+    trigger:
+      - platform: state
+        entity_id: input_text.test_switch_action_sim
+        to: "config_single"
+    variables:
+      mode_select: input_select.test_room_lighting_mode
+      current_mode: "{{ states(mode_select) }}"
+      available_modes: "{{ state_attr(mode_select, 'options') }}"
+      current_index: "{{ available_modes.index(current_mode) }}"
+      next_index: "{{ (current_index + 1) % (available_modes | length) }}"
+      next_mode: "{{ available_modes[next_index] }}"
+      mode_colors: >-
+        {{ states('input_text.adaptive_lighting_mode_colors') | from_json }}
+      next_color: "{{ mode_colors.get(next_mode, 170) }}"
+    action:
+      - service: input_select.select_option
+        target:
+          entity_id: input_select.test_room_lighting_mode
+        data:
+          option: "{{ next_mode }}"
+      - service: input_number.set_value
+        target:
+          entity_id: input_number.test_led_color
+        data:
+          value: "{{ next_color }}"
--- a/scripts/validate_yaml.sh
+++ b/scripts/validate_yaml.sh
@@ -0,0 +1,36 @@
+#!/bin/bash
+# scripts/validate_yaml.sh
+#
+# Validates YAML syntax for all Adaptive Lighting system files
+
+set -e
+
+echo "Validating Adaptive Lighting Mode System YAML files..."
+echo "========================================================"
+
+# Check if yamllint is installed
+if ! command -v yamllint &> /dev/null; then
+    echo "ERROR: yamllint not found."
+    echo "Install with: pip install yamllint"
+    echo "Or run with: nix run nixpkgs#yamllint -- <files>"
+    exit 1
+fi
+
+# Validate packages
+echo ""
+echo "Validating packages..."
+for file in packages/*.yaml; do
+    echo "  - $file"
+    yamllint -d '{extends: default, rules: {line-length: {max: 120}}}' "$file"
+done
+
+# Validate blueprints
+echo ""
+echo "Validating blueprints..."
+for file in blueprints/automation/*.yaml; do
+    echo "  - $file"
+    yamllint -d '{extends: default, rules: {line-length: {max: 120}}}' "$file"
+done
+
+echo ""
+echo "✓ All YAML files are valid!"