SwitchFlow Controller

This integration helps you automatically turn lights or switches on and off when motion or presence is detected. For example, a hallway motion sensor can turn on the hallway light, which then turns off when the area is clear.

You do not need to write code or YAML automations. Set everything up through Home Assistant's interface.

Languages

The integration's setup screens are available in English, Spanish, and Catalan.

What SwitchFlow Controller Does

SwitchFlow Controller lets you create several independent sets of rules, called controllers. Each controller manages one main light or switch and can optionally use a night light, motion or presence sensors, door or window sensors, and other lights to turn off when the main light turns on.

In Home Assistant, each device function is an entity. For example, a single motion detector and a light are usually two separate entities. This integration connects the entities you select; it does not create new devices or sensors.

You can use it for a basic motion-activated light, or add features such as a night light, a brightness limit, or a light and notification response when your alarm is armed. The extra features are optional.

How It Works

1. The controller must be enabled. You can also set a shared Smart Mode entity. When one is configured, controllers only respond while it is on. Without one, enabled controllers can respond normally.
2. A selected motion or presence sensor detects activity. The controller only turns a light on from motion if Turn on when motion/presence is detected is enabled. This setting is off by default. You can select up to two sensors for a controller.
3. The controller chooses which light to use. Normally it uses the main light. If you have configured a night-mode entity and a night light, it can use the night light when night mode is on. If you have configured an illuminance sensor, its reading must be below the selected limit; the default limit is 10 lux when no limit is entered.
4. The timer starts or restarts. New motion that activates the controller restarts its turn-off timer, so continued activity keeps the light on. The default delay is one hour; you can choose a shorter delay.
5. The light turns off when it is safe to do so. After the delay, all configured motion and presence sensors must be clear before the controller turns off its managed lights. If a sensor is still active, the controller waits for another delay and checks again. Alternatively, enable Turn off when the sensor clears to turn the lights off as soon as all configured sensors are clear.

When the Alarm Is Armed

Alarm behavior is optional. To use it, select a Home Assistant alarm entity in the shared settings. The integration responds only when that alarm reports an armed state. If you also select an alarm timer, it must be idle; while it is active, alarm responses are paused.

• For motion or presence, enable Notify when a motion or presence sensor activates and the alarm is armed on the controller if you want an alert. When an eligible motion event turns on or controls a light while the alarm is armed, the integration uses the shared alarm-light duration instead of the normal turn-off delay. The light turns off when that duration ends, even if a motion sensor is still active. The alert itself is optional and needs a notification action in the shared settings.
• For doors or windows, select up to two opening sensors on the controller. When the alarm is armed, Smart Mode is on (if configured), and a sensor changes from closed to open, the main light turns on if needed and uses the shared alarm-light duration. If the light is already on without an active controller timer, the opening does not take over that light. If a notification action is configured, an alert is sent. This opening alert does not depend on the controller's motion-notification setting.

The alarm-light duration is shared across controllers, but each controller has its own timer. Without an alarm configured, motion and presence still follow the normal controller settings.

The shared notification action can be a Home Assistant script or a notify entity. If you select a script, it receives the alert text (message), the controller name (controller_name), and the sensor that triggered it (trigger_entity_id). If no notification action is selected, lights can still respond to alarm events, but no alert is sent.

You do not need this YAML for a basic motion-activated light. If you want to test alarm notifications with a script, this example creates a persistent notification in Home Assistant:

alias: Send Alarm Notification
sequence:
	- action: persistent_notification.create
		data:
			title: "Alarm: {{ controller_name }}"
			message: "{{ message }}"
mode: single

Save the script in Home Assistant, then select it as the shared Alarm notification action in SwitchFlow Controller's settings.

Quick Start

For a simple setup, you need:

• A light or switch that Home Assistant can already control.
• A motion or presence sensor if you want the light to turn on automatically.

Install the integration, add a controller, select the light and sensor, and enable the option to turn on when motion is detected. The other options in this guide are optional.

Installation

Marketplace (formerly HACS)

1. In Home Assistant 2026.11 or newer, open Settings > Marketplace. In older versions, open HACS.
2. Search for SwitchFlow Controller and select Install.
3. Restart Home Assistant if prompted.
4. Go to Settings > Devices & services > Add integration and search for SwitchFlow Controller.

Manual Installation

1. Copy the custom_components/switchflow_controller folder from this repository into the custom_components folder in your Home Assistant configuration directory. Create custom_components if it does not exist.
2. Restart Home Assistant.
3. Go to Settings > Devices & services > Add integration and search for SwitchFlow Controller.

Setup Guide

1. Shared Settings

When you add the integration, you will see global settings. These are shared by all your controllers. If you only want a motion sensor to turn on a light, you do not need to select anything here; keep the defaults.

The global settings are:

