adaptive-lighting/docs/advanced/manual-control.md

icon
lucide/hand

Manual Control

Adaptive Lighting is designed to work seamlessly with manual adjustments, detecting when you or another source changes light settings and pausing adaptation accordingly.

How It Works

Adaptive Lighting is designed to automatically detect when you or another source (e.g., automation) manually changes light settings 🕹️. When this occurs, the affected light is marked as "manually controlled," and Adaptive Lighting will not make further adjustments until the light is turned off and back on or reset using the adaptive_lighting.set_manual_control service call. This feature is available when take_over_control is enabled.

Additionally, enabling detect_non_ha_changes allows Adaptive Lighting to detect all state changes, including those made outside of Home Assistant, by comparing the light's state to its previously used settings. The adaptive_lighting.manual_control event is fired when a light is marked as "manually controlled," allowing for integration with automations 🤖.

The Adaptive Lighting switch exposes these read-only attributes for its lights:

• manual_control: lights with any attribute marked as manually controlled.
• manual_control_brightness: lights with brightness marked as manually controlled.
• manual_control_color: lights with color marked as manually controlled.

These lists report manual-control flags. Actual adaptation also depends on take_over_control_mode and the brightness/color adaptation switches. For example, under the default pause_all mode, manually changing only brightness leaves manual_control_color empty while pausing both brightness and color adaptation. Under pause_changed, color can continue adapting.

The attributes are absent when the Adaptive Lighting switch is off. Use a fallback when checking them in templates:

{{ 'light.bedroom' in (state_attr('switch.adaptive_lighting_bedroom', 'manual_control_brightness') or []) }}

⚠️ Caution: Some lights might falsely indicate an 'on' state, which could result in lights turning on unexpectedly. Disable detect_non_ha_changes if you encounter such issues.

Configuration Options

take_over_control

When enabled (default: true), Adaptive Lighting detects light.turn_on service calls that specify brightness or color values. If such a call is detected for a light that's already on, that light is marked as "manually controlled".

adaptive_lighting:
  - name: "With manual control detection"
    lights:
      - light.living_room
    take_over_control: true  # default

take_over_control_mode

Controls how adaptation pauses when manual changes are detected:

Mode	Behavior
pause_all	Pause both brightness and color adaptation (default)
pause_changed	Only pause adaptation of the changed attribute

adaptive_lighting:
  - name: "Selective pause"
    lights:
      - light.living_room
    take_over_control: true
    take_over_control_mode: pause_changed  # Only pause changed attributes

detect_non_ha_changes

When enabled, Adaptive Lighting detects state changes made outside of Home Assistant by comparing the light's current state to its previously applied settings.

Warning

Use with caution. Some lights may falsely report an "on" state, which could result in lights turning on unexpectedly. Disable this option if you encounter such issues.

adaptive_lighting:
  - name: "Detect external changes"
    lights:
      - light.living_room
    take_over_control: true
    detect_non_ha_changes: true

autoreset_control_seconds

Automatically resets the manual control flag after a specified number of seconds. Set to 0 to disable (default).

adaptive_lighting:
  - name: "Auto-reset after 2 hours"
    lights:
      - light.living_room
    take_over_control: true
    autoreset_control_seconds: 7200  # 2 hours

adapt_only_on_bare_turn_on

When enabled, Adaptive Lighting only adapts lights when light.turn_on is called without specifying brightness or color. This is useful when you want scenes to work without interference.

adaptive_lighting:
  - name: "Respect scenes"
    lights:
      - light.living_room
    take_over_control: true
    adapt_only_on_bare_turn_on: true

adapt_only_on_ha_turn_on

When enabled, a light that turns on from off is only adapted if the state-change context exactly matches the most recent Home Assistant light.turn_on context recorded for that light. An unmatched turn-on is marked as manually controlled and left at its reported brightness and color.

Manual-control flags are shared by profiles controlling the same light. Use the same turn-on policy on those profiles; mixed policies can allow an earlier profile to adapt before another marks the light manually controlled.

This is the option to reach for when turning a light on with its local switch (or a native Lutron/Caséta scene) makes Adaptive Lighting override your brightness a moment later, forcing you to set it twice.

Its advantage over simply disabling detect_non_ha_changes is that the two behaviors are decoupled: you can keep detect_non_ha_changes: true to catch manual dimming of lights that are already on, while leaving unmatched turn-ons untouched.

Adaptive Lighting cannot identify every physical versus Home Assistant source. Some integrations replace or omit the service context when they publish device state. In that case, even a Home Assistant turn-on does not match and this option treats it as external.

adaptive_lighting:
  - name: "Respect physical switches and Lutron scenes"
    lights:
      - light.living_room
    take_over_control: true
    detect_non_ha_changes: true      # still catch manual changes to already-on lights
    adapt_only_on_ha_turn_on: true   # leave unmatched off→on events unchanged

Checking Manual Control Status

You can see which lights are marked as manually controlled by checking the switch attributes:

1. Go to Developer Tools → States
2. Find your Adaptive Lighting switch (e.g., switch.adaptive_lighting_living_room)
3. Look at the manual_control attribute - it lists all manually controlled lights

Resetting Manual Control

Via Service Call

service: adaptive_lighting.set_manual_control
data:
  entity_id: switch.adaptive_lighting_living_room
  lights:
    - light.floor_lamp
  manual_control: false  # Resume adaptation

By Turning Light Off and On

Simply turning a light off and then back on will reset its manual control status.

Via Automation

See Automation Examples for automation recipes that automatically reset manual control.

Events

When a light is marked as manually controlled, Adaptive Lighting fires an event:

Event type: adaptive_lighting.manual_control

Event data:

entity_id: light.living_room
switch: switch.adaptive_lighting_living_room

You can use this event to trigger automations:

automation:
  - alias: "Notify on manual control"
    trigger:
      platform: event
      event_type: adaptive_lighting.manual_control
    action:
      - service: notify.mobile_app
        data:
          message: "{{ trigger.event.data.entity_id }} was manually adjusted"

Best Practices

1. Use Zigbee groups when controlling multiple bulbs together - this ensures consistent manual control detection
2. Set reasonable autoreset times if you want lights to eventually resume adaptation
3. Use pause_changed mode if you only adjust brightness or color individually
4. Disable detect_non_ha_changes if you experience unexpected light turn-ons