--- 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 🤖. With `expand_light_groups: false`, manual control belongs to the group. A direct member change cannot pause adaptation for only that member; use group-level manual control or enable expansion for individual tracking. Explicit member targets in Adaptive Lighting services stay individual targets and do not mark or command the whole group. Changing expansion at runtime discards tracking and pending adaptation for targets no longer used by any profile. 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: ```jinja {{ '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". ```yaml 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 | ```yaml 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. ```yaml 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). ```yaml 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. ```yaml adaptive_lighting: - name: "Respect scenes" lights: - light.living_room take_over_control: true adapt_only_on_bare_turn_on: true ``` ### manual_control_on_external_turn_on When enabled, a turn-on without a state-change context matching the latest recorded Home Assistant `light.turn_on` is treated as manual control. This pauses brightness and color adaptation until manual control resets, rather than skipping just the first adjustment. The usual off/on, explicit reset, and configured timeout rules apply. A later unmatched turn-on marks the light manually controlled again. 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. Enable this if you want turn-ons from physical controls or native scenes to preserve their brightness and color. To adapt unmatched turn-ons, leave this disabled and enable `detect_non_ha_changes`. 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. ```yaml 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 manual_control_on_external_turn_on: true # leave unmatched off→on events unchanged ``` ### restore_manual_control By default a Home Assistant restart clears manual control: the startup adaptation brings every light back to the adaptive values. When enabled, manual control is saved to storage as it changes and restored at startup, so a light you dimmed before the restart stays where you left it. The option is off by default and nothing is written to storage until at least one profile enables it. What is stored is the manual-control flag of every light your profiles control, with the same brightness and color detail the switch attributes show. It is written whenever a flag changes, whether you dimmed the light, called `adaptive_lighting.set_manual_control`, or turned the light off. Writes are debounced by two seconds and go to one `adaptive_lighting.manual_control` file per Home Assistant instance. At startup the stored flags are pruned before anything adapts. A flag is kept only when the light is on. A light that was turned off while Home Assistant was down is not restored, because manual control normally clears on the off event that never reached Home Assistant. A light that is unavailable at startup is treated the same way, since its integration may bring it back in any state. A light that no profile controls anymore is forgotten entirely. Everything that is kept follows the usual rules from then on: off and on, an explicit reset, or a sleep mode change clears it. Profiles with `autoreset_control_seconds` do not restore manual control, because their holds are meant to expire on their own. Manual control belongs to the light rather than to a profile, so when several profiles control the same light the flag is restored as long as one of those profiles has this option enabled without an autoreset. The result does not depend on the order in which the profiles are set up. Only a full restart restores manual control. Reloading a config entry, or changing an option, still clears it the way it always has. ```yaml adaptive_lighting: - name: "Keep my dimming through restarts" lights: - light.living_room take_over_control: true restore_manual_control: true ``` ## 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 ```yaml 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](../automation-examples.md) 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:** ```yaml entity_id: light.living_room switch: switch.adaptive_lighting_living_room ``` You can use this event to trigger automations: ```yaml 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