Magic Areas Documentation

Magic Areas transforms standard Home Assistant Areas into presence-aware zones. Key capabilities include:

• Presence Detection: Uses motion sensors, media players, device trackers, and BLE beacons to track room occupancy.
• Smart Groups: Automatically creates groups for lights (overhead, task, accent, sleep), fans, and climate devices.
• Secondary States: Provides nuanced context like dark/bright, sleep, extended (long-term occupancy), and accented (media-based presence).
• Meta-Areas: Allows grouping areas into hierarchies like interior, exterior, or specific floors to track presence across multiple rooms.
• Sensor Aggregation: Automatically aggregates sensors by device_class and unit_of_measurement, and provides a Health Sensor for safety-related classes (gas, smoke, moisture, problem, safety).

The Presence Hold feature provides a dedicated switch for a specific area that acts as a manual override for presence detection.

When the Presence Hold switch is turned on, the area's presence state is forced to occupied, overriding all other configured presence sensors and logic. When the switch is off, the area reverts to normal presence detection behavior based on your existing sensors.

Common use cases include:

• Manually marking a room as occupied when sensors fail to detect someone (e.g., guests or pets).
• Temporarily keeping an area "occupied" for testing automations.
• Overriding presence during maintenance or cleaning.

The Light Groups feature organizes and automates lights based on their purpose and the current state of an area.

At its core, Magic Areas automatically creates a Home Assistant light.group for every area containing light entities. You can further classify these lights into predefined groups to enable smarter, context-aware automation:

• Overhead Lights: Main ceiling lights for general illumination.
• Accent Lights: Decorative or highlight lighting (e.g., under cabinets, wall sconces).
• Task Lights: Focused lights for workspaces, desks, or reading.
• Sleep Lights: Dim lighting suitable for nighttime or bedtime use.

Each populated group automatically receives a dedicated light.group entity in Home Assistant. To enable the automation logic for these groups, you must turn on the Light Control ($Area) switch created by Magic Areas.

Magic Areas is built upon three fundamental pillars:

• Presence Sensing: Detecting occupancy in an area using various sources like motion sensors, media players, device trackers, or BLE beacons.
• Area States: The state of an area (e.g., occupied vs. empty) which drives automations.
• Meta-Areas: Higher-level groupings (e.g., 'Interior', 'Exterior', 'Global', 'Floors') used to coordinate multiple areas simultaneously.

Magic Areas monitors both primary and secondary area states to trigger climate changes:

• Primary States: occupied or clear.
• Secondary States: sleep, dark, or extended.

Whenever a state change occurs, Magic Areas automatically applies the corresponding mapped preset to the configured climate device.

The Wasp in a Box 🐝📦 feature adds contextual logic to motion-based sensors by using an associated door or entry sensor (the "box"). This prevents false clears when a motion sensor times out after you have already left a room, or when a door is closed while motion is still active.

The Logic:

1. Wasp detected: If a motion sensor triggers, a "wasp" is assumed to be in the box.
2. Box closed: If the door/garage closes while motion is active, the wasp is assumed to stay inside.
3. Inactivity: If the box remains closed and motion stops, the wasp is assumed to still be inside.
4. Box opened: If the door opens and no motion is detected, the wasp is assumed to be gone.

This is particularly useful for enclosed spaces like bathrooms, bedrooms, offices, garages, and laundry rooms.

Magic Areas goes beyond simple binary presence (occupied/clear) by tracking secondary states. These states provide environmental context for an area, allowing automations to behave differently based on the time of day or activity level.

Common secondary states include:

• dark
• sleep
• extended

Developers can use these states to create context-aware automations, such as adjusting lighting brightness or color temperature when an area enters a dark or sleep state.

Magic Areas determines if an area is occupied or clear by monitoring presence-related events from specific Home Assistant entity types. It interprets the states and device_class values of these entities to automate area state changes without requiring manual configuration for most standard sensors.

Core Logic Examples:

• media_player (and remote): If the state is playing in an area $\rightarrow$ area is occupied.
• device_tracker: If the state is home $\rightarrow$ area is occupied.
• binary_sensor: If the state is on $\rightarrow$ area is occupied.

Magic Areas' core strength is stacking multiple presence sources. To handle 'flappy' or unreliable sensors (like BLE trackers that jump between rooms or mmWave sensors that trigger on moving curtains), use the 'Keep-only sensors' functionality.

Recommended Strategy:

• Use high-reliability sensors (mmWave, BLE, or 'Wasp in a box') as your primary sources.
• Add unreliable or slow sensors (like BLE trackers) to the 'keep-only sensors' list. This allows them to maintain presence state without causing the 'flapping' behavior typical of these devices.

The routing logic follows these rules:

• Occupancy Requirement: Only occupied areas matching the configured Notify States will receive audio.
• Duplication: Media is duplicated across multiple areas if more than one area qualifies.
• Exclusion: No playback occurs in sleeping, empty, or excluded areas.