# Room Configuration Guide

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 mode control with weekend mode, optional Inovelli integration

**Room Type**: Private bedroom with comprehensive lighting control

### Adaptive Lighting Configuration

In `configuration.yaml` (if not already done):

```yaml
adaptive_lighting:
  - name: master_bedroom
    lights:
      - 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
```

Restart Home Assistant after editing configuration.yaml.

### UI Configuration Steps

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

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

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

- [ ] 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

## Example 2: Living Room

**Goal**: Entertainment modes (Theater, Party), standard adaptive lighting

**Room Type**: Common area with social and entertainment use

### Adaptive Lighting Configuration

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

### 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

```yaml
adaptive_lighting:
  - name: bathroom
    lights:
      - light.bathroom_ceiling
      - light.bathroom_vanity
    interval: 60
    transition: 20
```

### UI Configuration Steps

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

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

**Step 3**: Test
- Switch to Reading mode via UI
- Verify it works without any blueprint changes!

### Change Weekend Mode Times

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