FAQ and Troubleshooting

FAQ and Troubleshooting

Getting Started

1. Do I have to configure anything to get started?
2. How is this different from other freeze, unavailable, and battery automations and blueprints?
3. What should I globally mute?
4. How do I set up email?
5. What is still not built?
6. What is next?

How It Works

7. Why does it watch devices instead of entities?
8. What are gaps?
9. What is a bad signal day?
10. What is the difference between Battery: Low and Battery: Falling?
11. Will it survive a restart or reboot?
12. Will this slow my system down or cause lag in my automations?

Understanding the Numbers

13. Why is Devices: Watched lower than my device count?
14. Why is Devices: Learned zero, or low?
15. Why does Status say Learning?
16. Why does the signal report show a device I know is fine?

Troubleshooting

17. I muted something by accident, will it have to be re-learned after I un-mute it?
18. A device shows as "not reported". What does that mean?
19. A dead device is not showing in the Device: Frozen count.
20. A battery is one percent above my threshold and still flagged.
21. My Zigbee coordinator went down. What do I see?
22. Every MQTT device went unavailable at once. What happened?
23. The log says a notification service was not found.
24. The house lost power. What happens when it comes back?
25. How do I show the brief or the signal report on a dashboard?
26. Something looks wrong. What do you need from me?

---

Getting Started

1. Do I have to configure anything to get started?

No. Install it, add it, and it starts watching every device immediately with pre-configured defaults. Two things are worth doing on day one: press the three enable buttons on the device page, and tell it where to send alerts on the Notifications and Daily Brief screen.

2. How is this different from other freeze, unavailable, and battery automations and blueprints?

Automations and blueprints watch a list of entities you maintain, against a timeout you guess at. Device Sentinel watches every device automatically and learns each one's own reporting rhythm, so a chatty motion sensor and a sleepy door sensor each get a freeze window that fits them. There is no list to maintain and no timeout to guess.

3. What should I globally mute?

Anything you do not want reported: phones, tablets, and watches (they leave the house and sleep on their own schedule), network presence trackers, and TVs or media devices that nap. Service entries and cloud connections are already set aside automatically. When in doubt, leave a device watched; muting is one click later, on the Exclusions and Muting screen.

4. How do I set up email?

Add and configure Home Assistant's SMTP integration, then open the Notifications and Daily Brief screen and pick the new notify service under Send the Full Brief To. The full styled brief arrives in your inbox on its schedule.

5. What is still not built?

Two things. Signal is experimental: bad signal days are recorded and reported and never alert, and Signal Strength says why and how you can help settle it. And the coordinator is read on Zigbee2MQTT and ZHA but not yet on Z-Wave, which needs a volunteer who runs it.

6. What is next?

A Device Sentinel dashboard. One ready-made screen that puts the whole integration in one place: the problem list to act on, the daily brief to read, the battery report and the signal report beside it, and the status of your bridge and broker at a glance. You will install it from HACS, point it at your system, done. It is not built yet, but it is where this project is heading.

How It Works

7. Why does it watch devices instead of entities?

Because hardware fails as a whole. If any entity on a device reports, the device is alive. Watching at the device level means one verdict per physical thing, not thirty per gadget.

8. What are gaps?

A gap is the quiet time between two reports from a device. Every device has a natural gap size: seconds for a motion sensor in a hallway, hours for a door that is rarely opened. Device Sentinel records each device's longest gap per day, and that history becomes the device's rhythm.

9. What is a bad signal day?

A day when a device's radio link sat well below its own normal. Each night the day's readings become a time-weighted fifth percentile, and that is compared against the median of the days before it. The day counts as bad only when the fall is large in the device's own units, 25 LQI points or 6 dB by default, and also large measured in the device's own spread, 4 by default. Both gates together are what let a steady link and a jittery one be judged fairly. The Signal Report shows it for the whole fleet.

10. What is the difference between Battery: Low and Battery: Falling?

Low is about now: the level is at or below your threshold. Falling is about the future: the level is dropping fast enough to reach empty within your Days Till Empty setting, even if it reads high today. Falling exists because some cells hold near full charge for their whole life and then drop quickly at the end; The Battery Report tells that story.

11. Will it survive a restart or reboot?

Yes. Learned rhythms, device clocks, problem list state, and any freeze in progress all survive. A device that had been silent twenty hours before a reboot is still a twenty-hour silence after it.

12. Will this slow my system down or cause lag in my automations?

No. Device Sentinel only listens to events Home Assistant already produces: it polls nothing, sends nothing over your radio networks, and never sits between a device and your automations. Its bookkeeping happens in memory, and disk writes are batched on a timer you control. Built to Be Efficient has the numbers.

Understanding the Numbers

13. Why is Devices: Watched lower than my device count?

