Introducing WITB+ (Wasp in the Box Plus) Blueprint
We’re excited to introduce the latest version of the WITB+ blueprint for Home Assistant!
You must be on Home Assistant Version 2024.8 or later for 0.5.0
Description: WITB+ (Wasp in the Box Plus) is an advanced automation blueprint crafted for occupancy detection using multiple sensors. Inspired by the concept of “Wasp in a Box,” this blueprint utilizes motion and door sensors to monitor occupants within a defined space (the “box”). When motion is detected, indicating the presence of a “wasp” (occupant), the box’s state is updated accordingly. The generated binary sensor reflects the presence or absence of a wasp in the box, facilitating seamless integration with automation triggers.
Assumptions:
Motion sensors are strategically positioned to detect movement when someone enters the room, thereby triggering occupancy detection.
The room is considered occupied as long as the door to the designated area (the “box”) remains closed, influencing the automation’s behavior.
Users are expected to configure motion and door sensors accurately to ensure precise occupancy detection within the designated area.
The blueprint offers options to control smart light bulbs, light switches, and fans within the area based on occupancy detection.
Users are encouraged to create input_boolean entities for occupancy tracking and bypass control if they opt to utilize these features.
For bypass functionality, users need to manually integrate call service actions into their automations or methods to control devices when bypassing occupancy detection is required.
Current Version: 0.5.0
Please see change log for more details. Stable Changelog
Get Started: To implement the WITB+ blueprint in your Home Assistant setup, simply import the blueprint using the provided URL: Download WITB+ Blueprint
Inputs:
Door Sensor: Select the door sensor or group of sensors representing the entrance to the designated area.
Motion Sensor: Choose the motion sensor(s) responsible for detecting movement within the area.
Light Bulbs, Light Switch, Fan: Select the devices to control within the designated area.
Bypass Mode: Customize the behavior of the automation during bypass events.
And more customizable options to tailor the blueprint to your specific needs!
Documentation: For detailed information on inputs, variables, triggers, actions, and customization options, refer to the blueprint documentation available on GitHub: View Blueprint Documentation
Feedback and Contributions: We welcome feedback, suggestions, and contributions from the community to enhance the WITB+ blueprint further. Feel free to share your experiences, ideas, or any issues you encounter while using the blueprint.
Future Enhancements
Additional Lighting Controls: We plan to expand the capabilities of the blueprint by incorporating more advanced lighting controls. This could include adjusting brightness, changing colors, or even integrating scene selection functionality.
Customization Options: We aim to provide users with more customization options to tailor the blueprint to their specific needs and preferences. This might involve configurable parameters for sensitivity, timing, or integration with other devices.
Integration with Environmental Sensors: In future iterations, we envision integrating the blueprint with environmental sensors to enhance automation based on factors like ambient light, temperature, or humidity.
Improved Bypass Functionality: We’re exploring ways to enhance the bypass functionality to make it more intuitive and user-friendly. This could involve simplifying the setup process or adding additional bypass modes for greater flexibility.
Time of Day Events: We’re considering adding time-based events to the blueprint, allowing users to configure different behaviors based on the time of day. This could include features like nightlight settings, where the lighting adjusts automatically based on the time, creating a more comfortable environment during nighttime hours.
Let’s make home automation smarter and more efficient with WITB+!
I notice the documentation includes this assumption:
It is assumed that as long as the door to the designated area (“box”) is closed, the room is considered occupied, influencing the automation’s behavior.
Am I misunderstanding? Surely this is only the case if motion has been detected since the door was closed, yes? Presumably this leads on from the first point, which referecnes motion?
I had previously implement WitB functionality using a function in Node-Red - this has worked well, but I’d prefer to migrate to a native HA blueprint and automation. Just configured it but I have had a false positive - the room showing as occupied when it was not. Before I start digging into too much testing I thought I should check this point.
I think the intent of that bit of the documentation is to say that: if the box is opened, occupancy triggered, and then the door remains closed, then no matter what the state of your occupancy sensor the box is considered occupied.
This is the spirit of the Wasp in a Box in general. You assume the wasp is still in there because no door has opened to let it out.
The door sensor is a group made up of my garage door and the man door to the garage. My garage door sensor creates a working binary_sensor so I was able to group it with the man door.
The door group sensor behaves as expected when I monitor its state.
The motion sensor is a template group consisting of a mmwave/pir sensor, and the state of my TV in the garage. It also is behaving as expected when I monitor the state.
The light is actually a zigbee power outlet configured as a light domain in HA.
When I enter the garage, the binary_sensor.garage_access_group turned to open, the binary_sensor.garage_occupied changed to occupied, and then the light turned on with this entry in the logbook:
turned on triggered by action Home Assistant Core Integration: Generic turn on
In the blueprint I have the “Motion off delay (Optional)” is set to 30 seconds.
But it has been 13 minutes now with the occupancy showing clear and the man door being closed and the lights have not turned off yet…
@nicesocks For sure I get what the logic is, but as you’ve also found, I was getting false positives - if I left the room and closed the door, it continued to show the room as occupied.
For now I’ve created my own automation which is working reliably, but I would prefer to revert to this Blueprint if possible.
WITB assumes that the room is normally open, meaning the door remains open when not in use. I wasn’t able to find a way for WITB to work when the door remains closed, whether the room is occupied or not. One of the limits to WITB is the use of just a door sensor and a motion sensor.
If you share your automation, perhaps we can work together to figure out WITB for situations where the door is normally kept open or closed.
I have basic blueprint with basic WITB logic. I hope to expand on this, but without using mmWave or some other sort of sensor that deals with limits of PIR motions sensors.
I have this set up in a bathroom where someone habitually leaves the lights on. So I set up a door sensor and a motion sensor in the room and filled in the blanks on this blueprint accordingly.
The behavior I see is this: If the door is closed, the light is turned on immediately. It never shuts off due to lack of motion detection.
Somehow I remember it working as I expected at first, which is: the light switch is triggered on manually → the door is closed → the PIR detects motion while the door is closed as the subject moves within the room → room is now verified as occupied until the door is opened → subject opens the door to exit → subject closes the door behind them, or doesn’t, shouldn’t matter → timeout period starts → PIR detects no motion and un-triggers after 30 seconds → automation sees no motion beyond that time and sets the room as unoccupied → light is turned off. If the occupant somehow remembers to turn the light off as they leave, that immediately sets the room as unoccupied and if the door is then closed the light will remain off.
If I am mistaken and it never did this to begin with, that’s fine. But this is the logic I was expecting. So, if this blueprint is to assume that if the room is unoccupied the door must remain open, that is of no real value over just hard-tying the light to the door contact sensor.
Sorry to hear you’re having issues. We’ll have to agree to disagree on the value.
As I understand it, your issue is that they close the door after leaving. With just a door sensor and a PIR motion sensor, WITB has a known limitation in determining whether someone actually entered or exited. The core challenge with WITB is that a door closing event alone doesn’t indicate direction—whether someone entered or if the door was simply closed without entry. The PIR motion sensor helps detect movement inside, but it doesn’t guarantee that a person remains in the area after the door closes.
This ambiguity makes WITB tricky to implement reliably with just these two sensors. A more robust approach would involve additional sensors or logic to track movement history and confirm presence over time. Off the top of my head, an mmWave sensor could be a potential solution for more accurate presence detection.
If you happen to know a good way to track this, let me know!
I can share my exact automation if that’s useful, but here’s a quick summary.
I trigger on the following:
Motion is detected
Door is opened
No motion for 1 minute
Door has been closed for 1 minute
I then have three conditions that evaluate as follows:
If motion is detected or the door is opened (and room currently “Unoccupied”), room is OCCUPIED
If no motion is detected for 1 minute and the door is currently open (and room currently “Occupied”), room is UNOCCUPIED
If door has been closed for 1 minute and no motion has been detected for 40 seconds (and room currently “Occupied”), room is UNOCCUPIED
This has worked very reliably for me, for several weeks. If someone is in the room with the door open, it will of course revert to Unoccupied if they’re not moving much, such as lying on a bed reading. This is a known limitation of the WiaB approach, but hasn’t been a major issue. Crucially though, it does allow the door to be left open or closed when the room is unoccupied.
The biggest challenge is dealing with the cooldown on the motion sensor. In particular, if someone leaves the room and shuts the door, that 3rd condition (which should revert to Unoccupied) won’t do so if the motion sensor cooldown is too long, which could result in the room being marked as Occupied all day - that would be a pain if its used for things like heating (which mine does). However widening the gap between the door test (1 min in my case) and the motion check (40 seconds) would resolve that - it just needs some adjustment based on how responsive your PIR is.
As I say this has worked great and I have no issue with sticking with it if I have to, but I’d prefer to use a Blueprint as its more scaleable, so please feel free to take anything here that might be useful and incorporate it.
Interesting! Since this add a no motion check, this would indeed help when the door is closed. Do you need to be more careful with the placement of the PIR sensor? Also, how does this work with people reading in the bathroom?"
I use this in a bedroom, but we can walk through how this would work in a bathroom.
In terms of reliably reporting that the room is unoccupied once they leave, that wouldn’t be any different from my use in a bedroom, so should be rock solid, even if the door is closed. As this seems to be a key challenge with the current blueprint I think that’s worth confirming up front.
So what’s the potential downside? Well, if a person walks into the bathroom, sits on the toilet and is then still enough so as not to trigger the PIR at all for a period of time, it’ll be incorrectly reported as Unoccupied. In more specific terms, and using my current values (see below), 20 seconds after the door closes they’ll need to not trigger the PIR at all for a further 40 seconds. Is that possible? Sure, but I suspect its not very likely. Also even if it does happen, any subsequent trigger of the PIR will result in the sensor “locking” to an Occupied state (because the door is closed).
As a reminder, my logic is built on two key values:
How long after the door is closed, will the room be evaluated as being potentially Unoccupied. The higher this value the longer it will take to respond to the room becoming empty, but the easier it will be to avoid false negatives, as you can set the value below higher. My current value for this is 60 seconds.
At that point, for how many seconds prior will the PIR need to have been “Clear” for the room to evaluate as Unoccupied. Make this too close to the first value and you’ll risk false positives as the PI won’t have time to clear; set it to low and you may get false negatives as there’s a more limited “window” during which movement will be evaluated. My current value for this is 40 seconds.
You can play with these two values to tune it. If you’re OK with it taking a bit longer to update the room status when you leave and want to minimise possible false negatives due to people being very still on the toilet, something like 120 / 90 or even 180 / 150 secs would be good options.
Hope that makes sense - feel free to ask any more questions, and thanks again for the work you do!
Introducing WITB+ (Wasp in the Box Plus) Blueprint
You must be on Home Assistant Version 2024.8 or later for 0.5.0
