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

<!-- CODE:START -->
<!-- print(include_section("../../README.md", "manual-control", strip_heading=True)) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
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 `skip_brightness_increases` option provides a dim-only policy for automatic adaptation. Adaptive Lighting can lower brightness and continue adapting color, but it will not raise brightness above the light's reported numeric value. To keep adapting after direct or physical brightness changes, use `take_over_control: false` and `detect_non_ha_changes: false`; otherwise the existing `pause_all` or `pause_changed` manual-control policy can pause adaptation before this brightness ceiling is applied.

This option does not store a brightness to restore later. A retained brightness reported while a light is off remains the ceiling on a bare turn-on, and leaving sleep mode does not necessarily restore the normal brighter target. Send a direct brightness request or disable `skip_brightness_increases` when you want to brighten the light. If the light reports no numeric brightness, Adaptive Lighting uses its calculated target.

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._**

<!-- OUTPUT:END -->

## 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
```

## 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