haos-blueprints/Common/Motion Light/README.md

Motion Light Automation Blueprint

This blueprint creates a smart motion-activated light control system. It handles motion detection, luminance-based triggering, and manual override detection to provide intelligent lighting automation.

Features

• Multiple motion sensor support (triggers on ANY sensor)
• Condition switches (ALL must be ON for automation to work)
• Multiple lights and/or switches control
• Light groups and area-based targeting (native area picker)
• Configurable timeout delay before turning off
• Minimum on duration (prevents rapid on/off cycling)
• Motion sensor on/off debounce (filter false triggers and PIR drop-outs)
• Smooth light transitions with configurable duration
• Luminance sensor support (only trigger in dark conditions)
• Time-based conditions (only active during specified hours)
• Day/Night mode (different light settings based on time)
• Scene support (activate scenes instead of light parameters)
• Dim before off (visual warning before turning off)
• Manual override detection (stops automation if user changes light) with configurable grace period
• Brightness threshold (only trigger if light is dim)
• Custom light parameters (brightness, color, etc.)
• Callback actions for enable/disable/manual events
• Debug notifications for troubleshooting

State Machine

The automation tracks these states via persistent storage:

State	Value	Description
NONE	0	Idle, waiting for motion
ENABLING	2	Light turn-on command sent, waiting for state change
ENABLED	1	Light is ON and controlled by automation
MANUAL	3	User took control, automation paused until light turns off

Behavior Notes

• Will NOT turn on light if it's already ON (prevents hijacking user control).
• If user changes the light while automation is active (e.g., dim, color, scene), enters MANUAL mode (after grace period).
• If the user turns the light ON while the automation is idle (pre-emptive manual control), it enters MANUAL mode and fires the manual_action callback. The disable_action callback is not run in this case (nothing was enabled to disable).
• If the light is turned off by any external source while motion is still active, the automation re-enables it (external turn-off recovery). To intentionally exit the automation, also turn off the corresponding condition switch — this routes through the disable path and respects the configured timeouts.
• Grace period prevents false manual overrides from delayed device state reports (e.g., Zigbee) — including stray reports that can follow a turn-off.
• MANUAL mode exits when light is turned OFF (by any means).
• Timeout delay only applies when turning OFF (motion cleared).
• Time conditions support overnight windows (e.g., 22:00 to 06:00).
• Day/Night mode uses separate time window from time conditions.

Brightness threshold interaction

brightness_threshold is checked only when the automation decides whether to enable. A light that is on but dimmer than the threshold is treated as "available to take over" — so the automation will run with that light. When the disable path runs, it will turn the light off (it does not restore a below-threshold dim state).

Callback ordering and mode: restart

Light state changes feed back into the automation, which uses mode: restart to handle rapid bursts. To make sure callbacks aren't silently dropped when the automation restarts mid-action, both enable_action and disable_action run before the corresponding turn-on/turn-off command.

Requirements

• At least one motion sensor.
• input_text entity for persistent state storage. Each automation instance must have its own entity. Increase the entity's max_length (default 100) to at least 255 to leave room for the JSON state — short values can cause silent truncation.
• Target light(s), switch(es), group, or area to control.

Author

Alexei Dolgolyov (dolgolyov.alexei@gmail.com)