Homebridge-theneverstill NPM

Homebridge Plugin TheNeverStill

Homebridge plugin to add critical functionality to your HomeKit home.

Frequently Asked Questions (FAQ)

What does this plugin do? // Why would I use this plugin?

Automations that trigger as frequent as every 30 seconds (rather than the 5 minute current HomeKit limitation) and are standard automation triggers instead of timer automations (meaning you can add additional triggers and conditions).
- E.g. Clock
  - Trigger Ideal State Switch checks every 30 seconds
Virtual switches with optional reset timers
- E.g. Motion Sensor Cooldown Switch
  - Driveway / yard / entrance nighttime lights
  - Bedroom / bathroom / kitchen / hallway lights (and fans)
- E.g. Ideal State Switch
  - Motion sensor lights (and fans)
  - Light sensor controlled doors and windows (e.g. chicken coop door)
- E.g. Time period of day
  - Daytime (between sunrise and sunset) / nighttime (between sunset and sunrise)
Virtual, renotifying security alarms
- E.g. Unresponsive Device Alarm
  - All battery powered devices
  - Critical and security devices (e.g. locks, garage doors, gates)

Isn't this plugin just a combination of other plugins?

Yes and no. While it is true that there are several other plugins that, when put together, add most of the same functionality, there are three critical differences:

homebridge-theneverstill allows you to combine related Homebridge devices all under one accessory. This is not only cleaner, but also:
With all related devices under one accessory, you can fully leverage the benefits of child bridges on each accessory. Per Homebridge: This can improve the general responsiveness and reliability of Homebridge.
(Coming soon!) This plugin will be verified by Homebridge. Many plugins with related functionality are not, so you are left with a lower guarantee of bug fixes and enhancements.

What's with the VA accessory name prefix?

It's an acronym for Virtual Accessory
It helps for quick identification of VA accessories

Homebridge Usage

Install

Log in to your Homebridge deployment and navigate to the Plugins tab
Search for theneverstill
Click the INSTALL button

Update

Log in to your Homebridge deployment and navigate to the Plugins tab
Find the plugin card for Homebridge TheNeverStill
Click the UPDATE button

Add Accessories

Log in to your Homebridge deployment and navigate to the Plugins tab
Find the plugin card for Homebridge TheNeverStill
Click the SETTINGS button
Enter properties for accessories and optionally click the + ADD ACCESSORY button to add new accessories
Click the SAVE button

Recommended Accessories

Clock

Purpose

