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
• Quick Start: Adding "Reading" Mode
• Method 1: UI-Created Modes (Recommended)
• Method 2: Package-Defined Modes
• Schema Reference
• Behavior Types
• Manual Control
• Advanced Examples
• Troubleshooting
• 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:

   {"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:

{"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:

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:

{
  "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 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{"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:

{"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:

{"behavior":"adaptive_lighting","manual_control":true,"led_color":212,"al_config":{}}

Example 4: "Sunrise Alarm" Mode

Gradual brightness increase with warm colors:

{"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:

{"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:

// 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:

{"behavior":"adaptive_lighting","min_brightness":20,"max_brightness":40}

Correct:

{"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:

- conditions: "{{ behavior == 'webhook' }}"
  sequence:
    - service: rest_command.trigger_webhook
      data:
        url: "{{ settings.webhook_url }}"

3. Create mode with webhook behavior:

{"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 - Setting up rooms
• Package Setup Guide - Installing global package
• README - Main documentation
• Adaptive Lighting Docs - AL integration reference