Wasp in Box¶

The "Wasp in Box" feature provides enhanced occupancy detection for rooms with a single entry/exit point (like bathrooms, closets, or small offices). It uses a simple but effective principle: if someone enters a room and the door closes, they remain in that room until the door opens again.

How It Works¶

The feature is named after the concept of a wasp trapped in a box - once inside, it remains there until an opening appears. Similarly, once a person enters a closed space, they must be considered "present" until they exit through the door.

With Door and Motion Sensors¶

When both door and motion sensors are available:

1. Entry Detection:
2. Door closes AND motion is detected → Room becomes OCCUPIED

3. The state persists even if motion stops

4. Exit Detection:

5. Door opens → Room becomes UNOCCUPIED
6. Any subsequent motion requires a new entry cycle

With Door Sensor Only¶

When only a door sensor is available:

1. Entry Detection:

2. Door closes while the room is unoccupied → Room becomes OCCUPIED

3. Exit Detection:

4. Door opens while the room is occupied → Room becomes UNOCCUPIED

Benefits¶

• Solves the "bathroom problem": Traditional motion sensors often time out while someone is in the bathroom, leading to lights turning off at inconvenient moments
• Works with minimal sensors: Can function with just a door sensor if needed
• Complements motion detection: Fills the gaps where motion detection fails
• Improves automation reliability: More accurately maintains occupancy state for rooms where people may be stationary

Configuration¶

The Wasp in Box feature can be enabled in the integration configuration UI:

1. Navigate to the integration configuration
2. Expand the "Wasp in Box Settings" section
3. Enable the feature and configure the options:

Integration¶

The feature creates a binary sensor that becomes part of your Area Occupancy Detection system:

• Entity ID: binary_sensor.[area_name]_wasp_in_box
• States: on (occupied) / off (unoccupied)
• Attributes:
• door_state: Current state of the door sensor
• last_door_time: Timestamp of last door state change
• motion_state: Current motion state (if using motion sensors)
• last_motion_time: Timestamp of last motion detection (if using motion sensors)
• motion_timeout: Configured timeout value

The sensor's state is considered alongside other sensors in the Bayesian probability calculation, with its influence determined by the configured weight.

Use Cases¶

• Bathrooms: Maintain occupancy even when a person is showering or otherwise stationary
• Closets: Detect occupancy in walk-in closets with minimal sensor requirements
• Small Offices: Maintain occupancy state when people are sitting still at a desk
• Storage Rooms: Track when people are retrieving items from storage
• Laundry Rooms: Detect presence during laundry activities with minimal motion

Technical Details¶

The Wasp in Box sensor tracks state transitions in a finite state machine:

1. UNKNOWN → Initial state before any data is collected
2. UNOCCUPIED → No one is in the room
3. OCCUPIED → Someone is in the room

The sensor uses Home Assistant's state tracking to monitor door and motion entities, processing their state changes to update its internal state based on the logic described above.

Wasp in Box Logic¶

The "Wasp in Box" sensor is a virtual binary sensor that helps determine if a space is occupied based on door states and motion detection. The concept derives its name from the idea of a wasp trapped in a box: once the door (lid) is closed with the wasp inside, the room is considered occupied until a door opens, indicating the wasp has left.

How It Works¶

The sensor monitors one or more door sensors and optional motion sensors:

1. When a door closes and recent motion was detected, the room is marked as occupied.
2. When a door closes and there are no motion sensors, the room is assumed to be occupied.
3. When a door opens while the room is occupied, the room is marked as unoccupied.
4. When motion is detected while all doors are closed, the room is marked as occupied.

The sensor retains its state between Home Assistant restarts, making it reliable for long-term occupancy tracking.

Maximum Duration Feature¶

The sensor can be configured with a maximum occupancy duration. This addresses scenarios where a space might be incorrectly marked as occupied for extended periods:

1. When enabled, the sensor will automatically reset to unoccupied after the specified duration.
2. Set to 0 (default) to disable this feature and maintain the traditional Wasp in Box behavior.
3. Useful in environments where someone might leave through an unmonitored exit.

Configuration¶

The Wasp in Box sensor can be configured in the integration settings:

• Enable Wasp in Box: Turn this virtual sensor on or off
• Motion Timeout: How long motion events are considered recent (in seconds)
• Wasp Weight: The weight factor for this sensor in probability calculations (0.1-1.0)
• Maximum Occupied Duration: Maximum time (in seconds) a space can be marked as occupied before automatically resetting (0 = no limit)

Example Use Cases¶

• Small rooms with single entry/exit points: The sensor excels at tracking occupancy in bathrooms, closets, or offices with one door.
• Spaces with incomplete sensor coverage: If you don't have motion sensors that cover the entire room, the Wasp in Box can still provide reliable occupancy detection.
• Persistent occupancy status: Unlike regular motion sensors, the Wasp in Box maintains its state even during periods of inactivity, as long as doors remain closed.

Attributes¶

The sensor provides these attributes:

• door_state: Current state of the monitored door(s)
• last_door_time: Timestamp of the last door state change
• motion_state: Current state of motion sensors (if applicable)
• last_motion_time: Timestamp of the last motion detection (if applicable)
• motion_timeout: Current motion timeout setting
• max_duration: Maximum time in seconds the space can be marked as occupied (0 = no limit)
• last_occupied_time: Timestamp when the space was last marked as occupied