Suppose you want to be alerted within 30 seconds of a device going unresponsive (e.g. a sensor's batteries run out of juice). Or suppose you miss an important Home notification (e.g. alarm, motion, contact) and wish you could be renotified every 30 seconds until the problem is resolved. Wouldn't it be great if you could go beyond the 5 minute limit of timer automations (and their lack of conditions) by being able to trigger automations every 30 seconds?

Create an accessory with the following configuration (see 'Add Accessories' steps above):

Use default values for all properties not explicitly noted below.

{
  "name": "Clock Virtual Accessory",
  "switchOneIsCreatable": true,
  "switchOneDefaultStateRevertTime": 30000,
  "switchTwoIsCreatable": true,
  "switchTwoDefaultStateRevertTime": 30000,
},

Set the Clock Virtual Accessory accessory to run a child bridge
- The purpose of setting this accessory to run as a child bridge, per Homebridge: This can improve the general responsiveness and reliability of Homebridge.
1. Log in to your Homebridge deployment and navigate to the Plugins tab
2. Find the plugin card for Homebridge TheNeverStill
3. Click the wrench (🔧) button
4. Click the Bridge Settings dropdown option
5. Toggle on the switch beside the Clock Virtual Accessory accessory
6. Click the SAVE button
Restart Homebridge
Add the Clock Virtual Accessory accessory to HomeKit
1. Log in to your Homebridge deployment and navigate to the Plugins tab
2. Find the plugin card for Homebridge TheNeverStill
3. Click the wrench (🔧) button
4. Click the Bridge Settings dropdown option
5. Open your HomeKit app (e.g. Home, Eve, Controller for HomeKit) and add a HomeKit Accessory using the QR code displayed under the Clock Virtual Accessory accessory
  1. On the Uncertified Accessory prompt click the Add Anyway button
  2. Select or create a room, e.g. Homebridge Room
  3. Name the child bridge, e.g. Clock Virtual Accessory Bridge
  4. Name the accessory (defined as a switch), e.g. Clock Virtual Accessory
  5. Name the child devices
    1. e.g. Clock Tick Switch
    2. e.g. Clock Tock Switch
Add the Clock Virtual Accessory scenes and automations
1. <Turn on Clock Tick Switch Scene>
  - Type: Scene
  - Name: <Turn on Clock Tick Switch Scene>
  - Action: Turn on Clock Tick Switch
2. <Turn on Clock Tock Switch Scene>
  - Type: Scene
  - Name: <Turn on Clock Tock Switch Scene>
  - Action: Turn on Clock Tock Switch
3. <Clock Heartbeat Automation>
  - Purpose: If your hub or Homebridge become unresponsive for an extended period of time Tick and Tock will stop working. This automation ensures Tick and Tock restart whenever your hub or Homebridge become responsive again. Additionally this automation resets Tick and Tock drift every 5 minutes.
  - Type: Timer Automation
  - The Home app does not support timer automations. You must use an advanced HomeKit app (e.g. Eve, Controller for HomeKit) to create them.
  - Name: <Clock Heartbeat Automation>
  - Repeat: every 5 minutes
  - Starts at: <the next 0/5 minute increment, e.g. Today at 11:40 AM, or Today at 2:45 PM, or Today at 2:50 PM; NOT Today at 10:33 AM>
    - You can start the timer on any minute increment, but it is easier for most people to remember and predict if it happens on 0/5 minute increments
4. <Clock Tick Off Automation>
  - Type: Trigger Automation
  - Name: <Clock Tick Off Automation>
  - Trigger: Clock Tick Switch Power Off
  - Conditions: None
  - Scene: <Turn on Clock Tock Switch Scene>
5. <Clock Tock Off Automation>
  - Type: Trigger Automation
  - Name: <Clock Tock Off Automation>
  - Trigger: Clock Tock Switch Power Off
  - Conditions: None
  - Scene: <Turn on Clock Tick Switch Scene>

Motion Sensor Cooldown Switch

Purpose Suppose you have one or more motion sensors that you use to trigger an automation that turns on some lights. How do you trigger the lights to turn off? Some motion sensors come with a customizable motion duration (until they stop reporting motion) that you could leverage, but many don't. Further, if you have multiple motion sensors on the same light trigger, you probably don't want the lights to turn off until all of the motion sensors are no longer detecting motion (after a cooldown period that you control). Wouldn't it be great if the lights only turned off after no motion was detected on multiple motion sensors for 5 minutes?

Create an accessory with the following configuration (see 'Add Accessories' steps above):
- For best results you should:
  - Set the motion duration as small as possible on all of your sensors (where applicable)
  - Set a default state revert time that is longer that your sensors' motion duration
- Use default values for all properties not explicitly noted below.
```
{
  "name": "Entrance Lights Virtual Accessory",
  "switchOneIsCreatable": true,
  "switchOneDefaultStateRevertTime": 300000,
},
```
Set the Entrance Lights Virtual Accessory accessory to run a child bridge
- The purpose of setting this accessory to run as a child bridge, per Homebridge: This can improve the general responsiveness and reliability of Homebridge.
1. Log in to your Homebridge deployment and navigate to the Plugins tab
2. Find the plugin card for Homebridge TheNeverStill
3. Click the wrench (🔧) button
4. Click the Bridge Settings dropdown option
5. Toggle on the switch beside the Entrance Lights Virtual Accessory accessory
6. Click the SAVE button
Restart Homebridge
Add the Entrance Lights Virtual Accessory accessory to HomeKit
1. Log in to your Homebridge deployment and navigate to the Plugins tab
2. Find the plugin card for Homebridge TheNeverStill
3. Click the wrench (🔧) button
4. Click the Bridge Settings dropdown option
5. Open your HomeKit app (e.g. Home, Eve, Controller for HomeKit) and add a HomeKit Accessory using the QR code displayed under the Entrance Lights Virtual Accessory accessory
  1. On the Uncertified Accessory prompt click the Add Anyway button
  2. Select or create a room, e.g. Homebridge Room
  3. Name the child bridge, e.g. Entrance Lights Virtual Accessory Bridge
  4. Name the accessory (defined as a switch), e.g. Entrance Lights Virtual Accessory
Add the Entrance Lights Virtual Accessory scenes and automations
1. <Turn on Entrance Light Switches After Motion Detected Scene>
  - Type: Scene
  - Name: <Turn on Entrance Light Switches After Motion Detected Scene>
  - Actions:
    - Turn on Entrance Lights Virtual Accessory
    - <Turn on entrance lights>
2. <Turn off Entrance Light Switches Scene>
  - Type: Scene
  - Name: <Turn off Entrance Light Switches Scene>
  - Action: <Turn off entrance lights>
3. <Automation to turn on lights when motion is detected>
  - Type: Trigger Automation
  - Name: <Automation to turn on lights when motion is detected>
  - Trigger: <Each desired motion sensor detecting motion>
  - Condition: Time: At night
    - This is configurable on the Home app, but at the time of writing it is not configurable on more advanced HomeKit apps (e.g. Eve, Controller for HomeKit)
  - Scene: <Turn on Entrance Light Switches After Motion Detected Scene>
4. <Automation to turn off lights when motion is no longer detected>
  - Type: Trigger Automation
  - Name: <Automation to turn off lights when motion is no longer detected>
  - Trigger: Entrance Lights Ideal State Alarm Power Off
  - Conditions: None
  - Scene: <Turn off Entrance Light Switches Scene>

Ideal State Switch

Purpose

Suppose you created a Motion Sensor Cooldown Switch. But what happens if some or all of your lights or Home hub(s) are unresponsive when the cooldown switch goes off? How long would your lights be left on until something reset their state? Wouldn't it be great if you had a way to easily define what the ideal state of the lights should be and reset them in a timer automation if their state is ever incorrect?

Disclaimer: This is best used for devices that are triggered by automations, not physical light switches or buttons. A smart light switch could be unresponsive to HomeKit but still work perfectly fine as a dumb switch, so it may cause unexpected results if HomeKit resets the device state right after you use the physical switch. (YMMV - Your mileage may vary. I personally still use it for these devices.)

Update the Entrance Lights Virtual Accessory accessory created above with the following configuration:

{
  "name": "Entrance Lights Virtual Accessory",
  "switchOneIsCreatable": true,
  "switchOneDefaultStateRevertTime": 300000,
  "switchTwoIsCreatable": true
},

Restart Homebridge
Rename the new virtual switch device
1. Open your HomeKit app (e.g. Home, Eve, Controller for HomeKit)
  1. Find the parent accessory (defined as a switch), e.g. Entrance Lights Virtual Accessory
  2. Find and rename the new child device, e.g. Entrance Lights Ideal State Switch
  3. Find and rename the original child device, e.g. Entrance Lights Motion Cooldown Switch
Update the Entrance Lights Virtual Accessory scenes
1. <Turn on Entrance Light Switches After Motion Detected Scene>
  - Type: Scene
  - Name: <Turn on Entrance Light Switches After Motion Detected Scene>
  - Actions:
    - Turn on Entrance Lights Ideal State Switch
    - Turn on Entrance Lights Motion Cooldown Switch
    - <Turn on entrance lights>
2. <Turn off Entrance Light Switches Scene>
  - Type: Scene
  - Name: <Turn off Entrance Light Switches Scene>
  - Actions:
    - Turn off Entrance Lights Ideal State Switch
    - <Turn off entrance lights>
Add the Entrance Lights Ideal State Switch scenes and automations
1. <Turn on Entrance Light Switches Scene>
  - This is very similar to the <Turn on Entrance Light Switches After Motion Detected Scene> scene, but it doesn't turn on the cooldown switch.
  - Type: Scene
  - Name: <Turn on Entrance Light Switches Scene>
  - Actions:
    - <Turn on entrance lights>
2. <Automation to make the entrance lights match the Entrance Lights Ideal State Switch>
  - This is a complex automation to create. You need to use an advanced HomeKit app (e.g. Eve, Controller for HomeKit) to initially create the automation so that it can have multiple triggers (you can select any existing scene to complete the automation creation). Then you must use the Home app to convert the automation into a shortcut automation.
    - Edit the automation, tap the Select Accessories and Scenes... button, deselect the temporarily selected scene, scroll to the bottom, under the ADVANCED section tap the Convert to Shortcut button, and click the x button to delete the previously selected scene to run.
  - Type: Shortcut Automation
  - Name: <Automation to make the entrance lights match the Entrance Lights Ideal State Switch>
  - Triggers:
    - It is up to you how often you want to run this check. You can take advantage of the Clock virtual switches if you want to trigger this automation every 30-60 seconds.
    - Clock Tick Switch Power Off
    - Clock Tock Switch Power Off
  - Shortcut:
    - Scripting => If
      - If => Input => Select a Home Accessory => Entrance Lights Ideal State Switch Is On
        Create a new action: Control Home => Set '<Turn on Entrance Light Switches Scene>'
        Drag the action to reside between the If and Otherwise sections
      - Otherwise
        Create a new action: Control Home => Set '<Turn off Entrance Light Switches Scene>'
        Drag the action to reside between the Otherwise and End If sections

Unresponsive Device Alarm Accessory

Purpose

Suppose you have one or more battery powered devices. How do you know when their batteries run out of juice? You could open the Home app on a periodic basis and individually check the battery level on each device. What happens if you forget? How much time would pass before you notice a device isn't working? How frustrated would you be when many of your dependant automations fail to get triggered? Wouldn't it be great if an alarm would go off whenever a device becomes unresponsive?

Note: To quickly disable retriggered notifications, turn the alarm state to disarmed via your HomeKit app.

Create an accessory with the following configuration (see 'Add Accessories' steps above):
- switchOneDefaultStateRevertTime should be about one to three minutes longer than the longest span you plan go to between device checks to allow for clock inconsistencies (e.g. if you plan to plan to run checks at 9am and 9pm, you should set it to be 12 hours and 3 minutes)
  - I typically set four checks so that two successive checks must fail in order to trigger the alarm.
- securitySystemOneRetriggerTime should be set to however often you want to be renotified about unresponsive devices.
```
{
  "name": "Unresponsive Battery Accessories Virtual Accessory",
  "switchOneIsCreatable": true,
  "switchOneDefaultStateRevertTime": 43380000,
  "securitySystemOneIsCreatable": true,
  "securitySystemOneRetriggerTime": 300000
},
```
Set the Unresponsive Battery Accessories Virtual Accessory accessory to run a child bridge
- The purpose of setting this accessory to run as a child bridge, per Homebridge: This can improve the general responsiveness and reliability of Homebridge.
1. Log in to your Homebridge deployment and navigate to the Plugins tab
2. Find the plugin card for Homebridge TheNeverStill
3. Click the wrench (🔧) button
4. Click the Bridge Settings dropdown option
5. Toggle on the switch beside the Unresponsive Battery Accessories Virtual Accessory accessory
6. Click the SAVE button
Restart Homebridge
Add the Unresponsive Battery Accessories Virtual Accessory accessory to HomeKit
1. Log in to your Homebridge deployment and navigate to the Plugins tab
2. Find the plugin card for Homebridge TheNeverStill
3. Click the wrench (🔧) button
4. Click the Bridge Settings dropdown option
5. Open your HomeKit app (e.g. Home, Eve, Controller for HomeKit) and add a HomeKit Accessory using the QR code displayed under the Unresponsive Battery Accessories Virtual Accessory accessory
  1. On the Uncertified Accessory prompt click the Add Anyway button
  2. Select or create a room, e.g. Homebridge Room
  3. Name the child bridge, e.g. Unresponsive Battery Accessories Virtual Accessory Bridge
  4. Name the accessory (defined as a switch), e.g. Unresponsive Battery Accessories Virtual Accessory
  5. Name the child devices
    1. e.g. Unresponsive Battery Accessories Canary Switch
    2. e.g. Unresponsive Battery Accessories Security System Switch
    3. e.g. Unresponsive Battery Accessories Security System
    - Test the switches to determine which one natively triggers the security system. You may need to rename them accordingly.
Add the Unresponsive Battery Accessories Virtual Accessory scenes and automations
1. <Turn on Unresponsive Battery Accessories Canary Switch Scene>
  - Type: Scene
  - Name: <Turn on Unresponsive Battery Accessories Canary Switch Scene>
  - Action: Turn on Unresponsive Battery Accessories Canary Switch
2. <Turn on Unresponsive Battery Accessories Security System Switch Scene>
  - Type: Scene
  - Name: <Turn on Unresponsive Battery Accessories Security System Switch Scene>
  - Action: Turn on Unresponsive Battery Accessories Security System Switch
3. <Turn on Unresponsive Battery Accessories Canary Switch Automation>
  - This is a complex automation to create. You need to use an advanced HomeKit app (e.g. Eve, Controller for HomeKit) to initially create the automation so that it can have multiple triggers (you can select any existing scene to complete the automation creation). Then you must use the Home app to convert the automation into a shortcut automation.
    - Edit the automation, tap the Select Accessories and Scenes... button, deselect the temporarily selected scene, scroll to the bottom, under the ADVANCED section tap the Convert to Shortcut button, and click the x button to delete the previously selected scene to run.
  - The way this automation works is that it will timeout if any of the Get State of devices are unresponsive. As such, the final scene will never run which eventually allows the Unresponsive Battery Accessories Canary Switch to revert (which triggers the next automation).
  - Type: Shortcut Automation
  - Name: <Turn on Unresponsive Battery Accessories Canary Switch Automation>
  - Triggers:
    - I typically use four time triggers instead of two to account for miscellaneous HomeKit instabilities. I also pick times where it wouldn't be too disruptive if an alarm goes off.
    - At 8:00 AM Repeat every day
    - At 9:00 AM Repeat every day
    - At 8:00 PM Repeat every day
    - At 9:00 PM Repeat every day
  - Shortcut:
    - Get state of Home => Get 'Accessory A' Characteristic 'Contact Sensor State'
    - Get state of Home => Get 'Accessory B' Characteristic 'Motion Detected'
    - Get state of Home => Get 'Accessory C' Characteristic 'Custom'
    - Control Home => Set 'Turn on Unresponsive Battery Accessories Canary Switch Scene'
4. <Turn on Unresponsive Battery Accessories Security System Switch Automation>
  - Type: Trigger Automation
  - Name: <Turn on Unresponsive Battery Accessories Security System Switch Automation>
  - Trigger: Unresponsive Battery Accessories Canary Switch Power Off
  - Conditions: None
  - Scene: <Turn on Unresponsive Battery Accessories Security System Switch Scene>

Plugin Development

Setup Development Environment

To develop Homebridge plugins you must have Node.js 12 or later installed and a modern code editor such as VS Code.

Install Development Dependencies

Using a terminal, navigate to the project folder and run this command to install the development dependencies:

npm ci

Build Plugin

TypeScript needs to be compiled into JavaScript before it can run. The following command will compile the contents of your src directory and put the resulting code into the dist folder.

npm run build

Link To Homebridge

Run this command so your global install of Homebridge can discover the plugin in your development environment:

npm link

You can now start Homebridge, use the -D flag so you can see debug log messages in your plugin:

homebridge -D

Watch For Changes and Build Automatically

If you want to have your code compile automatically as you make changes and restart Homebridge automatically between changes you can run:

npm run watch

This will launch an instance of Homebridge in debug mode which will restart every time you make a change to the source code. It will load the config stored in the default location under ~/.homebridge. You may need to stop other running instances of Homebridge while using this command to prevent conflicts. You can adjust the Homebridge startup command in the nodemon.json file.