Area Occupancy Detection for Home Assistant (Marketplace integration)

Installs: 603 sharing analytics
GitHub stars: 338
Connection: Works locally
Upkeep: Updated in the last 6 months
Version: 2026.10.2, October 24, 2026
Category: Sensors, Motion and presence
Kind: Marketplace integration
Needs: Needs the Marketplace (HACS on 2026.10 and older)
Domain: area_occupancy
Source: github.com/Hankanman/Area-Occupancy-Detection
Issues: Report an issue

Independent directory, made by the developer of Vulpo. Not affiliated with Home Assistant or the Open Home Foundation.

Screenshots From the README of Hankanman/Area-Occupancy-Detection.

About

Area Occupancy Detection estimates whether each Home Assistant area is occupied, using the probability of presence rather than motion alone. It combines inputs such as motion and presence sensors, doors, windows, locks, covers, media players and environmental sensors using Bayesian probability, and it learns usage patterns over time. Each area gets binary sensors for occupancy status and sleeping, an adjustable threshold number, and sensors for probability, detected activity, confidence and sensor health. Occupancy fades with a time decay whose half-life depends on the area's purpose, and adjacent areas can influence each other. A closed-door hold keeps single-entry rooms such as bathrooms occupied, and an away-mode entity can pause learning. Actions run analysis, export the configuration, purge an area's learned history, return weekly occupancy forecasts and change area options from automations. It works locally and is set up in the UI.

Automatic summary of the README and code of Hankanman/Area-Occupancy-Detection. Something wrong, or are you the maintainer and want your own text here? Get in touch

Supports

Works locally Talks to your devices on your own network. No vendor cloud in between.
From the Marketplace Installed through the Marketplace, formerly HACS.
Actively maintained Its author released or pushed a change in the last six months.

Provides

Sensors

Setting it up

Install it from the Marketplace and restart Home Assistant, then add it under Settings, Devices and services.

Area Occupancy Detection

Select an area or actionChoose an area to edit or remove, add a new area, or finish setup

Manage Areas

Select an area

Area config

Home Assistant AreaSelect the Home Assistant area for this occupancy detection. The area name will be automatically used for the device and entities.
Area PurposeThe primary purpose of this area determines decay behavior. Different purposes have different half-life values that affect how quickly occupancy probability decreases over time.
Name of Detection AreaThis is the name of the area or detection area. It will be used to name the sensors and the area occupancy entity.
Motion/Presence SensorsThese will be used to detect occupancy and presence. They can be motion sensors, occupancy sensors, or presence sensors.
Motion WeightThe weight given to motion sensor inputs in the occupancy calculation.
Motion TimeoutFor PIR-style motion sensors, which pulse briefly per detection and go quiet while someone sits still, each detection keeps counting in full for this long after the sensor turns off, before the area starts to clear, and is learned as occupied time. That bridges the gaps between detections instead of treating them as empty. Sensors that hold "on" while someone is there (most mmWave presence sensors) aren't extended; the integration tells the two apart from each sensor's own history.
P(Active | Occupied)The probability that a motion sensor is active when the area is actually occupied. Higher values (closer to 1.0) mean the motion sensor is more reliable when the area is occupied. Default: 0.95 (95%).
P(Active | Not Occupied)The probability that a motion sensor is active when the area is not occupied (false positive rate). Lower values (closer to 0.0) mean fewer false positives. Default: 0.005 (0.5%).
Door Sensors
Door Active StateThis is the state of the door that will be used to detect occupancy.
Door WeightThe weight given to door sensor inputs in the occupancy calculation.
Lock Sensors
Lock Active StateThis is the state of the lock that will be used to detect occupancy.
Lock WeightThe weight given to lock sensor inputs in the occupancy calculation.
Window Sensors

Area basics

Home Assistant AreaSelect the Home Assistant area for this occupancy detection. The area name will be automatically used for the device and entities.
Area PurposeThe primary purpose of this area determines decay behavior. Different purposes have different half-life values that affect how quickly occupancy probability decreases over time.
Adjacent AreasOther configured areas that physically connect to this one (e.g. a hallway connected to a bedroom). Selections are mutual — adding an area here also adds this one to its neighbour list. The integration learns transition patterns between adjacent areas and uses them to boost a neighbour's probability and slow decay when its usual exits stay quiet.

Area motion

