adaptive-lighting/docs/configuration.md

icon
lucide/settings

Configuration

Adaptive Lighting supports configuration through both YAML and the Home Assistant UI, with identical option names in both methods.

Basic Configuration

The simplest setup uses the Home Assistant UI. Go to Settings → Devices & Services → Add Integration → Adaptive Lighting. No adaptive_lighting: entry is needed in configuration.yaml.

YAML Configuration

Alternatively, you can specify lights and options in configuration.yaml:

adaptive_lighting:
  - name: "Living Room"
    lights:
      - light.living_room_ceiling
      - light.living_room_lamp

All Options

All configuration options are listed below with their default values. These options work identically in both YAML and the UI.

Variable name	Description	Default	Type
lights	List of light entity_ids to be controlled (may be empty). 🌟	[]	list of entity_ids
interval	Frequency to adapt the lights, in seconds. 🔄	90	int > 0
transition	Duration of transition when lights change, in seconds. 🕑	45	float 0-6553
initial_transition	Duration of the first transition when lights turn from off to on in seconds. ⏲️	1	float 0-6553
min_brightness	Minimum brightness percentage. 💡	1	int 1-100
max_brightness	Maximum brightness percentage. 💡	100	int 1-100
min_color_temp	Warmest color temperature in Kelvin. 🔥	2000	int 1000-10000
max_color_temp	Coldest color temperature in Kelvin. ❄️	5500	int 1000-10000
prefer_rgb_color	Whether to prefer RGB color adjustment over light color temperature when possible. 🌈	False	bool
sleep_brightness	Brightness percentage of lights in sleep mode. 😴	1	int 1-100
sleep_rgb_or_color_temp	Use either "rgb_color" or "color_temp" in sleep mode. 🌙	color_temp	one of ['color_temp', 'rgb_color']
sleep_color_temp	Color temperature in sleep mode (used when sleep_rgb_or_color_temp is color_temp) in Kelvin. 😴	1000	int 1000-10000
sleep_rgb_color	RGB color in sleep mode (used when sleep_rgb_or_color_temp is "rgb_color"). 🌈	[255, 56, 0]	RGB color
sleep_transition	Duration of transition when "sleep mode" is toggled in seconds. 😴	1	float 0-6553
transition_until_sleep	When enabled, Adaptive Lighting will treat sleep settings as the minimum, transitioning to these values after sunset. 🌙	False	bool
sunrise_time	Set a fixed time (HH:MM:SS) for sunrise. 🌅	None	str
min_sunrise_time	Set the earliest virtual sunrise time (HH:MM:SS), allowing for later sunrises. 🌅	None	str
max_sunrise_time	Set the latest virtual sunrise time (HH:MM:SS), allowing for earlier sunrises. 🌅	None	str
sunrise_offset	Adjust sunrise time with a positive or negative offset in seconds. ⏰	0	int
sunset_time	Set a fixed time (HH:MM:SS) for sunset. 🌇	None	str
min_sunset_time	Set the earliest virtual sunset time (HH:MM:SS), allowing for later sunsets. 🌇	None	str
max_sunset_time	Set the latest virtual sunset time (HH:MM:SS), allowing for earlier sunsets. 🌇	None	str
sunset_offset	Adjust sunset time with a positive or negative offset in seconds. ⏰	0	int
brightness_mode	Brightness mode to use. Possible values are default, linear, and tanh (uses brightness_mode_time_dark and brightness_mode_time_light). 📈	default	one of ['default', 'linear', 'tanh']
brightness_mode_time_dark	(Ignored if brightness_mode='default') The duration in seconds to ramp up/down the brightness before/after sunrise/sunset. 📈📉	900	int
brightness_mode_time_light	(Ignored if brightness_mode='default') The duration in seconds to ramp up/down the brightness after/before sunrise/sunset. 📈📉.	3600	int
color_temp_plateau_morning	The duration in seconds before solar noon during which the color temperature stays at max_color_temp instead of only reaching it at noon. The ramp from min_color_temp at sunrise to max_color_temp is compressed accordingly. 0 keeps the default curve. Only affects the morning. 🌤️	0	int 0-43200
color_temp_plateau_evening	The duration in seconds after solar noon during which the color temperature stays at max_color_temp before ramping down to min_color_temp at sunset. 0 keeps the default curve. Only affects the evening. 🌇	0	int 0-43200
color_temp_fixed_plateau_end	Local time (HH:MM:SS, 12:00 or later) until which the color temperature stays at max_color_temp in the evening, every day of the year, instead of following the sun. Needs color_temp_fixed_descent_end; unset keeps the default curve. Only affects the color temperature. 🌙	None	str (HH:MM:SS)
color_temp_fixed_descent_end	Local time (HH:MM:SS) at which the color temperature has smoothly descended from max_color_temp to min_color_temp, starting at color_temp_fixed_plateau_end. May be after midnight, at most 12 hours later. Needs color_temp_fixed_plateau_end; unset keeps the default curve. 🌙	None	str (HH:MM:SS)
color_temp_fixed_plateau_kelvin	Evening temperature in Kelvin (between min_color_temp and max_color_temp), reached and held for the last hour before color_temp_fixed_plateau_end; the daytime maximum is not capped. Needs both fixed times and is ignored when the plateau end is less than 1 h after solar noon. Applied in steps of 5 K. Unset holds max_color_temp. 🌙	None	str
take_over_control	Pause adaptation of individual lights and hand over (manual) control to other sources that issue light.turn_on calls for lights that are on. 🔒	True	bool
take_over_control_mode	The adaptation pausing mode when other sources change brightness and/or color of lights. pause_all always pauses both brightness and color adaptation. pause_changed pauses the adaptation of only the changed attributes and continues adapting unchanged attributes, e.g., continues color adaptation when only brightness was changed.	pause_all	one of ['pause_all', 'pause_changed']
detect_non_ha_changes	Detects and halts adaptations for non-light.turn_on state changes. Needs take_over_control enabled. 🕵️ Caution: ⚠️ Some lights might falsely indicate an 'on' state, which could result in lights turning on unexpectedly. Note that this calls homeassistant.update_entity every interval! Disable this feature if you encounter such issues.	False	bool
autoreset_control_seconds	Automatically reset the manual control after a number of seconds. Set to 0 to disable. ⏲️	0	int 0-31536000
only_once	Adapt lights only when they are turned on (true) or keep adapting them (false). 🔄	False	bool
adapt_only_on_bare_turn_on	When turning lights on initially. If set to true, AL adapts only if light.turn_on is invoked without specifying color or brightness. ❌🌈 This e.g., prevents adaptation when activating a scene and marks the light as manually controlled. If false, AL adapts regardless of the presence of color or brightness in the initial service_data. Needs take_over_control enabled. 🕵️	False	bool
manual_control_on_external_turn_on	Treat turn-ons without a matching Home Assistant light.turn_on context as manual control. Normal manual-control resets apply. Still allows detect_non_ha_changes for already-on lights. Needs take_over_control enabled. 🕵️	False	bool
reset_manual_control_on_sleep_mode_change	Reset manual control when the sleep mode switch is toggled. Set to false to preserve manual control across sleep mode changes. 😴	True	bool
separate_turn_on_commands	Use separate light.turn_on calls for color and brightness, needed for some light types. 🔀	False	bool
send_split_delay	Delay (ms) between separate_turn_on_commands for lights that don't support simultaneous brightness and color setting. ⏲️	0	int 0-10000
adapt_delay	Wait time (seconds) between light turn on and Adaptive Lighting applying changes. Might help to avoid flickering. ⏲️	0	float > 0
skip_redundant_commands	Skip sending adaptation commands whose target state already equals the light's known state. Minimizes network traffic and improves the adaptation responsivity in some situations. 📉Disable if physical light states get out of sync with HA's recorded state.	False	bool
intercept	Intercept and adapt light.turn_on calls to enabling instantaneous color and brightness adaptation. 🏎️ Disable for lights that do not support light.turn_on with color and brightness.	True	bool
multi_light_intercept	Intercept and adapt light.turn_on calls that target multiple lights. ➗⚠️ This might result in splitting up a single light.turn_on call into multiple calls, e.g., when lights are in different switches. Requires intercept to be enabled.	True	bool
include_config_in_attributes	Show all options as attributes on the switch in Home Assistant when set to true. 📝	False	bool
expand_light_groups	Expand light groups to their members (true, default). Set false to send commands to the group and track manual control for the group. Explicit member targets in services stay individual targets.	True	bool

