From 77183ee3eb54e779fff104c99736ddc406e954d8 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Sun, 6 Sep 2026 22:38:25 +0200 Subject: [PATCH] docs: explain physical turn-ons that require reloading (#1581) * docs: explain physical turn-ons that require reloading * docs: list options that require takeover control --- README.md | 8 ++++++++ docs/troubleshooting.md | 8 ++++++++ 2 files changed, 16 insertions(+) diff --git a/README.md b/README.md index 1ea941fd..6f710516 100644 --- a/README.md +++ b/README.md @@ -762,6 +762,14 @@ represent one sent command or the current desired state. ### :exclamation: Common Problems & Solutions +#### :bulb: Lights Only Adapt After Reloading + +If lights stop adapting after you turn them on with a physical switch or a Zigbee-bound remote, check the Adaptive Lighting switch's `manual_control` attribute. With `take_over_control: true` and `detect_non_ha_changes: false`, a turn-on without a matching Home Assistant `light.turn_on` call marks the light as manually controlled. Reloading clears that state, but the next physical turn-on can trigger it again. + +To adapt these turn-ons while still detecting later manual changes, enable `detect_non_ha_changes` and leave `manual_control_on_external_turn_on` disabled. This requires the light integration to report its state reliably. If you want Adaptive Lighting to keep adapting regardless of manual changes, disable `take_over_control` along with the options that require it: `detect_non_ha_changes`, `adapt_only_on_bare_turn_on`, and `manual_control_on_external_turn_on`. + +This explains the physical-switch case in [#1056](https://github.com/basnijholt/adaptive-lighting/issues/1056), but not every report in that thread. If the light is not listed in `manual_control`, include diagnostics and debug logs from the failed turn-on when reporting it. Lights returning from `unavailable` after a power cut are a separate case from an `off` to `on` state change. + #### :bulb: Lights Not Responding or Turning On by Themselves Adaptive Lighting sends more commands to lights than a typical human user would. If your light control network is unhealthy, you may experience: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index f39c62bc..f0596563 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -45,6 +45,14 @@ represent one sent command or the current desired state. +#### :bulb: Lights Only Adapt After Reloading + +If lights stop adapting after you turn them on with a physical switch or a Zigbee-bound remote, check the Adaptive Lighting switch's `manual_control` attribute. With `take_over_control: true` and `detect_non_ha_changes: false`, a turn-on without a matching Home Assistant `light.turn_on` call marks the light as manually controlled. Reloading clears that state, but the next physical turn-on can trigger it again. + +To adapt these turn-ons while still detecting later manual changes, enable `detect_non_ha_changes` and leave `manual_control_on_external_turn_on` disabled. This requires the light integration to report its state reliably. If you want Adaptive Lighting to keep adapting regardless of manual changes, disable `take_over_control` along with the options that require it: `detect_non_ha_changes`, `adapt_only_on_bare_turn_on`, and `manual_control_on_external_turn_on`. + +This explains the physical-switch case in [#1056](https://github.com/basnijholt/adaptive-lighting/issues/1056), but not every report in that thread. If the light is not listed in `manual_control`, include diagnostics and debug logs from the failed turn-on when reporting it. Lights returning from `unavailable` after a power cut are a separate case from an `off` to `on` state change. + #### :bulb: Lights Not Responding or Turning On by Themselves Adaptive Lighting sends more commands to lights than a typical human user would. If your light control network is unhealthy, you may experience: