FAQ and Troubleshooting - TheThinkingHome/device_sentinel GitHub Wiki

FAQ and Troubleshooting

Getting Started

  1. Do I have to configure anything right away?
  2. How is this different from a standard blueprint?
  3. What devices should I globally mute?
  4. How do I get my Daily Brief via email?
  5. What's still missing?

How It Works

  1. Why watch devices instead of entities?
  2. What exactly is a "gap"?
  3. How do you define a "bad signal day"?
  4. Low Battery vs. Falling Battery: What's the difference?
  5. Does the integration forget everything when I restart Home Assistant?
  6. Will this slow down my Home Assistant server?

Understanding the Numbers

  1. Why is my "Watched" count lower than my actual device count?
  2. Why is my "Learned" count so low?
  3. Why does the Status sensor just say "Learning"?
  4. Why does a nearly full battery say Steady when its level dropped?

Troubleshooting

  1. I muted a device by accident. Does it have to re-learn everything?
  2. What does "never reported" mean?
  3. Why isn't a dead device showing in the "Device: Frozen" sensor?
  4. My battery is slightly above the threshold, but still flagged as Low.
  5. My Zigbee coordinator crashed. Will my phone explode?
  6. Every MQTT device in my house died at the exact same second.
  7. Error: Notification service not found.
  8. My house lost power. Are my statistics ruined?
  9. Where do I read the Daily Brief?
  10. I found a bug. What do you need?
  11. My Bluetooth proxy is listed under three integrations. Will it be reported three times?
  12. A device has the wrong type. Does it matter?

Getting Started

1. Do I have to configure anything right away?

No. Install it, and it immediately starts watching every device in your house using sensible defaults. But to get the most out of it on day one, do two things: press the three Enable buttons on the Device Page, and tell it where to send your alerts under Notifications and Daily Brief. Then open the Recommendations tab on the dashboard and work through its cards: devices with no power source or no type can be set right on the card, and a device with no area is one click from its page.

2. How is this different from a standard blueprint?

Blueprints ask you to maintain a list of entities and guess a timeout value. Device Sentinel watches every device automatically and learns their unique reporting rhythms. A chatty motion sensor gets a tight window; a sleepy door sensor gets a generous one. No lists, no guessing.

3. What devices should I globally mute?

Anything you don't want to be bothered about: phones, tablets, smart watches (since they leave the house), network trackers, and TVs that nap. If you aren't sure, leave it watched. You can always mute it later with one click on the Exclusions and Muting screen.

4. How do I get my Daily Brief via email?

Configure Home Assistant's SMTP integration. Each email recipient then appears under Send the Full Brief To on the Notifications screen as Email, HTML. Choose those rather than the older notify. email actions.

5. What's still missing?

Two things. Signal alerting is experimental: it records and reports bad signal days, but weak-link alerting stays off because no signal pattern has been shown to predict a real failure. And the running controllers for Z-Wave and Matter aren't read yet, though integration outages are caught and their devices get time to rejoin when they return. Check their respective pages to see how you can help.

How It Works

6. Why watch devices instead of entities?

Hardware fails as a whole unit. If any entity on a multisensor reports in, the physical device is clearly alive. Watching at the device level gives you one verdict per physical gadget, rather than thirty separate alerts for a single dead weather station.

7. What exactly is a "gap"?

It's the silence between two reports. A motion sensor might have a natural gap of a few seconds, while a guest room window sensor might sit quiet for a week. Device Sentinel tracks the longest gap a device produces each day to learn its true baseline rhythm.

8. How do you define a "bad signal day"?

A day when a device's radio link performs significantly worse than its own normal baseline. Device Sentinel looks for a drop that is large in absolute terms (like 25 LQI points) and large compared to the device's usual jitter. Checking both judges steady links and bouncy links fairly. The dashboard's Signal Trends tab shows this in action.

9. Low Battery vs. Falling Battery: What's the difference?

Low means right now: the cell has crossed your flat percentage threshold. Falling predicts the future: the cell is dropping fast enough to hit zero within your warning horizon (like 30 days). A lithium battery might read 80% today but be completely dead by Friday; the Falling detector catches that cliff-edge.

10. Does the integration forget everything when I restart Home Assistant?

No. Rhythms, clocks, problem lists, and standing freeze verdicts are continuously saved to disk. A device that was silent for twenty hours before a reboot is still twenty hours silent when the system comes back up.

