home-assistant-blueprints/ADDING_MODES.md

# 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