FAQ and Troubleshooting

FAQ and Troubleshooting

Getting started

1. Do I have to configure anything to get started?
2. What works in this release yet?
3. How long before it actually does anything?

How it works

4. How is this different from a fixed timeout or other dead-sensor automations?
5. Why does it watch devices instead of entities?
6. Will it survive a restart or reboot?

Understanding the numbers

7. Why is Devices Watched lower than my device count?
8. Why is Devices Learned zero, or low?
9. Why does Status say Learning?
10. Why is a healthy device showing a small signal dwell number?

Troubleshooting

11. I excluded something, will it have to re-learn when I un-exclude it?
12. A device shows as "not reported". What does that mean?
13. A dead device is not showing in the Device: Frozen count.
14. A battery is one percent above my threshold and still flagged.
15. Something looks wrong. What do you need from me?
16. My Zigbee coordinator went down and the problem list filled with dozens of devices. Is that a malfunction?
17. Every MQTT device went unavailable at once. What happened?
18. The log says a notification service was not found.
19. The house lost power. What happens when it comes back?
20. What are the prephase-c files in my .storage folder?
21. How do I show the brief or the signal chart on a dashboard?

---

Getting Started

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

No. Device Sentinel runs on sensible defaults from the moment it is installed: it watches every device, learns each one's rhythm, and judges batteries and freezes without being told anything. The one thing worth setting is where alerts go, on the Notifications and Daily Brief screen, so detections reach your phone. Everything else is tuning you can leave alone.

2. What works in this release yet?

This is a pre-release built in layers. The layers currently live are: the learning engine; low battery detection; signal recording, with rail (stuck-signal) alerting now and weak-link dwell recording toward a future alert; the full freeze family (frozen, unavailable, unknown, never reported); the problem list; the notification engine in full, the per-family phone pushes, the persistent card, and the daily brief, emailed on its schedule; the silence-episode forensics; and the house-level record of restarts, coordinator outages, broker outages and integration reloads, which is what lets a device's silence be explained by something other than the device. Weak-link signal alerting is the one layer still held back, and it is the current work.

3. How long before it actually does anything?

Battery and unavailable detection work from the first day. Freeze detection needs each device to learn its rhythm first, seven days by default, so a fresh install reads zero Devices Learned for its first week. That is the system working, not stalling: it will not guess a device's normal until it has watched enough to be sure. Each device arms itself as it crosses the line, so the count climbs over the first week rather than flipping all at once.

How It Works

4. How is this different from a fixed timeout or other dead-sensor automations?

A fixed timeout has to pick one number, and no number fits a whole home: a motion sensor that reports every 30 seconds and a water meter that reports twice a day cannot share a threshold. Set it tight and the slow device flags constantly; set it loose and the fast device is dead for an hour before anyone knows. Device Sentinel learns each device's own reporting rhythm and sets its freeze window from that, so every device is judged against its own normal. There is no timeout to pick, and nothing to re-tune as you add hardware.

5. Why does it watch devices instead of entities?

Because the question it answers is "is this piece of hardware alive?", and the hardware is the device, not the entity. One device often exposes several entities, a sensor might report temperature, humidity, battery, and signal, and they do not all update on the same beat. Any one entity reporting proves the whole device is alive, so watching per device asks the question that matters: has this hardware gone silent? Watching per entity would flag a device as frozen because its humidity had not changed while its temperature was updating fine. The finest grain the integration uses is a label on an entity, to keep that one entity from feeding its device's judgment; there is no per-entity report, by design. Liveness of hardware is the scope, not correctness of individual readings.

6. Will it survive a restart or reboot?

Yes, fully. The learned statistics, every device's clock, and any flag in progress are stored on disk. A device twenty hours into a freeze is still twenty hours frozen after a reboot, and a battery low since Tuesday still reads low since Tuesday. A restart does not erase a silence either: where a device's integration publishes a last-contact time, Device Sentinel reads that rather than the moment a message arrived, so a bridge republishing its stored state cannot make a silent device look alive. See How Device Sentinel Learns for how that works and what happens when an integration offers no such time.

Understanding the Numbers

7. Why is Devices Watched lower than my device count?

Devices with no hardware behind them (service entries, cloud connections, integration containers) are classified out automatically; they are the Service Devices Ignored count. The rest of the difference is your own exclusions. The classification report names where every device landed; see The Reports.