• Smart mode: An input helper or sensor that lets you enable or pause all controllers. If configured, controllers only run while it is on. If not configured, enabled controllers can run normally.
• Night mode: An input helper or sensor that indicates it is nighttime. To use it, also select a night light in the controller.
• Alarm and alarm timer: Optional settings for responding to motion or openings while your alarm is armed.
• Alarm notification: An optional, shared notification action. Configure it only if you want to receive alerts.
• Alarm light duration: How long a light stays on for an alarm event. The default is one minute.

An input helper is an item you create in Home Assistant to hold a value or state, such as a virtual switch for night mode. You do not need to create one for a basic setup.

2. Create a Controller

After adding the integration, create a controller for each light or area. The setup guides you through three sections:

1. Lights and switches: Select the main light. You can also add a night light or other lights to turn off when the main light turns on.
2. Motion and presence: Select up to two sensors and choose when the light turns on and off.
3. Windows and doors: Optionally select up to two opening sensors to use with your alarm.

For your first controller, start with just the main light and one motion sensor. Make sure the controller is enabled, then enable Turn on when motion/presence is detected. This option is off by default, so you must enable it if you want the sensor to turn on the light.

3. Choose When the Light Turns Off

The default turn-off delay is one hour. You can change it, for example, to two minutes. When the delay has passed, the light turns off once all selected sensors report that the area is clear. If a sensor is still active, the controller waits and checks again after the same delay.

You can also enable Turn off when the sensor clears. The light will then turn off as soon as all selected sensors report that the area is clear, without waiting for the delay.

Example: Hallway Light

1. Create a controller and select the hallway light as the main light.
2. In the motion section, select the hallway motion sensor.
3. Enable the option to turn on when motion is detected.
4. Set the turn-off delay to two minutes.
5. Leave the other options empty and save.

When the sensor detects motion, the light turns on. If motion continues, the timer restarts. Once the delay has passed and the sensor is clear, the light turns off.

More Examples

Bathroom light

Select the bathroom light as the main light and the bathroom motion sensor as a detector. Enable motion activation and choose a short turn-off delay, such as two minutes. The light turns on when someone enters and turns off after the room is clear.

Hallway with a night light

Select the normal hallway light as the main light, a dimmer light as the night light, and the hallway motion sensor as a detector. Select a night-mode helper in the shared settings. When night mode is on, motion can use the dimmer light instead of the main light.

Staircase with two motion sensors

Select the staircase light and add one motion sensor at the bottom of the stairs and another at the top. Enable motion activation. The light stays on until the turn-off delay has passed and both sensors are clear.

Entrance light when the alarm is armed

Select the entrance light as the main light and the front-door contact sensor as an opening sensor. In the shared settings, select your alarm and choose an alarm-light duration. When the alarm is armed and the door opens, the entrance light turns on for that duration. Add a notification action in the shared settings if you also want an alert.

Optional Features to Try Later

• Night light: Select a main light and a night light, then configure the global night-mode entity. When night mode is on, the night light is used when appropriate.
• Ambient light control: Select a sensor that measures light in lux. The light can turn on only when the reading is below the threshold. If you leave the threshold empty, the default is 10 lux.
• A second sensor: Useful when an area has more than one detector. All configured sensors must be clear before the light turns off.
• Alarm: See When the Alarm Is Armed for how armed states, notifications, and alarm-light timers work.
• Door or window sensors: Add up to two opening sensors to a controller. They are used only when the alarm is armed.
• Motion alerts while the alarm is armed: Enable the notification option on each controller where you want motion alerts. The notification action itself is shared across controllers.

Troubleshooting

• The sensor does not turn on the light: Check that the controller is enabled and that you enabled the option to turn on when motion is detected.
• I configured Smart Mode: Make sure the selected helper or sensor is on. Controllers do not run while it is off.
• The light takes a long time to turn off: The default delay is one hour. After the delay, the sensor must also be clear unless you enabled immediate turn-off when sensors clear.
• An entity is unavailable: Check in Home Assistant that the selected device or entity is available again. The integration may also show a warning under Repairs.

Frequently Asked Questions

Do I need to create a Home Assistant automation?

No. The controller applies the rules you configure in the integration's setup screens.

Can I start without an alarm, input helpers, or a lux sensor?

Yes. To get started, you only need a light and, if you want motion activation, a motion or presence sensor.

Can I import my blueprint automations?

Not automatically. If you used a blueprint before, create the controllers manually and test them one at a time.

Technical Information

The integration provides these optional Home Assistant actions (services) for advanced use:

• switchflow_controller.enable_controller
• switchflow_controller.disable_controller
• switchflow_controller.reset_controller_timer
• switchflow_controller.force_turn_on
• switchflow_controller.force_turn_off

Most users do not need these actions. See services.yaml for their input fields.

If an entity you selected becomes unavailable, Home Assistant may show a warning under Repairs. Optional settings can be left empty.

Blueprint automations are not imported automatically. If you are replacing a blueprint, create the controllers manually and test them one at a time.

For changes in each release, see CHANGELOG.md. To report a problem, open an issue in the repository.