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

| Param | Description | Default | | ------------- | ------------- | -------- | | accessory | Must be set to "AwayMode" | name | The name of the switch | "Away Mode" | | sensorNames | Array of names for each sensor to be createdDEPRECATED - See 'sensors' parameter. If the 'sensors' parameter is specified, this will be ignored. | ["Trigger 1"] | | sensors | Array of per-sensor information.Each sensor object MUST contain 'name' and MAY contain 'minOffTime', 'maxOffTime', 'minOnTime', 'maxOnTime', 'activeTimesForSensor', 'offset'. These time parameters override the globally defined time parameters if specified.Example 1: [{"name": "Trigger1"}]Set sensor name, use the global time parameters.Example 2: [{"name": "Trigger1", "minOffTime": 27}]Set sensor name, override the 'minOffTime' global time parameter.Example 3: [{"name": "Trigger1", "activeTimesForSensor":[{"start": "sunset", "end": "23:00"}]}]Set sensor name, override the 'activeTimes' global time parameter.Example 4: {"name": "Trigger 1", "offset": {"sunrise": 0, "sunset": -30}}Set sensor name, override the 'offset' global time parameter.See global time parameters: 'minOffTime', 'minOffTime', 'minOnTime', 'maxOffTime', 'activeTimes', 'offset'Note: The 'activeTimesForSensor' parameter maps to the global 'activeTimes' parameter.Note: If the 'sensors' parameter is specified, the 'sensorNames' parameter will be ignored.Note: With recent changes in HomeKit (~iOS16, etc.), the sensor name assignments are not respected by HomeKit and will show up in the Home app (and other HomeKit compatible apps) as the name of the main switch. If you wish, you can manually change the name of the sensors in the Home app by removing the existing name and replacing it with the suggested name that is displayed. The suggested name is the name assigned in configuration. | [{"name": "Trigger1"}] | | minOffTime | Minimum off time (secs) | 300 | | maxOffTime | Maximum off time (secs) | 1800 | | minOnTime | Minimum on time (secs) | 1800 | | maxOnTime | Maximum on time (secs) | 3600 | | startTime | Time at which triggers should start to fire("hh:mm"|"sunrise"|"sunset")DEPRECATED - See 'activeTimes' parameter. If the 'activeTimes' parameter is specified, this will be ignored. | "00:00" | | endTime | Time at which triggers should stop firing("hh:mm"|"sunrise"|"sunset")DEPRECATED - See 'activeTimes' parameter. If the 'activeTimes' parameter is specified, this will be ignored. | "23:59" | | activeTimes | Array of start/end times for periods when triggers should fire.Set start/end times as: ("hh:mm"|"sunrise"|"sunset")You may also include the optional "absolute" parameter as: (true|false). When set to true, sensors will turn off immediately when the end time is reached (if one is on).You may also include the optional "maxActivations" parameter as: (integer). When set, it indicates the maximum number of times the sensor will be activated during period.Example 1: [{"start": "sunset", "end": "22:00"}]Example 2: [{"start": "sunset", "end": "22:00", "absolute": true, "maxActivations": 1}]| [{"start": "00:00", "end": "23:59"}] | | location | Lat/long location to compute sunrise/sunset from. Use in conjunction with "startTime"|"endTime" when they are set to "sunrise"|"sunset".({"lat": x, "long": y}) Find your location: GPS Coordinates | {"lat": 0, "long": 0} | | offset | Offset information for sunrise/sunset. Offset is in minutes. May be negative (before) or positive (after). Use in conjunction with "startTime"|"endTime" when they are set to "sunrise"|"sunset".({"sunrise": mins, "sunset": mins}) | {"sunrise": 0, "sunset": 0} |

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:

| startTime | endTime | Offset |Description | | --------- | ------- | ------ | ----------- | | "08:00" | "20:00" | NA | Span the hours from 8am to 8pm | | "20:00" | "08:00" | NA | Span the hours from 8pm to 8am | | "sunset" | "22:00" | {"sunset":-15} | Span the hours from 15 minutes before sunset to 10pm. Sunset is computed based on the location you provide. | | "23:00" | "sunrise" | {"sunrise":30} | Span the hours from 11pm to 30 minutes after sunrise. Sunrise is computed based on the location you provide. | | "sunrise" | "sunset" | {"sunrise":-15, "sunset":15} | Span the hours from 15 minutes before sunrise to 15 minutes after sunset. Sunrise and sunset are computed based on the location you provide. |

Logging

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