Motion/Presence SensorsThese will be used to detect occupancy and presence. They can be motion sensors, occupancy sensors, or presence sensors.
Motion WeightThe weight given to motion sensor inputs in the occupancy calculation.
Motion TimeoutFor PIR-style motion sensors, which pulse briefly per detection and go quiet while someone sits still, each detection keeps counting in full for this long after the sensor turns off, before the area starts to clear, and is learned as occupied time. That bridges the gaps between detections instead of treating them as empty. Sensors that hold "on" while someone is there (most mmWave presence sensors) aren't extended; the integration tells the two apart from each sensor's own history.
P(Active | Occupied)The probability that a motion sensor is active when the area is actually occupied. Higher values (closer to 1.0) mean the motion sensor is more reliable when the area is occupied. Default: 0.95 (95%).
P(Active | Not Occupied)The probability that a motion sensor is active when the area is not occupied (false positive rate). Lower values (closer to 0.0) mean fewer false positives. Default: 0.005 (0.5%).

Area sensors

Door Sensors
Door Active StateThis is the state of the door that will be used to detect occupancy.
Door WeightThe weight given to door sensor inputs in the occupancy calculation.
Lock Sensors
Lock Active StateThis is the state of the lock that will be used to detect occupancy.
Lock WeightThe weight given to lock sensor inputs in the occupancy calculation.
Window Sensors
Window Active StateThis is the state of the window that will be used to detect occupancy.
Window WeightThe weight given to window sensor inputs in the occupancy calculation.
Cover SensorsCover entities (blinds, shades, garage doors, shutters) that indicate occupancy when their state changes.
Cover Active StatesThe states of the covers that indicate occupancy (e.g., open, opening, closing).
Cover WeightThe weight given to cover sensor inputs in the occupancy calculation.
Media Players
Media Active StatesThese are the states of the media players that will be used to detect occupancy.
Media WeightThe weight given to media player inputs in the occupancy calculation.

Area behavior

Occupancy Threshold (%)The probability threshold above which the area is considered occupied.
Enable Time DecayWhether to enable time-based decay of occupancy probability.
Decay Half-LifeTime window over which occupancy probability decays by half. Set to 0 to use the purpose-based default value, or enter a value between 10 seconds and 1 hour to override.
Minimum Prior OverrideThe minimum prior probability that will be used regardless of learned patterns. Set to 0.0 to disable (default).
Exclude from All AreasWhen enabled, this area won't contribute to the All Areas aggregate sensors. Useful for garages, driveways, and outdoor areas.
Closed door means still occupiedFor a room with one way in, such as a bathroom. While its doors stay closed after motion, the area stays occupied, even if motion loses someone keeping still. It clears when a door opens, or after the Wasp in Box maximum duration (an hour by default). Needs a door sensor. Replaces Wasp in Box.
Enable Wasp in Box (deprecated)Deprecated: being replaced by a built-in closed-door hold that takes over this setting automatically. Enable wasp-in-box behavior and entity for this area. Useful for single-entry rooms like bathrooms.
Motion TimeoutHow long motion remains valid after detection.
Sensor WeightThe weight given to this sensor in the occupancy calculation.
Max DurationMaximum duration that the wasp-in-box stays active after the last detected motion.
Verification DelayThe delay after closing the last door before any detected motion is considered as actual occupancy. (0 = disabled).

After setup