Because some devices are set aside, for one of four reasons. Service entries, add-ons, cloud connections, and dashboard helpers have no hardware to watch. A device disabled in Home Assistant, by you or by its integration, cannot report at all, so its silence would say nothing about the hardware. A device with no entities registered has nothing that could ever report. And an integration you put on the exclude list on the Exclusions and Muting screen is never watched by your choice, because what it publishes is not a measurement of your house; phones and ping probes start on that list. The Devices: Set Aside count on the device page holds all four, and the classification report names which reason caught each one.

14. Why is Devices: Learned zero, or low?

Learning takes seven days of history per device, so a fresh install climbs slowly. And devices with no natural heartbeat, buttons and remotes that only speak when pressed, never establish a rhythm at all.

15. Why does Status say Learning?

Because no device has finished learning its rhythm yet. It flips to Watching when the first device arms, and unavailable and unknown detection is live in the meantime.

16. Why does the signal report show a device I know is fine?

The strip never shows fewer than five rows, so on a quiet fleet the last rows are simply the least good of a healthy set rather than devices with anything wrong. A ringed cell is the thing to look at, and a device with no ringed cell has not had a bad day at all. If several devices fell on the same day, look for one router rather than several devices.

Troubleshooting

17. I muted something by accident, will it have to be re-learned after I un-mute it?

No. Muting stops the reporting, never the learning. The moment you un-mute a device, its full history, which is retained, is there and judgment resumes instantly.

18. A device shows as "not reported". What does that mean?

Device Sentinel has never seen it say anything since it was discovered. Usually that is a device that is dead, unpowered, or was removed without being deleted from the registry. If the device is genuinely alive, pressing Enable Last Seen on the device page often gives it a voice. A device you disabled in Home Assistant is set aside rather than reported this way, because a disabled device cannot speak.

19. A dead device is not showing in the Device: Frozen count.

Three usual reasons: the count sensor ships switched off, so enable it from the entity's settings; the device is still learning and can only be judged unavailable or unknown so far; or the device is a button-type with no heartbeat, which is not judged frozen by design.

20. A battery is one percent above my threshold and still flagged.

That is deliberate. A flagged battery stays flagged until it climbs a couple of points clear of the threshold, so a cell hovering exactly at the line does not flap in and out of your reports.

21. My Zigbee coordinator went down. What do I see?

On Zigbee2MQTT and ZHA, one row naming the coordinator and how many devices are behind it, rather than a row per device. Those devices really were unreachable and their verdicts are recorded, but they are symptoms of one fault, so they are counted rather than listed. Your phone gets one message once the outage settles, and the tally updates silently after that. Everything clears when the coordinator returns. Two devices keep their own rows: one that was already broken before the outage, and one that does not come back afterwards. The Problem List has the detail.

22. Every MQTT device went unavailable at once. What happened?

Your MQTT broker stopped. The Broker: MQTT sensor records the outage, the devices are cleared of blame, and you get one row and one message naming the broker rather than dozens. A broker outranks any bridge, because a broker that is down takes every bridge with it. The Bridge and Broker Sensors explains it.

23. The log says a notification service was not found.

A notify service you picked was renamed or removed. Open the Notifications and Daily Brief screen and re-pick a valid service; until then the integration logs the warning and carries on.

24. The house lost power. What happens when it comes back?

The unclean shutdown is recognized on the next start and reported. At most, one write interval of routine clock progress is lost, and that repairs itself as each device reports again. Nothing learned is at risk.

25. How do I show the brief or the signal report on a dashboard?

Add a Webpage card pointed at /local/device_sentinel/daily_brief.html, or signal_report.html, or battery_report.html. The addresses never change. For the problem list, use the standard to-do list card pointed at todo.device_sentinel_problem_list.

26. Device Sentinel will not start and says it cannot read its storage file.

The file it keeps its learned data in has been damaged, usually by a power cut or a disk problem partway through a write. Device Sentinel stops rather than starting on data it cannot trust, and the message names the file.

Nothing has been changed or deleted. Your devices are untouched, and the copy Device Sentinel keeps of the last file that passed every check is still beside it.

You have two ways forward. Restore your Home Assistant backup, which keeps everything Device Sentinel had learned up to the moment the backup was taken. Or move the named file out of the .storage folder, which starts the learning again from nothing while leaving every setting, every mute and every exclusion exactly as you left them. Nothing else in Home Assistant is affected either way.

The smaller companion file is different. If only that one is unreadable, Device Sentinel starts anyway, says so, and loses at most a few minutes of live counters.

27. Something looks wrong. What do you need from me?

Two things: what you expected and what you saw, and the diagnostics download from Settings, Devices and Services, Device Sentinel, three-dot menu, Download diagnostics. Then open an issue and attach both.