How Device Sentinel Learns - TheThinkingHome/device_sentinel GitHub Wiki

How Device Sentinel Learns

A fixed timeout is a terrible way to judge a smart home. A motion sensor reporting every thirty seconds requires a completely different baseline than a door sensor checking in twice a day. Apply a global timeout, and you either get false alarms all morning or a dead motion sensor that goes unnoticed until tomorrow.

Device Sentinel solves this by quietly learning the unique reporting rhythm of every single device in your home.

Watching What Matters

If any entity on a device reports a real value, that device is alive. By watching at the physical device level, we avoid tracking thirty separate entities for a single multisensor.

The system automatically ignores virtual software, cloud connections, disabled hardware, and integrations you have chosen to exclude. If it cannot physically fail in your house, we don't watch it.

Learning the Rhythm

To figure out what is normal for a device, Device Sentinel measures its gaps, the quiet time between reports.

Every day, the system records the single longest gap a device produced, keeping a rolling two-week history. To find the true rhythm, it discards the absolute worst day as a fluke (like a temporary mesh hiccup or a router reboot) and takes the longest surviving gap as the baseline.

We only learn from completed gaps. This is a key rule. A device that goes silent and stays silent has not finished its gap. It is dead. The system will never learn that freezing is normal behavior, because a gap only counts when the device finally wakes up and speaks again.

Arming Your Fleet

A new device begins learning the moment you pair it. It takes seven days of history to fully arm. Until then, it is watched for unavailable states, but it will never be judged frozen because a brand-new schedule has no window to miss.

Devices without a natural heartbeat, like push buttons or remotes that only wake when pressed, never establish a regular rhythm. They will never arm, which is entirely by design. Because of this, your Devices: Watched count will always be higher than your Devices: Learned count.

Knowing When a Device Actually Spoke

Restarts, integration reloads, and bridge reconnects can produce massive bursts of traffic. When a Zigbee coordinator comes back online, it often republishes the last known state of every device it manages.

Device Sentinel looks past these artificial echoes by reading exact hardware timestamps whenever they are available. It knows the difference between a real sensor checking in and a system reboot echoing old data.

This is why the Enable Last Seen button on the device page matters. Where a device publishes a last_seen entity, that timestamp is the coordinator's own record of when it truly heard from the hardware, and no republished state can fake it.

Storms and Polling

Sometimes an entire integration's fleet of devices reports in the exact same second. Usually, this means a hub just reconnected, so those timestamps are thrown out.

However, some integrations deliberately poll their hardware on a timer. If an integration does this repeatedly, more than ten times in an hour, Device Sentinel recognizes the pattern, stops ignoring the bursts, and lets those devices safely learn their poll cadence as their normal rhythm.

Ignored Silences

Not every silence is a natural rhythm. The system deliberately throws out gaps caused by external events:

  • Coordinator and broker outages: If your Zigbee bridge or MQTT broker dies, the devices behind it are cleared of blame. We record the outage itself rather than learning a massive, fake silence for innocent sensors.
  • Unavailable stretches: We learn brief mesh hiccups, but throw out long unavailable stretches that were clearly fixed by a human intervention.
  • Pairing and Maintenance: If a device recovers during a pairing window or while you have Maintenance Mode active, your hands are credited and the silence is discarded.

Every one of these decisions is written down in your diagnostic reports so you always know why a gap was handled the way it was.

Lasting Memory

Everything learned survives a reboot. Device clocks, rhythms, and active faults are saved to disk. A device that has been silent for twenty hours before you restart Home Assistant is still twenty hours silent the moment the system comes back up.