Select an area
Home Assistant AreaSelect the Home Assistant area for this occupancy detection. The area name will be automatically used for the device and entities.
Area PurposeThe primary purpose of this area determines decay behavior. Different purposes have different half-life values that affect how quickly occupancy probability decreases over time.
Name of Detection AreaThis is the name of the area or detection area. It will be used to name the sensors and the area occupancy entity.
Motion/Presence SensorsThese will be used to detect occupancy and presence. They can be motion sensors, occupancy sensors, or presence sensors.
Motion WeightThe weight given to motion sensor inputs in the occupancy calculation.
Motion TimeoutFor PIR-style motion sensors, which pulse briefly per detection and go quiet while someone sits still, each detection keeps counting in full for this long after the sensor turns off, before the area starts to clear, and is learned as occupied time. That bridges the gaps between detections instead of treating them as empty. Sensors that hold "on" while someone is there (most mmWave presence sensors) aren't extended; the integration tells the two apart from each sensor's own history.
P(Active | Occupied)The probability that a motion sensor is active when the area is actually occupied. Higher values (closer to 1.0) mean the motion sensor is more reliable when the area is occupied. Default: 0.95 (95%).
P(Active | Not Occupied)The probability that a motion sensor is active when the area is not occupied (false positive rate). Lower values (closer to 0.0) mean fewer false positives. Default: 0.005 (0.5%).
Door Sensors
Door Active StateThis is the state of the door that will be used to detect occupancy.
Door WeightThe weight given to door sensor inputs in the occupancy calculation.
Lock Sensors
Lock Active StateThis is the state of the lock that will be used to detect occupancy.
Lock WeightThe weight given to lock sensor inputs in the occupancy calculation.
Window Sensors
Home Assistant AreaSelect the Home Assistant area for this occupancy detection. The area name will be automatically used for the device and entities.
Area PurposeThe primary purpose of this area determines decay behavior. Different purposes have different half-life values that affect how quickly occupancy probability decreases over time.
Adjacent AreasOther configured areas that physically connect to this one (e.g. a hallway connected to a bedroom). Selections are mutual — adding an area here also adds this one to its neighbour list. The integration learns transition patterns between adjacent areas and uses them to boost a neighbour's probability and slow decay when its usual exits stay quiet.
Motion/Presence SensorsThese will be used to detect occupancy and presence. They can be motion sensors, occupancy sensors, or presence sensors.
Motion WeightThe weight given to motion sensor inputs in the occupancy calculation.
Motion TimeoutFor PIR-style motion sensors, which pulse briefly per detection and go quiet while someone sits still, each detection keeps counting in full for this long after the sensor turns off, before the area starts to clear, and is learned as occupied time. That bridges the gaps between detections instead of treating them as empty. Sensors that hold "on" while someone is there (most mmWave presence sensors) aren't extended; the integration tells the two apart from each sensor's own history.
P(Active | Occupied)The probability that a motion sensor is active when the area is actually occupied. Higher values (closer to 1.0) mean the motion sensor is more reliable when the area is occupied. Default: 0.95 (95%).
P(Active | Not Occupied)The probability that a motion sensor is active when the area is not occupied (false positive rate). Lower values (closer to 0.0) mean fewer false positives. Default: 0.005 (0.5%).
Door Sensors
Door Active StateThis is the state of the door that will be used to detect occupancy.
Door WeightThe weight given to door sensor inputs in the occupancy calculation.
Lock Sensors
Lock Active StateThis is the state of the lock that will be used to detect occupancy.
Lock WeightThe weight given to lock sensor inputs in the occupancy calculation.
Window Sensors
Window Active StateThis is the state of the window that will be used to detect occupancy.
Window WeightThe weight given to window sensor inputs in the occupancy calculation.
Cover SensorsCover entities (blinds, shades, garage doors, shutters) that indicate occupancy when their state changes.
Cover Active StatesThe states of the covers that indicate occupancy (e.g., open, opening, closing).
Cover WeightThe weight given to cover sensor inputs in the occupancy calculation.
Media Players
Media Active StatesThese are the states of the media players that will be used to detect occupancy.
Media WeightThe weight given to media player inputs in the occupancy calculation.
Occupancy Threshold (%)The probability threshold above which the area is considered occupied.
Enable Time DecayWhether to enable time-based decay of occupancy probability.
Decay Half-LifeTime window over which occupancy probability decays by half. Set to 0 to use the purpose-based default value, or enter a value between 10 seconds and 1 hour to override.
Minimum Prior OverrideThe minimum prior probability that will be used regardless of learned patterns. Set to 0.0 to disable (default).
Exclude from All AreasWhen enabled, this area won't contribute to the All Areas aggregate sensors. Useful for garages, driveways, and outdoor areas.
Closed door means still occupiedFor a room with one way in, such as a bathroom. While its doors stay closed after motion, the area stays occupied, even if motion loses someone keeping still. It clears when a door opens, or after the Wasp in Box maximum duration (an hour by default). Needs a door sensor. Replaces Wasp in Box.
Enable Wasp in Box (deprecated)Deprecated: being replaced by a built-in closed-door hold that takes over this setting automatically. Enable wasp-in-box behavior and entity for this area. Useful for single-entry rooms like bathrooms.
Motion TimeoutHow long motion remains valid after detection.
Sensor WeightThe weight given to this sensor in the occupancy calculation.
Max DurationMaximum duration that the wasp-in-box stays active after the last detected motion.
Verification DelayThe delay after closing the last door before any detected motion is considered as actual occupancy. (0 = disabled).
Sleep Start TimeThe time when your sleep schedule begins. Areas with the 'Sleeping' purpose will use their configured decay half-life during this period.
Sleep End TimeThe time when your sleep schedule ends. Areas with the 'Sleeping' purpose will behave like 'Relaxing' areas outside of sleep hours.
Sensor health monitoringWhen enabled, the integration raises Home Assistant repair issues for stuck, unavailable, or never-triggered sensors and for slow or failing analysis cycles. Turn off to silence all repairs from this integration; previously raised issues will be cleared on the next analysis cycle.
Sensor state precision (decimals)Lower values significantly reduce recorder database writes from diagnostic sensors. 0 is recommended unless you need sub-percent resolution.
Away mode entityOptional. A boolean entity (input_boolean, binary_sensor or switch) that is on while the household is away, such as a vacation-mode toggle. While it is on, time away is left out of learning and the stuck-inactive and never-triggered sensor alerts pause. When set, it is used for alerts instead of person and device tracking. Leave empty to use person tracking for alerts only.
Select a person