11. Will this slow down my Home Assistant server?

Not at all. Device Sentinel just listens to the events Home Assistant is already generating. It doesn't poll, it doesn't broadcast on your radio networks, and it batches its disk writes on a timer you control. Built to Be Efficient has the receipts.

Understanding the Numbers

12. Why is my "Watched" count lower than my actual device count?

Because Device Sentinel automatically ignores virtual junk. It sets aside service integrations, add-ons, cloud trackers, disabled devices, devices with no entities, clones of hardware another integration already watches, and anything you've put on the Exclude list.

13. Why is my "Learned" count so low?

It takes seven days of history before a device can be judged frozen. A brand new install will climb slowly. Also, devices without a natural heartbeat, like push-button remotes that only wake when you press them, never establish a rhythm, which is entirely by design.

14. Why does the Status sensor just say "Learning"?

Because not a single device has finished its 7-day learning window yet. It changes to Watching once your first device has learned its rhythm. Don't worry, dead and unavailable detection is already live while it learns.

15. Why does a nearly full battery say Steady when its level dropped?

Most batteries report in half-point steps and wobble up and down from day to day. Device Sentinel compares each week's average with the week before, so a wobble cancels out and only a real fall counts.

Troubleshooting

16. I muted a device by accident. Does it have to re-learn everything?

No. Muting stops alerts, not learning. The moment you un-mute it, its full history is waiting and judgment resumes instantly.

17. What does "never reported" mean?

It means Device Sentinel has never seen the device speak since it was discovered. It's usually a dead battery, an unpowered device, or a leftover entry in Home Assistant for a device that is gone. Try pressing Enable Last Seen on the device page to see if that gives it a voice.

18. Why isn't a dead device showing in the "Device: Frozen" sensor?

Three possibilities: 1) You haven't enabled the sensor yet (it ships disabled by default), 2) The device is still in its 7-day learning phase, or 3) It's a button or remote with no heartbeat, which Device Sentinel doesn't judge for freezes.

19. My battery is slightly above the threshold, but still flagged as Low.

That is deliberate. A battery reported low stays reported until it climbs two points clear of the threshold. This stops a cell hovering exactly at the line from spamming you with alerts every time it fluctuates.

20. My Zigbee coordinator crashed. Will my phone explode?

No. Device Sentinel catches the coordinator failure directly. You get one row and one alert naming the coordinator and counting the devices behind it. The devices behind it are cleared of blame. When the coordinator comes back, that same row counts your devices home and gives the slow ones a few minutes before any of them is reported on its own.

21. Every MQTT device in my house died at the exact same second.

Your MQTT broker crashed or restarted. Device Sentinel watches the broker directly, so it will record the outage and blame the broker, not your seventy-four smart plugs.

22. Error: Notification service not found.

You probably renamed your phone or uninstalled the companion app. Head to the Notifications and Daily Brief screen and re-pick your valid targets. Device Sentinel also raises a Repair card offering to remove the dead targets for you.

23. My house lost power. Are my statistics ruined?

No. The integration recognizes the unclean shutdown when it boots back up. At most, you lose one write-interval of routine clock progress (about 15 minutes), which repairs itself the next time your devices check in. Nothing learned is lost.

24. Where do I read the Daily Brief?

Open Device Sentinel in your sidebar. The Daily Brief tab shows it for any of the last fourteen days. The file itself is config/device_sentinel/daily_brief.html.

25. I found a bug. What do you need?

Say what you expected to see and what actually happened, and attach your diagnostics file (Settings > Devices and Services > Device Sentinel > ... > Download diagnostics). Then open an issue on GitHub.

26. My Bluetooth proxy is listed under three integrations. Will it be reported three times?

No. If two integrations see the same hardware, Home Assistant lists it twice, and a Bluetooth proxy can be listed by ESPHome, by Bluetooth and by your router integration. Device Sentinel watches the copy that reports and sets the others aside as clones. The Classification tab reads "clone" for each copy, and the watched device's page names them under Same hardware. You don't have to exclude or mute anything.

27. A device has the wrong type. Does it matter?

Only for sorting. The type comes from the device's own entities or from a known model, and it decides where the device sits when you narrow a tab to one type. Press the pencil beside Type on the device's page and pick the right one; your answer covers every device of that model. The Recommendations tab lists devices with no type and models whose devices disagree.