Sensor Health Monitoring¶

The integration continuously monitors the health of all configured sensors and alerts you through Home Assistant's Repairs system when issues are detected. This helps you identify degraded sensors that may be reducing occupancy detection accuracy.

How It Works¶

During the hourly analysis cycle, the integration checks each sensor for:

• Stuck active — a binary sensor has been continuously active for longer than expected
• Stuck inactive — a binary sensor hasn't changed state for an unusually long time
• Unavailable — a sensor has been offline (unavailable, or gone from Home Assistant) for more than 1 hour
• Never triggered — a sensor has never been active since it was added (checked after 7 days)

When an issue is detected, a repair entry appears in Settings → System → Repairs with a description of the problem and actionable troubleshooting steps. Repairs are dismissed automatically as soon as the sensor recovers, without waiting for the next hourly check.

Detection Thresholds¶

Thresholds are tuned per sensor type to avoid false positives:

Stuck Active (sensor continuously "on")¶

The base threshold is multiplied by the area's purpose, so rooms where long stillness is normal get much more headroom:

Two exemptions apply: media_player.* entities are never flagged for being unavailable (a TV powering off is normal operation, not a fault), and the virtual Sleep presence sensor is excluded from all health checks.

A stuck sensor stops counting¶

Once a sensor is flagged stuck active, it no longer counts as evidence. Otherwise a TV left paused for a day would hold the room occupied with nobody there. The sensor counts again the moment it changes state, including a move from one active state to another, such as that TV starting to play. When a stuck stretch finally ends, it doesn't start a decay either, because it never counted in the first place.

The repair stays open for you to fix. If the long activity is real (a TV that genuinely plays all day), Ignore the repair and the sensor keeps counting.

Stuck stretches don't train the model either. When the area learns from history, any motion or media stretch longer than its stuck-active threshold is cut to the threshold, so a sensor stuck on can't teach the room a habit. Sleep sensors are never cut.

Stuck Inactive (sensor never changes state)¶

Other Checks¶

Away from home¶

A sensor that sits idle while everyone is away isn't stuck or misconfigured. While the household is away, the stuck inactive and never triggered checks pause, and any open alerts of those two kinds clear. When someone comes back, idleness counts from the return rather than from before the trip, so a holiday doesn't raise every alert the moment you walk in. Stuck active keeps being checked while you're away, since a sensor that's on in an empty house is more suspicious, not less.

There are two ways to tell the integration the household is away. It uses one at a time, never both.

Person tracking is the default. When Home Assistant's Home zone counts nobody home (zone.home is 0), the household is away. This needs person entities with device trackers, which is what drives zone.home. Without them, or while none of them has a known location, the checks behave as they always have.

An away mode entity replaces person tracking. Under Configure → Global Settings → Away mode entity, pick an input_boolean, binary_sensor or switch that is on while you are away, such as a vacation-mode toggle. While it is on the household is away, and while it is off the household is home. Once one is set, zone.home and the person entities are not consulted at all. That suits a home with no person entities, and one where phone locations say something other than the truth, such as a house-sitter staying while you are away. Clear the field to go back to person tracking.

The entity is read during the hourly health check, so a change is picked up at the next one, and the return is timed to that check. While the entity is unavailable or unknown, or no longer exists, the checks run as they always have. They do not fall back to person tracking, so what pauses them never depends on which of the two happens to be readable.

If your entity is on while someone is home, such as an "anyone home" sensor, put a template binary sensor in front of it that reverses it, and pick that one:

template:
  - binary_sensor:
      - name: "Household away"
        state: "{{ is_state('binary_sensor.anyone_home', 'off') }}"

Excluded Sensors¶

The following sensors are excluded from health checks:

• Sleep sensors — virtual sensors that are managed by the integration
• Wasp in Box sensors — virtual sensors for bathroom occupancy
• Environmental sensors (temperature, humidity, illuminance, etc.) — only checked for unavailability, not for "stuck" states, since their values change continuously

Repair Issues¶

Repair entries appear in Settings → System → Repairs and include:

• The affected sensor's entity ID and area
• How long the issue has persisted
• The sensor type and applicable threshold
• Specific troubleshooting guidance

Severity Levels¶

Auto-Resolution¶

Repair entries are automatically deleted the moment the sensor recovers, rather than at the next hourly check:

• A stuck sensor changes state → repair disappears. A move from one active state to another counts, such as a paused TV that starts playing.
• An unavailable sensor comes back online → repair disappears. A sensor that comes back reading unknown counts as back: it is reachable and has yet to report a value.
• A sensor that hasn't triggered, or has never triggered, fires → repair disappears

New repairs are still raised by the hourly check, since every threshold is an hour or longer.

A sensor can't trigger while it is offline, so after an outage of an hour or more its inactivity checks count from when it came back. A sensor that spent five days offline doesn't return to a "hasn't triggered for eight days" repair.

A repair you Ignore stays ignored, including the next time the same sensor has the same problem, and is not deleted when the sensor recovers. To get alerts for that sensor again, un-ignore it from the ignored repairs in Settings → System → Repairs.

Sensor Health Entity¶

Each area gets a diagnostic sensor entity that exposes health status:

sensor.<area_name>_sensor_health

• State: Number of current health issues (0 = all healthy)
• Icon: mdi:heart-pulse when healthy, mdi:alert-circle when issues exist
• Entity Category: Diagnostic

Attributes:

The Evidence sensor also includes a health_status field in its details attribute for each entity, showing one of: healthy, stuck_active, stuck_inactive, unavailable, never_triggered, or excluded.

Pipeline Health¶

In addition to per-sensor checks, the same health monitor flags calculation pipeline issues per area — silent failures in the integration's own learning surface that would otherwise leave you wondering why occupancy looks wrong. These appear in Settings → System → Repairs alongside sensor issues, with their own translation key family (pipeline_health_*) so they're distinguishable.

How to read pipeline issues¶

Each repair entry includes a short numeric summary in the title (hours since the issue started, hours of cache age, etc.) and a longer description with What to do steps tailored to the failure.

• For the deepest detail, download diagnostics from the integration card — pipeline issues are surfaced under each area's health section, and the inputs that drove them (priors, cache age, correlation analysis_error fields) are visible in the same dump. See Diagnostics.
• All of these issues auto-resolve when the next analysis cycle finds the underlying state has recovered (e.g. the prior is learned, the cache rebuilds, analysis completes faster, correlations succeed).

Common Scenarios¶

Dead Battery¶

A Zigbee motion sensor runs out of battery and goes unavailable. After 1 hour, a repair entry appears:

binary_sensor.bathroom_motion_1 is offline in Bathroom

The motion sensor has been unavailable for 5 hours. The integration is currently falling back to learned priors for this area.

Stuck Sensor¶

A PIR sensor gets stuck in the "on" state (hardware malfunction). After the 8-hour base threshold (this area has no purpose multiplier):

binary_sensor.toilet_motion_1 appears stuck in Toilet

The motion sensor has been continuously active for 9 hours, which exceeds the 8-hour threshold.

Misconfigured Sensor¶

A kitchen oven binary sensor is configured but the power threshold is too high, so it never triggers. After 7 days:

binary_sensor.kitchen_oven may be misconfigured in Kitchen

The appliance sensor has never been active in 7 days of monitoring.

Tips¶

• Check the Sensor Health diagnostic entity in your dashboards to see at-a-glance health across areas
• Use the Evidence sensor's details attribute to see per-entity health status alongside probability contributions
• If a sensor is intentionally unused, consider removing it from the area configuration rather than ignoring the repair
• The health check runs hourly — new issues may take up to 1 hour to appear after a sensor degrades