Full Configuration Example

Full example:

# Example configuration.yaml entry
adaptive_lighting:
- name: "default"
  lights: []
  prefer_rgb_color: false
  transition: 45
  initial_transition: 1
  interval: 90
  min_brightness: 1
  max_brightness: 100
  min_color_temp: 2000
  max_color_temp: 5500
  sleep_brightness: 1
  sleep_color_temp: 1000
  sunrise_time: "08:00:00"  # override the sunrise time
  sunrise_offset:
  sunset_time:
  sunset_offset: 1800  # in seconds or '00:30:00'
  take_over_control: true
  detect_non_ha_changes: false
  only_once: false

Multiple Configurations

You can create multiple Adaptive Lighting configurations for different areas or use cases:

adaptive_lighting:
  - name: "Daytime Spaces"
    lights:
      - light.living_room
      - light.kitchen
      - light.office
    min_brightness: 30
    max_brightness: 100

  - name: "Bedroom"
    lights:
      - light.bedroom_ceiling
      - light.bedroom_lamp
    min_brightness: 5
    max_brightness: 80
    sleep_brightness: 1
    sleep_color_temp: 1000

Related Topics

• Brightness Modes - Detailed explanation of brightness calculation modes
• Sleep Mode - Sleep mode configuration
• Manual Control - How manual control detection works