8. Why is Devices Learned zero, or low?

Each device needs enough completed days to establish a rhythm, seven by default. A fresh install reads zero for its first week; that is the system working, not stalling. Some devices never arm at all: buttons and remotes have no heartbeat to learn, by design, which is why Devices Learned is not expected to ever reach Devices Watched.

9. Why does Status say Learning?

No device has established its rhythm yet. It flips to Watching at the first one and stays there.

10. Why is a healthy device showing a small signal dwell number?

That is the design working. Dwell counts the time a device spends at or below its own learned signal floor, and the floor is set right at the level a healthy device brushes on its worst moments. So a small reading, in the 0 to 5 percent range, is proof the line sits where normal variation just reaches it, which is what makes a real problem stand out as big and obvious. If nothing ever touched the line, the line would be telling you nothing. Sustained dwell, not the occasional brush, is the anomaly. See Signal Strength.

Troubleshooting

11. I excluded something, will it have to re-learn when I un-exclude it?

No. Excluded items are still watched and learned; only judgment and reporting are suppressed. Undoing an exclusion is instant and complete.

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

It has produced nothing at all since Device Sentinel first saw it, for at least 48 hours. This catches the case that would otherwise slip through: a device with no learned rhythm and often no live entity, a registry ghost, a device dead before install, a monitor whose target is gone. It is yours to sort out: fix it, delete it if it is a stale registry entry, or send it to the Freeze Detection exclude list if it is meant to be quiet for now.

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

Check whether it is globally excluded. A globally excluded device is judged by nothing, so it is never counted as down, by design. The reports STATUS column shows it as global. If you want it watched for freezes, remove it from Global Exclusions; if you want it watched for battery and signal but not called down, the freeze exclude list is the narrower tool.

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

A flagged battery clears at 2 points above the threshold, not 1. The margin exists because battery readings rebound under load; without it, a cell at the line would flap in and out of the report.

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

Download Diagnostics: Settings, Devices and Services, Device Sentinel, three-dot menu, Download Diagnostics. Attach it to an issue at the issue tracker. It carries the learned state, the settings in effect, and the classification, and answers most questions without screenshots. Notification targets are redacted automatically.

16. My Zigbee coordinator went down and the problem list filled with dozens of devices. Is that a malfunction?

No, that is the mesh outage seen truthfully: every device really was unreachable, so each was listed, and each left the list on recovery. The record keeps it tidy: the coordinator's down and up are one system event with the outage duration, and the silences it caused are set aside from learning with the cause named, no (bridge down) in the episode report, so a mesh incident cannot distort any device's learned rhythm. The daily brief collapses the flood into one line rather than one per device, which is the part a person actually reads: "64 devices went unavailable at 1:50 AM and recovered, revived by the z2m bridge going down and coming back." Nothing needs doing beyond fixing the coordinator.

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

The MQTT broker stopped. Device Sentinel watches the broker directly, so the outage is recorded as one event with its duration and the devices are not blamed for it. A coordinator cannot report this: when the broker stops, nothing delivers the coordinator's own last message, because the broker is what delivers it, so the bridge sensor goes on reading as running while everything behind it is silent. See What Is Recorded About Your House.

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

A notify service picked on the Notifications screen no longer exists, such as a renamed phone or a removed integration. The integration logs the warning and continues. To fix it, return to the Notifications and Daily Brief screen and pick a valid service.

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

The start after a power cut is recognized as following an unclean shutdown, and the brief says so. Devices already on the problem list keep their history, everything else starts its clock fresh so nothing is falsely accused of freezing during the outage, and silence measured before the cut still counts toward learning, marked truncated in the episode report. What Is Recorded About Your House has the full story. Nothing needs doing.

20. What are the prephase-c files in my .storage folder?

A one-time backup of both storage files, taken automatically the first time a release started that changed how storage is written. They are what a rollback to a version before 0.10.0 would need. They are small, they are never written again, and they can be deleted once you are confident you will never roll back that far.

21. How do I show the brief or the signal chart on a dashboard?

Add a Webpage card and point it at /local/device_sentinel/daily_brief.html or /local/device_sentinel/signal_dwell.html. Those two addresses never change; each always shows the newest version. Give the card a fixed height or aspect ratio so the page has room. Dated copies of both pages are kept for two weeks in the same folder if you want an older day.