Setting Up the SecuritySystem Type
The SecuritySystem type is a simple device type meant to replicate an interface to an Alarm system. From the iOS side, it allows selection of conventional alarm arming states (Home, Away, Night) as well as an "Off" state, and can set a "Triggered" state when triggered.
The "Home", "Away", and "Night" states correspond to the alarm system being armed, but with different sensors active. Generally, you use "Away" when all the sensors are to be active. For example, "Home" might be used during the daytime, so that door and window sensors are active but motion sensors are not (thus allowing occupants to move around the house, but still securing doors and windows). "Night" is somewhere between "Home" and "Away". You might use this, for example, to turn all the door and window sensors on, as well as motion sensors in some areas active, but leave sensors inactve in bedroom areas so that occupants can move around on a bedroom level of the home. The "Off" state corresponds to the alarm system being "Off". The "Triggered" state corresponds to one or more of your security devices activating when in the Home, Away, or Night modes.
To make use of the SecuritySystem device, you either need (1) to have a plugin in your HomeSeer system which has corresponding Home, Away, Night, Off, and Triggered states, or (2) You will need to (i) create a corresponding Virtual device in HomeSeer with those states and (ii( set up multiple HomeSeer events to detect changes in your sensor devices and then change the state of your HomeSeer virtual device (which will then get reported back to HomeBridge and your iOS device). Both of these are explained, below.
Before adding the SecuritySystem device to your config.json, you will typically need to create a corresponding virtual device in HomeSeer with states corresponding to the iOS "Off", "Night", "Away", "Home", and "Triggered." The rare exception to needing a "virtual" device is if you have a plugin that works with your existing physical alarm system and provides the "Off", "Night", "Away", "Home", and "Triggered" states.
To create a virtual device in HomeSeer, first go to your HomeSeer device home page (Click on "Home" in the HomeSeer web page). Then click on the Add Device symbol (a green "+" in the upper-right area of the HomeSeer device Home page). A new web page with three tabs ("Configuration", "Advanced" and "Status Graphics") will appear and you will then be asked to enter the device's Name. The main configuration takes place in the "Status Graphics" area, so after entering the name, select the Status Graphics tab. On that tab, you will make entries corresponding to the "Off", "Home", "Away", "Night" and "Triggered" states as shown in the graphic, below. You should assign the value of 0 to the "Home" state, 1 to the "Away" state, 2 to the "Night" state, 3 to the "Off" state and 4 to the "Triggered" state as shown in the image below. If you assign any other values, you will need to set many more parameters in your config.json file!
Once you have this set up, you can add the device to your HomeBridge config.json file. Assuming the virtual device was assigned the HomeSeer reference 9999, you would add the following entry in the "accessories" array of your config.json file
{"type":"SecuritySystem", "ref":9999}
Once you've done this and re-started Homebridge, the new device should appear. You can test this by making changes on to the device in iOS or HomeSeer and watching for changes in the corresponding device. If you select the "Triggered" state in HomeSeer, the device should then trigger in iOS
Now that you have the SecuritySystem "virtual" device has been created in HomeSeer and the corresponding device added to homebridge so that it shows in iOS, you need to set up your HomeSeer events to control the state of the HomeSeer Virtual device. Here are some general guidelines.
(This section is a work in progress)
- Add explanation that this event triggers when the "Off" state is selected and should then deactivate any alarms that were set
(This section is a work in progress)
-
Add explanation that when the "Home", "Night" or "Away" states are selected, you should reject the selection and return to the "Off" state if a sensor is currently triggered. For example, you don't want to activate if a door or window are open. This requires some careful event programming as you have to check the sensors when you activate.
-
Add explanation that if setting to "Home", "Night" or "Away" is rejected because a sensor is already triggered, then it is useful to let the user know this. One way to let a user know that the SecuritySystem didn't arm because a sensor was already triggered is to send the user's iOS device a text if this occurs. HomeSeer can send a text via the HomeSeer email function. For example, to send a text to an AT&T subscriber with phone# 2125551212, HomeSeer would send email to the phone number [email protected] saying why the system didn't arm . Most cellular providers have an email domain that can be used for sending text. See, https://www.digitaltrends.com/mobile/how-to-send-a-text-from-your-email-account/. This method of alerting the user may be less effective if the user switches iOS devices (though you could send the text to all the iOS devices!).
-
Add explanation that you may want to use a wait command in the event so that you can open a door and leave the house once the "Away" state is activated. A simpler option is to activate the SecuritySystem for the iOS device after you've left so you don't have to use waits in the setups.
-
Add explanation: A possible solution to fully arming in the "Away" state before you leave home would be to create another virtual device which is a simple switch, let's call it "Fully Armed". Whenever the virtual SecuritySystem device in HomeSeer goes to the "Off" alarm state, an event should activate to turn the "Full Armed" Switch to "Off". Then also create your security system events such that when "Away"is selected, it triggers an event that first checks if any of the sensors are already triggered; if they are, return to the "Off" mode. Otherwise, start a countdown in that event, say 30 seconds using the HomeSeer "wait" event action, and then turn the "Fully Armed" switch to "On". Now, in your sensor events, for the "Armed" state, you no longer check the virtual SecuritySystem device; instead you check this "extra" virtual switch device and you would use the logic ((If fully_Armed is On) and (If sensor is triggered)) then set security system to "Triggered". There are probably other ways to do it, but I think this one is pretty straightforward.
(This section is a work in progress)
-
Add explanation: Set up events to detect if any sensor is activated. If the sensor is activated, then change the state of the HomeSeer virtual SecuritySystem device to "Triggered" but only if the "Home", "Night" or "Away" state was selected. If you have a large number of sensors, this can be some lengthy event processing as you have to set up "Home", "Night" and "Away" groupings. Each of the armed state grouping generally has a large number of event triggers of the form If ((sensor device #1 changes state to alarm) and if (virtual security device is set to "Home")) or if ((sensor device #2 changes state to alarm) andif (virtual security device is set to "Home")) or if ((sensor device #3 changes state to alarm) andif (virtual security device is set to "Home"))
-
Once "Triggered" the SecuritySystem device stays triggered until cleared by selecting "Off" or a triggering state.
(This section is very much a work-in-progress. If you are using a physical alarm system with this device type, and I have't yet finished this section or anything is unclear, then please ask any questions in the "issues" section and I'll turn my attention back to this section.)
If you have a plugin, you may need o set up specific values in your config.json file for the SecuritySystem device parameters listed below.
"armStayValue": 0, // Value sent to HomeSeer to indicate the system should be armed, with people home mode. "armAwayValue": 1, // Value sent to HomeSeer to indicate the system should be armed, with nobody home. "armNightValue": 2, // Value sent to HomeSeer to indicate the system should be armed, night mode. "disarmValue": 3, // Value sent to HomeSeer to indicate the system should be disarmed.
"armedStayValues": [0], // Array of Values reporting system is armed, with people home mode. "armedAwayValues": [1], // Array of Values reporting system is armed, with nobody home. "armedNightValues": [2], // Array of Values reporting system is armed in home mode, night mode. "disarmedValues": [3], // Array of Values reporting system is disarmed. "alarmValues": [4] // Array of Values reporting system is currently in an alarm triggered state.