Rooms Occupancy and Rooms Manager
While ST has a concept of rooms it is essentially a grouping mechanism which does not enable personalized automation. In contrast rooms occupancy considers the room as a meta device and automates common tasks associated with a “room” physical or virtual. What makes it really useful is not just the room's occupancy state but the ability to manage automation for rooms in a set of rules for the room based on the occupancy state of the room and data from various sensors. When creating a room device through the smartapp you are able to create these rules for the rooms making your rooms really smart.
What these rules enable is many common tasks around rooms which most users go through automating at some point. Usually through setting up a few rules or creating a few pistons. I have been there and done that myself. While those work to a degree, it does not enable the kind of comprehensive automation that should be possible for devices in a room based on sensor and device inputs. This smartapp makes that possible.
If there is one principle that these apps are built on, it is - that your home automation should work in the background in a repeatable and predictable manner without requiring periodic human intervention. In short - your automation should work for you and not the other way around. But even more importantly perhaps, this app gets you the kind of WAF for your home automation that you have always dreamed about. 🙂
You can continue reading here for the summarized version or read the more detailed and always the latest version on Github which also describes the individual settings:
Rooms Manager and Rooms Occupancy readme on Github
Additionally, these room devices also have attributes, capabilities and commands which are useable in webCoRE or other smartapps like Smart Lighting in ST or Rule Machine in Hubitat. There is a range of other automations that webCoRE makes possible that could not otherwise be done without writing a custom smartapp for it. I use webCoRE for that and am I big fan of Adrian. So checkout webCoRE as well if you don't already use it.
How does this app work?
This app works by setting rooms occupancy to various states based on a set of sensors as specified by the user. It takes this state and attribute values from various sensors and evaluates a set of rules that you create to match the conditions. When all of the conditions for the rule matches, it executes actions specified on these matching rules.
As an example, you can specify motion sensors in Occupied settings to set a room state to Occupied when there is motion from any of those motion sensors. Then create a rule to turn on some lights. In this rule you could also set that these lights should only be turned on if a lux sensor is at a certain lux value or lower. Or you could specify that only turn on the lights during certain times. Or you could specify turn on the lights at a certain level during certain times and at another level during other times.
As a part of the Occupied settings you can also specify timeout values so the room does not indefinitely stay set to Occupied state and the lights turn off after a while when there is no motion. How quickly that happens is controlled by you through the timeout value you specify in the settings. By specifying settings in the Checking settings you are also able to dim the lights before the lights turn off completely so there is a visual cue to the room occupant that the lights will turn off because they have not moved in a while.
Off course you may be in the room while and not be moving for a while like reading a book or watching TV. That's when you use the Engaged settings to set the room to Engaged state. See below for additional details.
Here are the common room occupancy states:
-
Occupied:
-
Engaged:
-
Asleep:
-
Vacant:
-
Checking:
-
Locked:
Occupied is you go to a room are in there for a few minutes then leave the room. Lights come on when you enter the room and turn off after a couple of minutes of your leaving the room. Think of Occupied as a transient state and Engaged below as a somewhat persistent state.
Engaged is when you stay in a room for an extended period of time and may be motionless for some or all of the time. since we cant depend on the motion event for engaged state there are different options to set the room to engaged for extended occupancy. these are all under engaged settings and there is more coming. but these help make sure the switches you set to on stay on even if there is no motion in the room. When in Engaged state you have a different and longer timeout state than the Occupied state. So there is still a motion requirement but a much higher time threshold than the Occupied state.
Asleep state is meant for use while the room should be 'asleep' as in not respond to most typical automation like motion automation. But it does allow for other automation like using a night light and using a button to turn on or off the night lights. You are still able to create rules for the Asleep state but it additionally support a little bit for Asleep state specific automation in the Asleep settings.
Vacant state is for when the room is vacant and you want everything to get turned off. It is possible to setup rules for Vacant settings as well but not required.
Checking state is used for transition between states and not user controlled. For example, when moving from Occupied to Vacant occupancy state the room will transition to Checking state. While the app does not allow creating rules for checking state there is some settings available to control dimming of the lights when in Checking state.
Locked state disables all automations for the room and allows you to control lights and other devices in the room either manually or some other way.
The states 'locked', 'reserved', 'kaput' and 'donotdisturb' are effectively all similar in that they all disable automation. That being the case there is some sensors allowed to set / unset rooms to / from Locked state but no other automation beyond that for these occupancy states. Here is a quick description of the various top level settings and how the app works. At the heart of the app is the concept of room states and rules to automate devices based on these room's states and other sensor inputs. (In the following description when I talk about sensors it refers to devices that have attributes which are used to drive decisions in the room's rules.)
Note many of these settings are optional but when specified will require other settings to be specified. Like specifying a motion sensor is optional. But if you do specify a motion sensor the motion event to trigger timeout countdown becomes required.
Top level settings:
Room Devices
Room sensors used in checking rule conditions based occupancy state and data from these sensors.
The next 6 settings group are for how the room is set to each of those 6 occupancy states and settings specific to that occupancy state.
Occupied Settings
Engaged Settings
Vacant Settings
Asleep Settings
-
Night lights:
Settings for night lights with motion while in Asleep state.
Locked Settings
Settings that specify how this occupancy state is set. Normally it is based on motion but there are also other ways of detecting Occupied state like a specific switch turning on. Available settings:
Settings that specify how this occupancy state is set. Normally it is based on motion but there are also other ways of detecting Engaged state like a button being pressed.
Settings that specify how this occupancy state is set. Normally it is based on motion but there are also other ways of detecting Occupied state like a specific switch turning off.
Settings that specify how this occupancy state is set. Asleep is tricky because there is no true commonly used physical asleep sensors. So, these settings allow other ways of setting Asleep occupancy state and specifying night light settings which are a little different from how lights work through the rules.
Settings that specify how this occupancy state is set. This state disables all automation for the room.
These group of settings allow for light routine settings used in the rules.
Auto Level 'AL' Settings
Holiday Lights 'HL' Settings
Settings to specify auto level and color temperature settings for the room which allows using 'AL' as a light level rule to automatically calculate and use these values based on time of day, wake and sleep time specified.
Settings to specify holiday light patterns for use in rules during various holiday seasons. Allows for rotating colors through or slow twinkling any set of lights specified in the rules.
Temperature settings is their own group.
Temperature Settings
Manage temperature settings for the room in conjunction with thermostat or switch controlled room AC and/or heater. After adding temperature settings remember create temperature rules in maintain rules so the app can automate temperature control based on these rules.
Here are the rest of the settings starting with the heart of the app - Maintain Rules, which allows you to maintain automation rules for the room and turn them in to smart rooms.
Maintain Rules
Adjacent Room Settings
Mode and Other Settings
View All Settings
Here's where to create the rules that check room occupancy state, various sensor values and other variables to decide which lights and switches should be turned on or off. It also allows executing a piston or routine or even starting and stopping a music player based on the rules.
While date acts a filter when checking rules for match, time works as a trigger. So, if you wanted your outdoor lights to turn on and off at certain times everyday you would create 1 rule with those times and lights to turn on and off at right times. You could also use this feature in combination with date filtering and with or without Holiday Light 'HL' settings above for different color settings for different holidays.
Adjacent rooms allow specifying which rooms are adjacent to that room so you can automatically turn on lights in the next room when moving through this room.
Miscellaneous settings that don't fit any where else, like in which modes should all automation be disabled or what icon to use for the room in the rooms manager and a few other settings.
What the name says.
This only describes a part of what's possible through this app. For more details please see each group of settings for a room in the see wiki here:
http://thingsthataresmart.wiki/index.php?title=Rooms_Occupancy
For a github install from repo in ST use : owner: adey / name: bangali / branch: master. Install and publish the rooms occupancy DTH then install and publish the rooms manager and rooms child app smartapps.
For a manual install here are the links, in order of DTHs and smartapps you should save and publish.
rooms occupancy DTH:
rooms manager smartapp:
rooms child smartapp:
Then go to ST app -> Automation tab -> Add a Smartapp -> My apps in ST app and install rooms manager app then create your rooms within rooms manager.
When creating a room first give the room a name and save the room then go back in to the room to add various settings to the room. This is because the app uses app state to manage the rules and in ST the app state is not consistent till the app has been saved once.
Like the rooms app and want to contribute? Here are some options:
- Like this post to help other users find this app
- Submit a feature request on this thread or by creating an issue on Github
- Submit a bug for something that is not working quite right here or on Github
- Donate to support development of the app: donate here.
old explanation of settings
while ST has a concept of rooms it seems to be more of a grouping mechanism. in contrast rooms occupancy considers the room as a meta device and automates a few common tasks associated with a “room” physical or virtual. in keeping with that it has attributes, capabilities and commands which are useable in webcore or other smartapps like Smart Lighting.however, what makes it useful for me is not just the room’s state but the abiloty to manage automation for room in one set of settings for the room. when adding a room device through the smartapp you are able to configure settings for the room which allow the various devices in the room to be automated based on these settings.
heres an detailed settings post that @johhnwilliam put together. much better than i had 
a quick note on occupied and engaged states. think of occupied as a transient state and engaged as a persistent state.
occupied is you go to a room are in there for a few minutes then leave the room. lights come on when you enter the room and turn off after a couple of minutes of your leaving the room.
engaged is when you stay in a room for an extended period of time and may be motionless for some or all of the time. since we cant depend on the motion event for engaged state there are different options to set the room to engaged for extended occupancy. these are all under engaged settings and there is more coming. but these help make sure the switches you set to on stay on even if there is no motion in the room.
when in engaged state you have a different and longer timeout state than the occupied state. so there is still a motion requirement but a much higher time threshold than transient occupied state.
for example in settings:
- if away modes are selected, rooms will change to ‘vacant’ state if they are in either the ‘occupied’ or ‘checking’ state when location changes to any of the away modes.
- if motion sensors are selected, rooms will change to ‘occupied’ state on motion if they were previously ‘vacant’.
- if switches are selected, when room changes to ‘occupied’ the switches will be turned on.
- if motion timeout in seconds is selected the room will be changed to ‘vacant’ after last motion inactive + motion timeout seconds.
- if 2nd group of switches are selected, when room changes to ‘vacant’ the switches will be turned off.
- this is only a part of what’s possible. please take a look at the settings for a room in the child-app that captures all of these settings to get a sense of what else is possible.
these are very common tasks around rooms which most users go through automating at some point, so also posting here in case others find this useful.
for a github install use : owner: adey / name: bangali / branch: master
UPDATE: updated version 0.14.0 to github with the following changes:
* Version: 0.14.0
*
* DONE: 2/25/2018
* 1) update device tiles to be more verbose.
UPDATE: updated version 0.12.0 to github with the following changes:
* Version: 0.12.0
*
* DONE: 2/8/2018
* 1) added alarm to rooms occupancy. tested somewhat. family kind of upset with me for random alarms going off :-(
* 2) sunrise & sunset now support offset in minutes. so if you always wanted sunrise -30 or sunset +30 now you can.
* Version: 0.11.5
*
* DONE: 2/5/2018
* 1) added setting for locked state timeout setting.
* 2) on motion active added check for power value to set room to engaged instead of occupied.
* 3) on occupied switch check power value to set room to engaged instead of occupied.
* 4) on contact close check for both occupied and checking state to set room to engaged.
* 5) for motion inactive with multiple motion sensors check all sensors for active before setting timer.
UPDATE: updated version 0.11.0 to github with the following changes:
* Version: 0.11.0
*
* DONE: 2/1/2018
* 1) added support for time announce function. straightforward annoucement for now but likely to get fancier ;-)
* 2) added rule name to display in rules page.
* 3) added support for power value stays below a certain number of seconds before triggering engaged or asleep.
* 4) added support for vacant switch. except this sets room to vacant when turned OFF not ON.
* 5) changed speaker device to music player in the rooms setup.
* 6) added support in rules to control window shade.
UPDATE: updated to github with the following changes:
* Version: 0.10.7
*
* DONE: 1/26/2018
* 1) added support for switch to set room to locked.
* 2) added support for random welcome home and left home messages. multiple messages can be specified delimited
* by comma and one of them will be randomly picked when making the annoucement.
* 3) added support for switch to set room to asleep.
*
* Version: 0.10.6
*
* DONE: 1/24/2018
* 1) added support for power value to set room to asleep.
*
* Version: 0.10.5
*
* DONE: 1/23/2018
* 1) added rules support for maintaining temperature.
*
UPDATE: updated version 0.10.0 to github with the following changes:
* Version: 0.10.0
*
* DONE: 1/18/2018
* 1) added one page easy settings for first time users.
UPDATE: updated version 0.09.9 to github with the following changes:
* Version: 0.09.9
*
* DONE: 1/14/2018
* 1) added variable years to date filter.
UPDATE: updated version 0.09.8 to github with the following contribution from @TonyFleisher:
* Version: 0.09.8
*
* MERGED: 1/12/2018
* 1) added switches for occupied state and corresponding settings by https://github.com/TonyFleisher.
UPDATE: updated version 0.09.7 to github with the following changes:
* Version: 0.09.7
*
* DONE: 1/11/2018
* 1) addeed night switches control from device tiles indicators
* 2) added setting to keep room in engaged state based on continuous presence and not just presence change.
* 3) refactored how another room engaged works and checks for continuous presence before reseting room state.
// TODO
* 4) added resetting of asleep state to engaged state reset. will probably make that an option later.
// TODO
* 5) started work on adding thermostate to maintain room temperature. going to change this to use rules
* which will require a significant change to how rules work so wanted to push everything else out before
* starting the work to change maintain room temperature to use rules.
* 6) added another optimization when getting rules to allow getting conditions only.
* 7) move is busy check to motion handler instead of downstream.
* 8) added multiple rule processing with the following evaluation logic:
* a) if matching rules have no lux and no time all of those rules will be executed.
* b) if matching rules has lux the rule with the lowest lux value < current lux value will be
* executed. if there are multiple matching rules with the same lux value all of them will be executed.
* c) if matching rules has time all rules that match that current time will be executed.
* d) if matching rules have lux and time the rule with the lowest lux value < current lux value and
* matching time will be executed. if there are multiple matching rules with the same lux
* value and matching time all of them will be executed.
* 9) timer indicator now uses minutes when time is over 60 seconds.
* 10) fixed a few small bugs here and there.
note the todos.
UPDATE: updated version 0.09.4 to github with the following changes:
* Version: 0.09.4
*
* DONE: 12/30/2017
* 1) updated device tiles layout and added a bunch of indicators.
* 2) added checking state to room busy check.
last release of 2017 … happy new year everyone!
UPDATE: updated version 0.09.2 to github with the following changes:
* Version: 0.09.2
*
* DONE: 12/25/2017
* 1) added option to temporarily override motion timers with rules.
* 2) added support for button to set room to asleep.
* 3) added checks for interval processing of rules.
* 4) some optimizations and bug fix.
UPDATE: updated version 0.09.0 to github with the following changes:
* Version: 0.09.0
*
* DONE: 12/23/2017
* 1) added color coding for temperature indicator. since ST does not allow device handler display to be conditional
* for celcius color coding user will need to edit the DTH and uncomment the celcius section and comment the
* Fahrenheit values.
* 2) added support for room AC and heater support to maintain room temperature. support for thermostat is coming.
* 3) moved all stanalone devices to their own settings page.
* 4) added setting to indiciate if contact sensor is on inside door or outside. e.g. contact sesnor on garage door
* would be an outside door contact sesnor. this reverses the occupancy logic so when contact sensor is open
* the door is engaged or occupied instead of when the door is closed.
* 5) added support for button to set room to vacant.
* 6) moved webCoRE_init call to the bottom of the updated() method.
* 7) couple of bug fixes.
UPDATE: updated version 0.08.6 to github with the following changes:
* Version: 0.08.6
*
* DONE: 12/17/2017
* 1) added support for variable text for arrival and departure announcements.
* 2) added support for power level to set room to engaged.
UPDATE: updated version 0.08.5 to github with the following changes:
* Version: 0.08.5
*
* DONE: 12/16/2017
* 1) added support for arrival and departure announcement.
* 2) added support for speaker control through rules and use of speaker to set a room to engaged.
* 3) bug fix to stop truncating temperature to integer.
UPDATE: updated version 0.08.3 to github with the following changes:
* Version: 0.08.3
*
* DONE: 12/12/2017
* 1) added support for wake and sleep times to calculate level and color temperature.
* 2) add support to process rules every 15 minutes so switches state/level/color temperature is updated.
* 3) fix for continuous motion with motion sensor.
UPDATE: updated version 0.08.1 to github with the following changes:
* Version: 0.08.1
*
* DONE: 12/10/2017
* 1) added support for auto level which automatically calculates light level and optionally color temperature to
* to be set based on local sunrise and sunset times. this does not yet use circadian rhytym based calculation.
UPDATE: updated version 0.07.5 & 0.08.0 to github with the following changes:
* Version: 0.08.0
*
* DONE: 12/8/2017
* 1) added support to reset room state from ENGAGED or ASLEEP when another room changes to ENGAGED or ASLEEP
* 2) added support to reset room state when another room changes to ENGAGED or ASLEEP.
* 3) removed lux threshold support from main settings since this is now available under rules.
* 4) fixed presence indicator for device display.
* 5) added support for multiple engaged switches.
* 6) added undimming for lights.
* 7) added support for centigrade display.
* 8) added support for multiple presence sensors.
* 9) couple of bug fixes.
*
* Version: 0.07.5
*
* DONE: 12/5/2017
* 1) added support to reset room state from ENGAGED or ASLEEP when another room changes to ENGAGED or ASLEEP
* 2) added right temperature scale support
* 3) fixed couple of bugs
* 4) added support for date filtering in rules
UPDATE: updated version 0.07.3 to github with the following changes:
* Version: 0.07.3
*
* DONE: 12/2/2017
* 1) added support for executing piston instead of just turning on a light
* 2) added view all settings
* 3) added room device indicators to the room device so they can be seen in one place
* 4) added timer to room which counts down in increments of 5
* 5) some bug fixes
UPDATE: updated version 0.07.0 to github with the following changes:
* Version: 0.07.0
*
* DONE: 11/27/2017
* 1) instead of adding swtiches to individual settings created rules to allow switches to be turned on and off
* and routines to be executed via this rule. VACANT state automatically turns of the switches the last rule
* turned on unless user creates a rule for VACANT state in which case the automatic turning off of switches
* on VACANT state is skipped instead the rules are checked and executed for the VACANT state.
* 2) some bug fixes.
the rules create much more flexibility in when switches are turned on and off or routines are run controlled by these rules.
before creating rules please give the room a name and save it. then go back in to the room and edit the rules. the rules use the app state and without the room created the app state is not available to the app for use.
UPDATE: updated version 0.05.8 & 0.05.9 to github with the following changes:
if you are using Rooms Occupancy with say wC note that “occupancyStatus” is now called “occupancy”. there is no impact if used from ST app only. sorry for the breaking change.
* Version: 0.05.9
*
* DONE: 11/21/2017
* 1) changed name of 'occupancyStatus' to just 'occupancy' to be consistent with ST.
* 2) added switches to turn on and off when room changes to asleep. switches set to turn on are also turned off
* when room changes away from asleep.
* 2) some bug fixes.
*
* Version: 0.05.8
*
* DONE: 11/20/2017
* 1) Changed configuration pages
UPDATE: updated version 0.05.7 to github with the following changes:
* Version: 0.05.7
*
* DONE: 11/20/2017
* 1) added support for room busy check.
* 2) added support for arrival and/or departure action when using presence sensor.
* 3) some bug fixes.
UPDATE: updated version 0.05.5 to github with integration for sleep sensor contribution by @johhnwilliam:
* Version: 0.05.5
*
* DONE: 11/19/2017
* 1) added sleepSensor feature and corresponding settings by https://github.com/Johnwillliam
* 2) some bug fixes.
@johhnwilliam will probably add more details about the sleep sensor integration when he is back from his sleep. 
awesome to have @johhnwilliam contributing to the project!
UPDATE: updated version 0.05.1 to github with the following changes:
* Version: 0.05.1
*
* DONE: 11/15/2017
* 1) added setting to select which days of week this rooms automation should run.
UPDATE: updated version 0.05.0 to github with the following changes:
* Version: 0.05.0
*
* DONE: 11/13/2017
* 1) expanded the adjacent room settings. if you specify adjacent rooms you can choose 2 options:
* i) if there is motion in an adjacent room you can force the current room to check for motion and on no
* motion change room state to vacant.
* ii) if there is motion in an adjacent room you can turn on lights in this room if it is currently vacant.
* this allows for the adjacent rooms feature to be used as a light your pathway can kind of setup.
* 2) some bug fixes.
UPDATE: updated version 0.04.5 to github with the following changes:
* Version: 0.04.5
*
* DONE: 11/10/2017
* 1) revamped device details screen. if users dont like it will revert back.
* 2) when swiches are turned off because lux rose or is outside of time window added settings to turn off both
* group of switches instead of just switches off.
* 3) added option to change state directly from engaged to vacant without moving to checking state.
* 4) removed last event from status message.
UPDATE: updated version 0.04.3 to github with the following changes:
* Version: 0.04.3
*
* DONE: 11/8/2017
* 1) added last event to status message.
* 2) added concept of adjacent rooms that you can select in room settings. setting does not do anything yet :-)
UPDATE: updated version 0.04.2 to github with the following changes:
* Version: 0.04.2
*
* DONE: 11/6/2017
* 1) added setting option to allow timeout from last motion active or on motion inactive. if motion has a long timeout
* this will allow the lights to turn off quicker. but be aware motion sensor may show motion due to long
* timeout while room indicates its vacant.
UPDATE: updated version 0.04.1 to github with the following changes:
* Version: 0.04.1
*
* DONE: 11/5/2017
* 1) added support for time window to turn on/off switches when between those times. this works with other settings
* as well. like if lux is specified both the lux setting and the time setting have to be true for switches
* to be turned on or off.
*
UPDATE: updated version 0.04 to github with the following changes:
* Version: 0.04
*
* DONE: 11/3/2017
* 1) added support for presence sensor to change room state to engaged when present. when presence sensor is not
* present the room automation should work normally.
* 2) added support for modes which when set cause all automation to be bypassed if location is any of those modes.
*
* Version: 0.03.7
*
* DONE: 11/1/2017
* 1) added support for contact sensor. when contact sensor changes to closed room will be set to checking state.
* if there is no motion afterwards room will be set to vacant. if there is motion, room will be set to
* engaged which stops room automation from kicking in till the contact is opened again.
* when contact sensor changes to open room will be set to checking state so automation can resume again.
* the only exception to this is home changing to away in which case room will be set to vacant.
* 2) when contact sensor is specified but no motion sensor is specified room will be changed to engaged when
* contact sensor closes.
* 3) if there is a motion sensor specified but no motion timeout value then room will be changed to vacant when
* motion sensor becomes inactive and room is in occupied or checking state.
* 4) added engaged switch which when turned on will mark the room as engaged to stop automation. this gets a
* little tricky when both engaged switch and contact sensor is defined. the contact sensor changing to
* open will reset the state back to checking. but if there is subsequent motion in the room within the
* timeout period the room will be set to occupied. or if the door is closed again and there is subsequent
* motion in the room within the timeout period the room will be set to engaged stopping automation.
* 5) added lights control with lux for engaged state.
* 6) added button push to toogle room state to engaged or checking when room state is already engaged.
**see below for github details.**
UPDATE 10/31/17:
heres a few things i have added to the DTH/smartapp since i posted this. feedback welcome.
* Version: 0.03.5
*
* DONE: 10/29/2017
* 1) added support for setting level and/or color temperature for turning on switches. these will be set for
* those devices in the turn on switchs list that support it.
* 2) since motion inactive timeout can vary so widely amongst different brands of motion sensors chose not to
* use motion inactive event and instead timeout on motion active event for predictable user experience.
* 3) added support for dimming before turning off light.
* 4) added support for color setting which takes preference over color temperature if the switch supports it.
* 5) fixed small bugs.
*
* Version: 0.03.1
*
* DONE: 10/27/2017
* 1) added support for lux sensor and lux value. if these values are specified:
* a) if lux value falls <= that value and switches on are selected those switches will be turned on.
* b) if lux value rises > that value and switches off are selected those switches will be turned off.
* c) switches on with motion will be turned on only when lux value is <= that value.
* 2) fixed small bugs.
*
===================================================================================
cross post from examples category if anybody else wants to try it for other use cases:
