search

Jason-Morcos / homebridge-magic-occupancy

Occupancy sensor linked to one or more switches with a built-in delay not-unoccupied delay for Homebridge
GNU General Public License v3.0
79 stars 3 forks source link

readme

Homebridge "Magic Occupancy Switch" Plugin

npm version verified-by-homebridge

IF YOU ARE AN EXISTING USER OF HOMEBRIDGE-MAGIC-OCCUPANCY v2, DO NOT UPDATE TO v3 OF THIS PLUGIN UNLESS YOU ARE OKAY WITH YOUR PREVIOUS SETTINGS FOR THIS PLUGIN BEING RESET TO DEFAULTS WHICH WILL LOSE ANY AUTOMATIONS YOU SET UP IN THE HOME APP BASED ON v2 SWITCHES AND SENSORS. v3 IS A SIGNIFICANT REWRITE AND OFFERS DIFFERENT OPTIONS THAN v2 WHICH ARE VERY POWERFUL BUT REQUIRE A MANUAL UPGRADE

This plugin allows you to create complex automations leveraging motion sensors and switches in tandem, helpful for making your lights feel like "magic". If you want the bathroom fan to turn off a few minutes after the lights, this plugin is for you. If you want the lights in your house to turn on when you're pulling up to the driveway and then stay on as long as you're walking around the house, this plugin is for you. If you want your lights to stay on for a few minutes if triggered by motion or forever if triggered manually by a light switch, this plugin is for you. Now go automate some magic!

How to install

sudo npm install -g homebridge-magic-occupancy

Example config.json:

I recommend configuring the switch via the Homebridge X UI. However, you may configure the plugin manually via config.json

    "accessories": [
        {
          "accessory": "MagicOccupancy",
          "name": "Hallway Occupancy",
          "stayOccupiedDelay": 60,
          "maxOccupationTimeout": 86400,
          "persistBetweenReboots": true,
          "startOnReboot": false,
          "lightSwitchesNames": "Light Switch 1, Light Switch 2",
          "statefulSwitchesNames": "Stateful Switch 1, Stateful Switch 2",
          "triggerSwitchesNames": "Trigger Switch 1, Trigger Switch 2",
          "statefulStayOnSwitchesNames": "Stateful Stay-On Switch 1, Stateful Stay-On Switch 2",
          "triggerStayOnSwitchesNames": "Trigger Stay-On Switch 1, Trigger Stay-On Switch 2",
          "createMasterShutoff": true
        }
    ]

To create multiple occupancy sensors in Homebridge X UI, scroll to the bottom of the plugin's settings and click the "Add Another" button to setup additional full Magic Occupancy configurations.

What problem will this solve?

This package is optimal for turning on lights in rooms via motion sensors or other triggers. In an ideal world, if lights are turned on by a motion sensor you would want them to turn off when motion stops. Also, ideally if you turned on the lights manually they would never turn off (or not turn off for a long time).

That's what this plugin does

This package exposes an occupation sensor with six different types of triggers. You can combine any of them to create any behavior you'd like. There are four types of simple switches and two types of complex switches.

Simple Switches:

Complex Switches:

More Info on Switches:

When the stateful switch is turned on, the occupation sensor is turned on. When the stateful switch then turns off, the occupation sensor stays on for a customizable number of seconds which can be 0 (the Stay Occupied Delay).

When a trigger stateless switch is turned on, it stays on for a second before automatically turning off. When one of these switches turns on, it turns on the occupancy sensor while it's on and the occupancy sensor continues to stay on for the Stay Occupied Delay after the trigger finishes. This one is really useful for triggering with a motion detected event. You can use any combination of actions from these two types of switches to keep the occupation sensor on.

The other two types of simple switches, Stateful and Trigger Stay-on Switches, act just like their non Stay-on siblings with one key difference - they can't activate the occupation sensor, only keep it active. These are useful, for example, if you have a hallway light that you want to turn on when the garage opens and keep on then as long as you have motion anywhere in the house (but you wouldn't want motion in the house to normally turn the light on).

The icing-on-the-cake switch is the "Light" switch. This switch is the key to the use case above - being able to balance a manual light switch and motion sensor. In essence, a "Light" switch is a stateful switch that is ideal for automation using lights. The key point is that because the switch is turned on automatically whenever motion is detected, it avoids a dead end of "Motion Sensor triggers Occupancy -> Occupancy Triggers Lights On -> Light On triggers a switch on Occupancy -> Motion sensor stops but occupancy stays on forever."

The final switch is the Master Shutoff switch. This switch will instantly turn off all the other switches and turn off the occupancy sensor when turned on. This is helpful for advanced automation use cases.

The last configuration setting of note is the "Absolute Max Occupation Time (auto-shutoff)". This lets you set a max time in seconds after which the occupation sensor should always turn itself off no matter what.

Overall this plugin is quite complex, but that's also what makes it powerful.

Example Set of HomeKit Automations

Here is an example use case for how you can make this switch incredible powerful. This assumes your room is a hallway with a light and motion sensor.

Homebridge config:

    "accessories": [
        {
          "accessory": "MagicOccupancy",
          "name": "Hallway Occupancy",
          "stayOccupiedDelay": 60,
          "maxOccupationTimeout": 86400,
          "persistBetweenReboots": true,
          "startOnReboot": false,
          "lightSwitchesNames": "Hallway Occupancy Light Switch",
          "statefulSwitchesNames": "Hallway Occupancy Motion Switch",
          "triggerSwitchesNames": "Hallway Occupancy Trigger Switch",
          "statefulStayOnSwitchesNames": "Hallway Occupancy Stay-On Stateful Switch",
          "triggerStayOnSwitchesNames": "Hallway Occupancy Stay-On Trigger Switch",
          "createMasterShutoff": false
        }
    ]

HomeKit Automations

Now, when the Hallway Lights are manually turned on or off, they stay on until the switch is manually turned back off or the maxOccupationSeconds time (86400 seconds=1 day) elapses. When the Hallway Lights are turned on by the motion sensor, they automatically turn off stayOccupiedDelay (60 seconds=1 minute) after motion stops.

Additional Advanced HomeKit Automations

These automations add the fancy elements of turning on the hallway lights when the garage opens, keeping the hallway lights on for longer if they're already on and the kitchen lights turn on, and keeping the hallway lights on as long as the dining room lights are on (if the hallway lights are already on). Fancy!