homebridge-away-mode

Homebridge plugin that provides triggers to turn on and turn off lights to simulate occupancy. We provide the triggers, you provide the lights.

A simulated switch is created that controls whether "away mode" is active. When the switch is on, away mode is active. When the switch is off, away mode is inactive. A set of simulated sensors detect "activity". When activity (motion) is detected, turn the light on. When activity (motion) is not detected, turn the light off. The behavior of each sensor is random: a sensor is off for a period of time, turns on for a period of time, then repeats. When the switch is turned on, the sensors are activated to start their off/on behavior. When the switch is turned off, the sensors are deactivated and turned off.

Homebridge Restart

The plugin attempts to restore itself to the its previous state if a restart occurs and the "away mode" switch is on:

1. The "away mode" switch is turned on.
2. For any sensor that was previously on:
   1. If the sensor is still allowed to be on, it is turned on and the normal on/off sequence is resumed, starting from on.
   2. If the sensor is not allowed to turn on, it is not turned on and the normal on/off sequence is resumed, starting from off.
3. Any sensor that was previously off will begin its on/off sequence, starting from off.

Caveat - Because the plugin does not track how long a sensor had been on (or off) when a restart occurred, it is possible that the sensor will be on (or off) longer than the settings would normally allow. This will only effect the first sequence following the restart.

Installation

npm -g install homebridge-away-mode

Configuration

It is highly recommended to use the homebridge-config-ui-x plugin for ease of configuration. The homebridge-away-mode plugin's behavior is driven almost entirely by the values you specify in the configuration. Depending on how many sensors you configure and how complex you make each sensor's behavior, the configuration can become quite extensive.

Simple configuration example

config.json:

"accessories": [
    {
        "accessory": "AwayMode",
        "name": "Away Mode",
        "sensors": [
            {
                "name": "Trigger1"
            },
            {
                "name": "Trigger2"
            }
        ],
        "minOffTime": 300,
        "maxOffTime": 1800,
        "minOnTime": 1800,
        "maxOnTime": 3600
    }
]

The above example creates a switch called 'Away Mode' and two sensors: 'Trigger 1' and 'Trigger 2'. A sensor will remain off for 300 to 1800 seconds (5 minutes to 1/2 hour). A sensor will remain on for 1800 to 3600 seconds (1/2 hour to 1 hour). Sensors will only be active when the 'Away Mode' switch is turned on.

In this example, you use your automation software to turn the 'Away Mode' switch on when you want the sensors to be active (turn on & off), and off when you don't want them to be active.

HomeKit

In Home (or any of the HomeKit compatible apps), you will see three new devices exposed:

• 1 switch named 'Away Mode'
• 2 motion sensors named 'Trigger 1' and 'Trigger 2'

Automate the switch to turn on and off at specific times. For example:

• 15 minutes before sunset (daily), turn the switch on
• At 10:00pm (daily), turn the switch off

Automate the motions sensors. For Example:

• When motion is detected ('Trigger 1'), turn 'Lamp 1' on
• When no motion is detected ('Trigger 1'), turn 'Lamp 1' off

This setup makes sense when you know you will be away from your house for an extended period of time. You enable the switch automation before you leave and disable it when you return.

Advanced configuration example

config.json:

"accessories": [
    {
        "accessory": "AwayMode",
        "name": "Away Mode",
        "sensors": [
            {
                "name": "Trigger1"
            },
            {
                "name": "Trigger2"
            }
        ],
        "minOffTime": 300,
        "maxOffTime": 1800,
        "minOnTime": 1800,
        "maxOnTime": 3600,
        "activeTimes": [
            {
                "start": "sunset",
                "end": "22:00"
            }
        ],
        "location": {
            "lat": 40.689510,
            "long": -74.044500
        },
        "offset": {
            "sunrise": 0,
            "sunset": -15
        }
    }
]

The above example creates a switch called 'Away Mode' and two sensors: 'Trigger 1' and 'Trigger 2'. A sensor will remain off for 300 to 1800 seconds (5 minutes to 1/2 hour). A sensor will remain on for 1800 to 3600 seconds (1/2 hour to 1 hour). Sensors will only be active when the 'Away Mode' switch is turned on. Sensors will only turn on from 15 minutes before sunset to 10:00pm. The location information is used to compute the values for sunrise/sunset (as needed).

In this example, you might use your automation software to detect when your residence is not occupied and turn on the 'Away Mode' and turn if off when the residence is occupied. However, you only want the sensors turning on and off during a specific period of the day.

Note: This can mostly be accomplished using HomeKit and the simple configuration. However, HomeKit does not allow you to mix specific times (eg., 10:00pm) with sunrise/sunset times.

HomeKit

In Home (or any of the HomeKit compatible apps), you will see three new devices exposed:

• 1 switch named 'Away Mode'
• 2 motion sensors named 'Trigger 1' and 'Trigger 2'

Automate the switch to turn on and off based on specific conditions. For example:

• When the last person leaves home, turn the switch on
• When the first person arrives home, turn the switch off

Automate the motions sensors. For Example:

• When motion is detected ('Trigger 1'), turn 'Lamp 1' on
• When no motion is detected ('Trigger 1'), turn 'Lamp 1' off

This setup makes sense when you want to make sure the automation always runs when you are not home, but only want the sensors to trigger during specific times of the day.

Parameters

Parameters in the table above are optional, except 'accessory' which must be set to 'AwayMode', and need not be specified if you are happy with the default value.

Time examples:

Logging

Use the -D option on Homebridge to enable verbose logging for this plugin.