-
Notifications
You must be signed in to change notification settings - Fork 130
Occupancy_Monitor
Counts the number of people in a network of motion sensors and, with the use of Presence_Items, can keep track of the occupancy state of each room.
The old method of calling set_fp_nodes() on each sensor object has been deprecated. For the time being, as long as you call set_fp_nodes() on the object BEFORE you add() it to the occupancy monitor, the nodes will be properly transferred.
In addition, where in the past you added the actual sensors to the occupancy monitor, now you only add the Door_Item and Motion_Item objects.
Please switch to the new method ASAP.
In a .mht file
X10MS, B13, x10_example_motion_detector, , MS13
MOTION, x10_example_motion_detector, example_motion_detector
OCCUPANCY, om
PRESENCE, x10_example_motion_detector, om, presence_example_roomIn a .pl file:
$x10_example_motion_detector->set_fp_nodes(1, 2, 3);
$om->add($x10_example_motion_detector);In a .mht file:
X10MS, B13, x10_example_motion_detector, , MS13
MOTION, x10_example_motion_detector, example_motion_detector
OCCUPANCY, om
PRESENCE, example_motion_detector, om, presence_example_roomIn a .pl file:
$om->set_edges($example_motion_detector, 1, 2, 3);The differences here are:
- In the new method,
x10_example_motion_detectoris only used to create theexample_motion_detectorobject. After that it is not used in any occupancy code. This means you'll have to change all the entries for PRESENCE objects in your .mht files to refer to the Motion_Item and not the original sensor. -
set_edges()is called on the occupancy monitor and the Motion_Item is passed in as the first argument. This is done instead of callingset_fp_nodes()on the original sensor.
Note that calling add() is no longer necessary if you call set_edges(), but won't hurt anything.
Example initialization:
use Occupancy_Monitor;
$om = new Occupancy_Monitor();Draw up a diagram of house rooms and number the connected rooms passageways add the sensors and their connections in the example as follows. So, if you have a motion detector in a hallway connected to two rooms, it would have two edges, one each for the boundry between the hallway and each room.
$om->set_edges($garage_motion, 1);
$om->set_edges($garage_hall_motion, 1, 2);
$om->set_edges($basement_motion, 2);
$om->set_edges($kitchen_motion, 2, 3);
$om->set_edges($family_motion, 3, 4);
$om->set_edges($foyer_motion, 4, 5, 6);
$om->set_edges($living_motion, 2, 5);
$om->set_edges($den_motion, 6, 7);
$om->set_edges($hall_motion, 4, 7, 8, 9);
$om->set_edges($robert_bedroom, 8);
$om->set_edges($celine_bedroom, 9, 10);
$om->set_edges($master_bedroom, 9, 11);You can have more than one motion detector and/or door in the same room, just be sure to set the same edges on each detector.
$garage_door_switch->tie_items($om,'off','reset');
$utility_door_switch->tie_items($om,'off','reset');
$patio_door_switch->tie_items($om,'off','reset');
$front_door_switch->tie_items($om,'off','reset');
$om->tie_event('info_monitor($state, $object)');
sub info_monitor
{
my ($p_state, $p_setby) = @_;
if ($p_state =~ /^min/ or $p_state=~ /^last/){
print_log "Current People count: $p_state";
}
}- on
- motion
- alertmin - Motion or door opening
- reset - Resets all statistics
- "minimum:xxx" - Minimum count of people. The name to me is a bit confusing. What this actually represents in the highest number of people seen in the house since the last 'reset' of the occupancy monitor.
- "current:xxx" - Current count of people on last sensor report, or the number of unique people seen recently.
- "average:xxX" - Running average count of people (NOT IMPLEMENTED YET??)
- "last:xxx" - Last sensor to report
- "people:xxx" - A different count of people in the house based on adding up the number of people in each presence object. If you are not using room counts, then this will be the number of unique rooms containing people. If you ARE using room counts then this should provide the most accurate count of the number of people in the house at the current time.
- input states - All input states are echoed exactly to the output state as well.
Each unique set of edges creates one room. If multiple objects have the same edges they are in the same room. If two objects do NOT have the same edges then they are NOT in the same room. The order of the edges does not matter but you should NOT list the same edge twice for the same object. To start, you assign a number to every junction between two rooms. So, let's say that your house consists of three rooms all off of a single hallway. You then have three junctions, each one between the hallway and one room. So, you would do this:
Hallway attaches to all three rooms
$om->set_edges($motion_hallway, 1, 2, 3);Each room attaches to the hallway
$om->set_edges($motion_room1, 1);
$om->set_edges($motion_room2, 2);
$om->set_edges($motion_room3, 3);Now, doors can be confusing, because they are the edge. In this simple example, if you had a door sensor on each of the three doors, you would just do:
$om->set_edges($door_room1, 1);
$om->set_edges($door_room2, 2);
$om->set_edges($door_room3, 3);I had a difficult sitution where I had two doors with sensors which were the two boundries of one room. If the room had a motion sensor, then it would work like this:
$om->set_edges($motion_detector, 1, 2);
$om->set_edges($door1, 1);
$om->set_edges($door2, 2);But in my case I did not have a motion detector, which means that edges 1 and 2 would never be associated with eachother... which would cause problems. So, my rule is, when a room does not have a motion detector at all, but has one or more door sensors, act like the door sensor is in
$om->set_edges($door1, 1, 2);
$om->set_edges($door2, 1, 2);In fact, you really should consider all doors to be IN one room or the other. You can still associate the door with the light items for each room, which is usually what you want to do. So, let's say that we are back to three rooms connected in a row. Each room has a motion detector. There is a door sensor on both doors. You would start with the motion detectors (where $motion2 is the middle room):
$om->set_edges($motion1, 1);
$om->set_edges($motion2, 1, 2);
$om->set_edges($motion3, 2);Now, you could "place" both door sensors in the middle room:
$om->set_edges($door1, 1, 2);
$om->set_edges($door2, 1, 2);Or, you could "place" them in each end room:
$om->set_edges($door1, 1);
$om->set_edges($door2, 2);Or you could put one in the middle room and one in an end room. What you should do is "place" the door items in the room with the poorest motion detector coverage. So, a room with no motion detectors would come first, but a room with limited motion detector coverage is also a good choice.
Let's do one more door example. We have two rooms, each with a motion detector, and a door in between them. So, we only have one edge:
$om->set_edges($door, 1);
$om->set_edges($motion_room_1, 1);
$om->set_edges($motion_room_2, 1);Now, what is wrong here? Remember, if more than one object has the same edge list then they are considered to be the same room. So this edge listing gives us one room only. So, we need to make up at least one fake edge:
$om->set_edges($door, 1);
$om->set_edges($motion_room_1, 1);
$om->set_edges($motion_room_2, 1, 100);Now there are two rooms and the door is "in" room #1. This is great if room #1 has the poorest motion detector coverage. If room #2 has poorer coverage, put the door "in" room #2:
$om->set_edges($door, 1, 100);
$om->set_edges($motion_room_1, 1);
$om->set_edges($motion_room_2, 1, 100);If the rooms on each side of the door have about equal motion detector coverage, then determine which room you are usually entering when you open the door and place the door into that room. You can still attach the door to the Light_Items on both sides of the door.
First of all, you may want to experiment with a new feature where the occupancy monitor actually keeps track of the number of people in each room instead of just occupied/vacant. Note that enabling this makes it more likely that you will have false occupieds (thus leaving lights on that don't need to be) and less likely that you will have false vacants (thus turning lights off that need to be on). Because of this you may want to enable expiration of your presence objects (use the occupancy_expire() function on each presence object).
To enable the counting of people in each room:
$om->room_counts(1);NOTE: At this time, I no longer use room counts
Next, I have many Hawkeye motion detectors that are very close together. There are scenarios where I walk by one and it sends out 'motion'. Then I keep walking within its field of vision but it doesn't send out another 'motion' for about 5 seconds. Let's say that after 3-4 seconds I walk into another room and its motion detector sends out a 'motion'. But then the first motion detector finally sends out its 'motion' signal immediately afterwards. Now the occupancy monitor thinks I'm back in the original room. When I walk into the next room it thinks I'm a new person.
So, I added an optional "ignore time" for each detector. I only recommend using it for Hawkeye motion detectors and any other sensors that have a certain amount of inherent latency. I currently set this for ALL of my Hawkeyes with a value of 2 seconds (which really means 2-3 seconds). What this means is that if a room JUST went vacant within the previous 2-3 seconds (which happens when I enter a new room) and then there is a motion signal, it will be ignored. This could mess things up, though, if you step into a room and then immediately step back into the previous room. But, if you stay in that new room within motion detector coverage for another 5 seconds or so then another motion command should be sent and everything should be okay.
Here is what I do for all of my Hawkeyes:
$om->ignore_time($x10_motion_hallway, 2);Now, my other situation is that I have soom door sensors which are basically instantaneous. But some of these doors have Hawkeye's pointing right at the doors. So, it is almost certain that when I open the door and as I step through it the Hawkeye WILL send 'motion' after the door indicated that it was opened. So, for these specific motion detectors, I set their ignore time to 10 seconds.
This is another feature I added to handle my doors that so quickly send changes to Misterhouse. The scenario is that I am in room 1, I walk through room 2 and open a door with a sensor before any motion detectors in room 2 have been able to tell Misterhouse they saw motion. So, all of a sudden the occupancy monitor thinks I am a second person.
So, what this allows for is, if a sensor detects activity, and there is nobody in the immediately surrounding rooms, then it will turn to these extra rooms to check for people. If it finds somebody in one of these rooms it will move them to the new location. You turn this on by doing this:
$om->set_extra_rooms($master_bed_door_sensor,
$sensor_master_bath, $sensor_hall_bedrooms);This says that if the sensor $master_bed_door_sensor detects activity (i.e. it is opened), and nobody is present in the two connecting rooms, then go on and check the room containing $sensor_master_bath and the room containing $sensor_hall_bedrooms.
This is also useful if you have any motion detectors that frequently miss you entering the room... especially if there is a certain path you take from one room to another and through a third room that causes you to not be detected my a motion detector in that third room.
Here are some details:
- The first argument is an actual sensor, not a
Door_ItemorMotion_Item! This only applies to that single SENSOR and not to any other sensors that may be in the same room. - All of the remaining objects are sensors from ROOMS from which the presence can be taken. If there are multiple sensors in the ROOM then only list ONE of them.
- IMPORTANT: The sensor in the first argument must be separated from each following sensor by only ONE room. This is because the algorithm will move the person from the extra room into ONE intermediate room and then expects them to be adjacent to the room containing the sensor listed as the first argument.
This function was added just because of my dogs. What I have done in my house is set up most motion detectors so that they will never see the dogs. This works fine most of the time. The problem is that if two people are in one room and one person leaves, the occupancy monitor doesn't know if two people or one person left. So, the initial room will go vacant until it sees more activity in there.
The problem is that for certain rooms like the master bedroom and family room, the person in the room might be sitting down or laying down out of range of the motion detectors. This means that the light will turn off on them after the timer runs out.
So, I have certain motion detectors that watch the entire room and regularly pick up the dogs. They are set, however, to only maintain presence and not establish presence. The way this is accomplished is:
- Motion from these detectors is ignored unless the occupancy monitor thinks the room was recently vacated (within a user-specified number of seconds), in which case the room is switched back to "occupied".
- Motion from these detectors will never cause predictions nor will it remove people from surrounding rooms.
- When a room IS switched back to "occupied" because of one of these sensors, the occupancy count is never increased (if you are not using room counts, this will only happen if there are too many unique rooms occupied as defined by expected_occupancy). What this means is that the room with the most stale presence has its room count decreased (or simply marked 'vacant' if not using room counts) to account for this new presence.
You enable this only for the motion detectors you want largely to be ignored by the system:
$om->maintain_presence($family_room_motion_maintain, 300);In this case, if the room was vacated within the previous 300 seconds then the specified motion detector can re-establish presence if it detects motion. Remember that you can also set a minimum amount of time the room must be vacant before the presence can be re-established using ignore_time().
Another function added because of my animals. In this case, you can set a sensor (probably a Motion_Item) that can only cause the room to become occupied if it is able to take occupancy from a surrounding room (or any extra rooms specified). This means that occupancy can never pop up in this room. In my case, I have a small bathroom with a motion detector on the ceiling looking straight down. We normally keep the door cracked shut, but the cats get in sometimes and create motion. Since there is only one connecting room to the bathroom, presence will only show up there if presence was already in the connecting room.
$om->no_new_presence($hall_bath_motion_detector);Where $hall_bath_motion_detector is a Motion_Item in my case, and to me this setting only makes sense with motion detectors. Note that if you have the motion item attached to the light item then the light will still turn on even though presence is not established.
When somebody enters a room, and there are people present in more than one connecting room, it does not know from which room the person came. So, it has no choice but to assume all people entered the new room with the hope that motion sensor activity will return any falsely removed people to their appropriate rooms, with the true empty room never regainging occupancy, of course.
Well, this method works pretty well, but I like to use every bit of information I have available to me. So, what I realized is that if a particular edge is actually a door and that door has not been opened recently, then there is no way that any people that are behind that door to move into the attached room. So, I have added a facility for you to tell the occupancy monitor where exactly your doors are and as such this knowledge can be exploited.
The format of the call is:
$om->door_restriction($door_object, 1, 10);Where $door_object is the actual Door_Item for the door you are referring to. The number '1' is the one edge the door is on. The number '10' is the number of seconds back that an open state will be searched for.
I'll try to put the above function call into a bit easier to understand English. Basically, it is telling the occupancy monitor to NOT allow anybody to move across edge 1 unless the door $door_object was in an open state in the previous 10 seconds.
You must call this function for every door object you want to enable this feature for. By default, a door's open/closed state does not affect whether or not somebody can pass through its edge (plus, in many cases the occupancy monitor does not know which edge the door is actually on).
Because doors can trap a fake person in a room, I recommend setting an expiration on the presence object. Also, when a door restriction is enabled, because of this trapping possibilty, the system is a bit more liberal with removing people from rooms when the door was just recently closed. For that reason, I recommend that any rooms with such a door restrictions should either be a room that you rarely remain inside with the door closed (i.e. a closet) or a room with its own motion detector inside.
In my home automation setup, I usually know how many people are in the house from other sources. But I need the occupancy monitor to keep track of where the people actually are. There is no point in setting a minimum occupancy because the occupancy monitor would have no idea where to place the people initially. Besides, errors pretty much always cause too many people to be present, not too few.
So, if you set a maximum here, if too many people are present in the house, then the "stalest" presence will be removed. Remember, if you are not using room counts (which I don't currently), this will actually just limit the number of unique rooms containing people.
$om->max_occupancy(3);This sets the absolute number of people to be tracked in the house to three. To disable, set this to -1, which is the default.
NOTE: max_occupancy() will keep the number of people present, determined by adding up the occupancy count of each room, less than or equal to the value set. It will NOT affect the 'minimum' count which is based only on activity and therefore the 'minimum' count may exceed the specified maximum. The 'people' count, on the other hand, will always be less than the specified number.
Sometimes we have people come over and spend the night in which case I enable a guest mode which increases the maximum occupancy. But other times we just have somebody come over for dinner or whatever. So, what I'm trying now is to set the maximum occupancy to one higher than the expected occupancy. And then I'm setting the expected occupancy to 1 or 2 depending on whether my wife and/or I are home.
The idea is that the system will try to keep occupancy at the expected occupancy. But if occupancy exceeds this expected value twice within a specified period of time, then it allows the occupancy to increase. Once it is increased, the expected occupancy is actually increased to the new value. This means that it can increase yet again if it needs to. But it will never increase to above the maximum occupancy, if set.
To reset the expected occupancy, just set it again. This will put it back to the value specified and reset any timers related to it. What I do is do such a reset whenever my front door is opened which is how our guests always come into or leave the house.
$om->expected_occupancy(2, 300);This resets the expected occupancy to 2 people and allows it to increase whenever an increase looks necessary twice within 300 seconds. Note that this does not actually affect any presence information, unless the current occupancy count is greater than the new expected count, in which case only the most recent presence is maintained.
To turn off the expected occupancy, set it to -1:
$om->expected_occupancy(-1);NOTE: expected_occupancy() will keep the number of people present, determined by adding up the occupancy count of each room, less than or equal to the value set. It will NOT affect the 'minimum' count which is based only on activity and therefore the 'minimum' count may exceed the specified maximum. The 'people' count, on the other hand, will always be less than the specified number. In fact, the first time the expected occupancy is exceeded, 'minimum' will go up by one and 'people' will remain at the expected occupancy level. If this happens again within the specified amount of time, 'people' will rise to the 'minimum' count at that point.
I have managed to avoid detecting my dogs with the motion detectors in every room in my house. I have, however, a problem in the kitchen. Despite my best efforts, the cats still jump onto the counters and the kitchen table and therefore trigger my motion detectors.
So, I added the ability to require more than one motion detector to detect motion before presence is established in the room. This is done by overriding the default weight of 1 for particular motion detectors. Once enough unique motion detectors detect motion to cause the cumulative count to exceed 1, presence will be established.
Here is an example that should hopefully make things more clear:
$om->set_edges($om_motion_kitchen1, 11, 13, 16);
$om->set_edges($om_motion_kitchen2, 11, 13, 16);
$om->set_edges($om_motion_kitchen3, 11, 13, 16);
$om_motion_kitchen1->presence_value(0.5);
$om_motion_kitchen3->presence_value(0.5);
$om_auto_kitchen_light->add($om_motion_kitchen2, $only_when_fairly_dark,
$only_when_home, $om_presence_kitchen, $only_without_movie_lights);By not setting a value for $om_motion_kitchen2, it remains at the default of 1. What this means is that if $om_motion_kitchen2 detects motion, presence is automatically established in the kitchen. In addition, since $om_motion_kitchen2 is directly attached to the light object, the light will come on, regardless of the presence value.
But, if $om_motion_kitchen1 detects motion, the presence will effectively be set to 0.5, which is not quite 1. To establish presence in the kitchen, one of the other two motion detectors still need to detect motion. Since both of the remaining motion detectors will push the total above 1, either one will cause presence to be established.
Once presence is established in the room or a surrounding room the whole count is reset to zero.
An additional feature of partial presence is that if somebody walks through a room and doesn't trip enough motion detectors to establish presence, as long as they tripped at least one, presence is allowed to move through that room, if necessary.
Put another way, if somebody pops up in a room, the following steps are taken, taking into account any door restrictions:
- Presence is taken from all surrounding rooms
- If no surrounding presence is found, but partial presence is found in a surrounding room and presence is found in a room adjoining that room, presence will move through the room with partial presence and into the new room.
- If extra rooms have been specified for the new room, and presence exists in one of those extra rooms, presence is taken from said room.
- Finally, if all else fails, new presence is created in the new room.
The standard presence expiration is handled through the presence object. Just call occupancy_expire() to set an expiration time on any of your presence objects (as described in Presence_Monitor.pm).
But, if you are using room counts (or the bounce-prevention code described next), there can be another problem. Start with two people in one room. Now one person goes into an adjoining room. Then the other person also goes into the other room. The problem is that, by default, the second person will never be moved into the other room. That's what you can change here -- set an expiration time after which presence will be moved into another room when it detects activity, even if the other room already has one or more people in it.
The first argument is one of the sensors in the room, and the second argument is the expiration time, in seconds. Be sure that you have called set_edges() on the sensor before calling this.
$om->presence_move_time($sensor, 600);When setting this value, you should think about how long somebody would stay in the specified room and how good the motion detector is in that room, relative to the adjoining rooms.
Remember -- in order for this to affect anything, the presence in one room has to be older than the specified time (which means there has been no motion detected) AND there has to then be activity in an adjacent room.
This option pretty much only makes sense to me when you are NOT using room counts, which I do not use at this time. Basically, without room counts, there is no way, by default, that two adjoining rooms can both have occupancy at the same time (unless there is a closed door between them and you activate that restriction).
In my house, the ktichen and family room are adjoining and if one person is in each room, the occupancy will keep bouncing back and forth as motion detectors are triggered. This is fine if you have a significantly lengthy delay before the lights turn off, but in my case I have lights or ceiling fans that may turn on only after a room has been continuously occupied for a certain amount of time. In my case, then, I would like both rooms to be able to be occupied at the same time. So, what you can do is this:
$om->prevent_bounces($sensor_room1, $sensor_root2, 60, 2);Where $sensor_room1 is any sensor (Motion_Item or Door_Item) that is in one of the rooms, and $sensor_room2 is any sensor that is in the other room. The rooms must be adjoining (or it wouldn't make much sense to use this feature). This says that if presence leaves either of the rooms and moves to the other room two times within 60 seconds, then presence should be allowed in both rooms at the same time. Also note that this will NEVER cause the expected occupancy count (which, when not using room counts, is the expected unique rooms with presence) to be exceeded and will never cause presence to be taken from elsewhere in the home to account for the presence in adjoining rooms.
I want to provide some example scenarios here from my house to show how I use these various tuning options to improve occupancy tracking in my house. I'll add these as I find time and reasons to add them.
I have a couple of doorways in my house with motion detectors on each side. As I walk through the doorway, I trigger the two motion detectors perhaps within 1/10 to 1/5 of a second apart. Because my Hawkeye motion detectors have not completely predictable latency associated with the first sign of motion and the sending of the signal, it is entirely possible that as I walk past detector 1 and then detector 2, Misterhouse receives the signal from detector 2 before the signal from detector 1. So, without any modification, it will think that I ended up in the first room when in fact I ended up in the second room.
So, I use the ignore_time() function to prevent this problem from occurring. By using this feature, the belated motion signal from detector 1 will be ignored because the room containing detector 1 just went vacant let's say 1 second before the signal was received (room 1 went vacant when detector 2 sent its motion signal). This will properly leave my presence in room 2.
$om->ignore_time($motion_detector_1, 4);
$om->ignore_time($motion_detector_2, 4);Now, regardless of which way I walk through the doorway, a belated (out of order) signal from one of the detectors won't errantly move my presence back into the first room. In fact, I use a delay of 2 (which means 2-3 seconds) for ALL of my Hawkeye motion detectors just in case.
In one of my rooms, I have the previous scenario (two motion detectors in different rooms very close together) but also with a hallway entering room 1 right outside the doorway. The hallway does NOT have a motion detector close to this intersection. So, what can happen here is that I'm in the hallway, I walk through room 1, and into room 2, and the scenario happens as described above.
But the fix above doesn't fully solve the problem on its own. Since I started out in the hallway, and then it got motion 2 activity, I was never in room 1, so the ignore time for motion 1 won't take effect. So, even with the ignore time set, when Misterhouse receives the motion 2 signal, it assumes there is a new person in room 2 (and still thinks somebody is in the hallway). Then, when the belated motion1 comes through, it moves both people into room 1. So, not only is the presence removed from room 2, where it should be, but there are now too many people present (which only matters if you are using room counts).
So, we can add another setting in addition to the ignore_time() calls in the previous scenario. We can specify that if motion 2 sees motion (in room 2) but there is nobody in any adjoining rooms (i.e. room 1), then if somebody is in the hallway they should automatically moved THROUGH room 1 and into room 2. The moving through the room is important because presence is indeed briefly established in room 1 which makes the ignore time properly ignore the belated motion signal from motion 1.
$om->set_extra_rooms($motion_detector_2, $motion_detector_hallway);This says that when motion_detector_2 detects motion and there is no presence in any adjoining rooms, to take presence from whatever room $motion_detector_hallway is in (if possible). I don't have a rule for going the other way (room 2 into the hallway) because the motion detector in the hallway is sufficiently far away from the other motion detectors that it works just fine on its own.
I have four outside doors on my house. I treat the garage itself as a room of my house, so the external door there is the garage door. Then I have my front door which is connected to my living room. And I have two back doors both connected to my patio. I actually treat the back patio as a room in my house as well. I have X10 wireless door/window sensors on each of these doors. I also have a gate between the front and back of my house with a sensor on it. I have motion detectors in my garage but not anywhere outside of my house.
I use the following user code to handle any occupancy issues related to any movement outside the house.
# First, handle movement in and out of the front door and garage
if (state_now $om_door_front eq 'open') {
# Front door was opened, remove presence from living room, counting
# on motion detectors in the living room to re-establish presence
$om_presence_living_room->set_count(0);
# Also, if garage door is open, somebody might have gone from
# the garage to the front door, so clear occupancy there. Again,
# motion detectors are in the garage to re-establish presence
if (state $garage_door eq 'open') {
$om_presence_garage->set_count(0);
}
}
# Now, handle movement between the front yard and the back yard
if (state_now $side_gate eq 'open') {
# Gate was opened... remove presence from front and back yards
# as appropriate, allowing it to be re-established only if
# somebody re-enters one of the rooms
$om_presence_back_patio->set_count(0);
if (state $garage_door eq 'open') {
$om_presence_garage->set_count(0);
}
}