-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added lock mechanism and plain switch types
All switches can now be stored on disk Improved documentation
- Loading branch information
Showing
19 changed files
with
634 additions
and
129 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| # Automation Switch | ||
|
|
||
| HomeKit (as of iOS 11.1) does not provide a capability to delay the execution of rules. This plugin provides an automation switch that can be used to build a set of rules that are delayed in execution by a configurable period of time on each switch. The period as well as the repetetiveness and the response can be configured via HomeKit (while the configuration provides sane defaults) and can also be changed in response to rules. | ||
|
|
||
| This switch optionally supports being saved to storage on every state change, the switch will save the settings and restore them when homebridge is restarted. | ||
|
|
||
| > Please note that while the plugin works with the Home app, some features, such as dynamic | ||
| > reconfiguration can only be used with other HomeKit apps, such as [Elgato Eve](https://www.elgato.com/en/eve/eve-app). | ||
| ## Appearance | ||
|
|
||
| Each automation switch provides a regular switch, a motion sensor and a configuration service. Activating the switch starts a timer, which will trigger the motion sensor for 1s when the timer elapses. This can be used as a trigger for HomeKit rules. | ||
|
|
||
| The switch support two modes: An automatic shut off mode, where the motion sensor will only be tripped once and the switch is automatically shut off. The other mode is a repeating mode, where the motion sensor will be tripped repeatedly until the switch is shut off again. | ||
|
|
||
|  | ||
|
|
||
| (Screenshot: Elgato Eve) | ||
|
|
||
| ## Configuration | ||
|
|
||
| ```json | ||
| { | ||
| "bridge": { | ||
| ... | ||
| }, | ||
| "platforms": [ | ||
| { | ||
| "platform": "AutomationSwitches", | ||
| "switches": [ | ||
| { | ||
| "type": "automation", | ||
| "name": "Automation Switch #1", | ||
| "period": 1800, | ||
| "autoOff": false | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| ## Options | ||
|
|
||
| | Attributes | Required | Usage | | ||
| |------------|----------|-------| | ||
| | type | Yes | Set this to ```automation``` to make this entry an automation switch. | | ||
| | name | Yes | A unique name for the automation switch. Will be used as the accessory name. | | ||
| | period | Yes | The default time delay of the switch in seconds, before the sensor is triggered. | | ||
| | autoOff | Yes | Set this to ```true``` to automatically turn the switch off after the period has expired once, ```false``` to keep the triggering the sensor until it has expired. | | ||
| | default | No | Specifies the default state of the switch. This is used if the switch is not yet stored, not stored or the storage has become faulty. The default state is ```false``` if not specified, which means the switch is off. Setting this to ```true``` turns the switch on by default. | | ||
| | stored | No | Set this to true if you want the switch to retain its on/off state across restarts. The default setting for the ```switch``` type is ```false```. | | ||
|
|
||
| See [configuration](Configuration.md) for more advanced configuration examples. | ||
|
|
||
| ## Usage | ||
|
|
||
| This type of switch is best used if you need to delay the execution of a scene or if you need to execute the scene multiple times until something else has happened. | ||
|
|
||
| I personally have used this to send me notifications until I close the bathroom window, reminding me every 10 minutes that the window is open and I might freeze to the toilet seat. For that I combine this switch type with my [homebridge-telegram](https://www.npmjs.com/packages/homebridge-telegram) plugin. (Shameless plug.) | ||
|
|
||
| ## Notes | ||
|
|
||
| ### Stored switch states | ||
|
|
||
| This switch has logic, which is tied to the state of the switch (e.g. 'On' or 'Off'.) The initial state of the switch is determined either by the "default" field in the configuration or by the value saved just before homebridge terminated the last time. | ||
|
|
||
| If the initial value is `true` the timer controlled by the switch will immediately start as soon as the plugin is initialized. This can also serve to delay initialization just after homebridge has been loaded. | ||
|
|
||
| ### Editing the timeout period | ||
|
|
||
| If the automation switch was stored the default period from the configuration file is also not used any longer. To edit the timeout in those cases, either edit the file that belongs to the switch (located in your homebridge configuration directory under the persist folder) or delete it and then edit the default again. |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| # Advanced configuration | ||
|
|
||
| The following configuration example shows all switches in combination. The configuration was used to make the screenshots in the detailed documentation pages. The configuration shows examples of the | ||
| [automation switch](AutomationSwitch.md), the [lock mechanism](LockMechanism.md), the [security system](SecuritySystem.md) and the regular [switch](Switch.md). | ||
|
|
||
| ## Example | ||
|
|
||
| ```json | ||
| { | ||
| "bridge": { | ||
| ... | ||
| }, | ||
| "platforms": [ | ||
| { | ||
| "platform": "AutomationSwitches", | ||
| "switches": [ | ||
| { | ||
| "type": "automation", | ||
| "name": "WindowOpenAlert", | ||
| "period": 600, | ||
| "autoOff": false, | ||
| "stored": false | ||
| }, | ||
| { | ||
| "type": "automation", | ||
| "name": "AutoOff", | ||
| "period": 900, | ||
| "autoOff": true, | ||
| "stored": false | ||
| }, | ||
| { | ||
| "type": "lock", | ||
| "name": "ScreenLock", | ||
| "default": "unlocked", | ||
| "stored": true | ||
| }, | ||
| { | ||
| "type": "security", | ||
| "name": "Home Mode", | ||
| "default": "armed-stay", | ||
| "stored": true | ||
| }, | ||
| { | ||
| "type": "security", | ||
| "name": "My DIY security system", | ||
| "default": "unarmed", | ||
| "stored": true | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| # Custom services and characteristics | ||
|
|
||
| Most of the switch types provided by this plugin use standard HomeKit characteristics. In some cases there was no way (or it made no sense) to bend the standard services/characteristics to enable the use cases supported by this plugin. | ||
|
|
||
| All custom services and characteristics used are listed below. | ||
|
|
||
| ## Custom characteristics | ||
|
|
||
| All custom characteristics are defined in [HomeKitTypes.js](../src/HomeKitTypes.js). | ||
|
|
||
| ### Custom automation switch characteristics | ||
|
|
||
| The automation switch provides a programming service, which allows dynamic changes to the time period between triggers and also control of the automatic shut off. These characteristics can be used in scenes to change the default behavior of the switch. | ||
|
|
||
| | Characteristic | UUID | Service | Permissions | Usage | | ||
| |---|---|---|---| | ||
| | Period | `B469181F-D796-46B4-8D99-5FBE4BA9DC9C` | READ, WRITE | `FD92B7CF-A343-4D7E-9467-FD251E22C374` | The period of the switch in seconds. This value can be changed between 1s and 3600s. A change will only take effect the next time the switch is turned on. | | ||
| | AutomaticOff | `72227266-CA42-4442-AB84-0A7D55A0F08D` | `FD92B7CF-A343-4D7E-9467-FD251E22C374` | READ, WRITE | Determines if the switch is shut off after the period has elapsed. If the switch is not automatically shut off, the timer will be restarted and the motion sensor will be triggered again until the switch is shut off externally. | | ||
|
|
||
| Both of these characteristics are provided on the custom SwitchProgramService. | ||
|
|
||
| ### Custom security system characteristics | ||
|
|
||
| The security system provides an additional characteristic to trigger the Alarm state: | ||
|
|
||
| | Characteristic | UUID | Service | Properties | Description | | ||
| | Alarm | `72227266-CA42-4442-AB84-0A7D55A0F08D` | `0000008E-0000-1000-8000-0026BB765291` | READ, WRITE, EVENTS | This characteristic enables the triggering of an alarm. Can also be used for additional rules. | | ||
|
|
||
| This characteristic is provided as an extension on the standard security system service. | ||
|
|
||
| ## Services | ||
|
|
||
| Each switch created by this accessory will provide the standard HomeKit services: | ||
|
|
||
| - AccessoryInformation service | ||
| - BridgingState service | ||
|
|
||
| ### Automation switch | ||
|
|
||
| The automation switch additionally provides: | ||
|
|
||
| - Switch service | ||
| - MotionSensor service | ||
| - SwitchProgram service (see above) | ||
|
|
||
| ### Lock mechanism | ||
|
|
||
| The lock mechanism service provides: | ||
|
|
||
| - LockMechanism service | ||
|
|
||
| ### Security system | ||
|
|
||
| The security system switch provides: | ||
|
|
||
| - SecuritySystem service | ||
|
|
||
| ### Switch | ||
|
|
||
| - Switch Service |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| # Lock mechanism | ||
|
|
||
| This switch type represents a lock. A lock can be locked or unlocked and changing the state of the lock triggers built-in HomeKit notifications. Use it for things that can best be simulated by a lock. | ||
|
|
||
| ## Appearance | ||
|
|
||
| The lock mechanism only provides means to lock/unlock via specifically labelled buttons. | ||
|
|
||
|  | ||
|
|
||
| (Screenshot: Elgato Eve) | ||
|
|
||
| ## Configuration | ||
|
|
||
| ```json | ||
| { | ||
| "bridge": { | ||
| ... | ||
| }, | ||
| "platforms": [ | ||
| { | ||
| "platform": "AutomationSwitches", | ||
| "switches": [ | ||
| { | ||
| "type": "lock", | ||
| "name": "My simulated door lock", | ||
| "default": "unlocked", | ||
| "stored": false | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
|
|
||
| ## Options | ||
|
|
||
| | Field | Required | Description | | ||
| |---|---|---| | ||
| | type | Yes | Set this to ```lock``` to make this entry a lock mechanism. | | ||
| | name | Yes | Set this to the name of the lock as you want it to appear in HomeKit apps. | | ||
| | default | No | This configures the default state of the lock if it is not yet stored, never stored or the storage has become faulty. Set this to ```unlocked``` or ```locked``` depending on your needs. By default a lock is ```unlocked``` if this is not specified. | | ||
| | stored | No | Set this to true if you want the lock to retain its locked/unlocked state across restarts. The default setting for the ```lock``` type is ```false```. | | ||
|
|
||
| See [configuration](Configuration.md) for more advanced configuration examples. | ||
|
|
||
| ## Usage | ||
|
|
||
| This type is best used to simulate a physical lock or things that are best described by a lock. An example use case for the lock is in conditions for HomeKit rules and thus use it to enable or disable the rules based on other conditions. | ||
|
|
||
| ## HomeKit Notifications | ||
|
|
||
| HomeKit, by default, enables notifications for lock mechanisms. Once enabled you automatically get built-in notifications for this lock too. You can disable these notifications in the Home.app if you do not care for the notifications. To disable/enable the notifications, open the Home app, select the tile that represents the lock and long-press on it, choose Details and scroll down until you get to Notifications. You can disable them there. | ||
|
|
||
| There's unfortunately no way to change the notification text in HomeKit. If you're looking for something to send customized notifications I'd recommend one of the [IFTT plugins](https://www.npmjs.com/search?q=homebridge+ifttt) or my [homebridge-telegram](https://www.npmjs.com/packages/homebridge-telegram) plugin (shameless plug.) |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.