Texts from the code of Hankanman/Area-Occupancy-Detection.

Entities

Binary sensorsOccupancy Status, Wasp in Box, Sleeping
NumbersOccupancy Threshold
SensorsOccupancy Probability, Prior Probability, Decay Status, Detected Activity, Activity Confidence, Evidence, Presence Confidence, Environmental Confidence, Sensor Health, Accuracy

Actions

Run AnalysisRun the analysis for all areas in the area occupancy instance.
Export ConfigExport the complete integration configuration as YAML.
Purge Area HistoryDelete all learned history for a single configured area (priors, correlations, intervals, aggregates, cached occupied intervals) without removing the area from the integration. Use this when a room's learned behavior is no longer accurate and you want the integration to re-learn from scratch.Fields: Area
Get Time PriorsReturn the learned weekly occupancy-prior forecast for each area: for every weekly slot (day of week x time of day) the probability that the area tends to be occupied. Unlike the occupancy probability sensor (a current-state estimate), this exposes priors for future slots so other integrations can build a forward-looking occupancy profile, for example to pre-heat a room before its habitual occupancy. Returns response data only.Fields: Area
Set Area OptionChange one configured area's detection tunables from an automation or script. Values go through the same validation and purpose-default handling the configuration UI applies, so an automation cannot put an area into a state the UI would reject. Structural configuration (which entities belong to an area, adjacent areas) is deliberately not settable here.Fields: Area, Occupancy threshold, Enable time decay, Decay half-life, Minimum prior override, Enable Wasp in Box, Closed door means still occupied

Troubleshooting

DiagnosticsDownloads a diagnostics file to attach to a bug report.
Repair noticesNotices it can show in Settings, Repairs:Wasp in Box is being replaced by a built-in closed-door hold, Has learned it is occupied most of the time

From the README

Have you ever had your lights turn off while you're still in the room? Or watched your smart home mark you as "away" while you're sitting perfectly still, watching TV? These frustrating experiences happen because most occupancy detection relies on simple motion sensors that can't understand context.
Area Occupancy Detection solves these real-world problems by thinking more intelligently about what "occupied" really means. Instead of just checking if motion was detected, it combines multiple clues, learns from your patterns, and calculates the probability that someone is actually there.
Bayesian Occupancy Detection: Combines multiple sensor inputs using Bayesian probability for accurate occupancy detection.
Dual-Model Approach: Separates presence indicators (motion, media, appliances, doors, windows, covers, power, sleep) from environmental support (temperature, humidity, CO2, etc.). Presence sets the…
Multiple Sensor Support:
Motion/Occupancy Sensors: Primary input and ground truth for detecting presence.
Media Devices: TV, media players, and similar devices as activity indicators.
Appliances: Switches or sensors representing devices like fans, PCs, or other appliances.
Cover Sensors: Blinds, shades, shutters, and garage doors being operated.
Environmental Sensors: Temperature, humidity, illuminance, CO2, sound pressure, atmospheric pressure, air quality, VOC, PM2.5, and PM10 sensors contribute subtle occupancy clues.
Doors and Windows: Entry/exit and ventilation patterns.

From the README of Hankanman/Area-Occupancy-Detection, MIT License. Shortened.