The Diagnostic Reports

The Diagnostic Reports

This page covers the three diagnostic files the integration writes for the system administrator. They are located in config/device_sentinel/, readable in any file editor, and exist so you can see what has been learned and what has happened without having to trust a summary number. The pages written for a person rather than a maintainer, the daily brief, the battery report, and the signal report, each have their own chapter: The Daily Brief, The Battery Report, and The Signal Report.

All three files are written at startup, at midnight, at your scheduled daily brief time, and whenever you press the Regenerate Reports button.

device_telemetry.md

This is the learning ledger. It contains one row per watched device, listed alphabetically by name so you can find a device by scanning rather than hunting.

Each row leads with the device and the integration it belongs to, formatted as Device (Integration). This is a way to differentiate between near-duplicates. The row carries the learned daily maxima, today's running maximum, the rhythm so far, and the signal floor where the device reports a signal. If you ever wonder why a device's freeze window is what it is, the history is reported here.

A STATUS column reads either Reported, or Muted with the reason in parentheses: GLB for global, or BAT, SIG, FRZ for the three section mutes.

The Reporting Devices section above the chart lists every device with a fault from any family, grouped by Freeze, then Battery, then Signal, and sorted alphabetically within each group. Each line carries the fault, how long it has lasted, and the device's problem-list state: [○ open], [✓ acknowledged], or [✗ removed from list] when a person deleted the item by hand while the fault persisted. Acknowledged faults are shown here on purpose; the checkbox silences notifications, not the diagnostics.

classification.md

This table contains one row per device. Its columns mark whether a device is WATCHED (has hardware and is recorded) or SET ASIDE, and the SET ASIDE cell names the reason rather than printing a tick: service, for a device with no hardware to watch; disabled, for one Home Assistant has switched off; no entities, for one with nothing registered that could report; or ignored, for one whose integration you put on the ignore list. For a watched device, it marks whether the global mute has it and why: Global (integration), Global (label), or Global (device), naming which rule caught it. COPIES flags a name shared by more than one registry device.

How to use it: if a device is not being watched and you think it should be, this file says why in one lookup.

silence_episodes.md

The third report is a forensic record rather than a status file. It answers a question the other two cannot: when a device goes quiet for much longer than usual and then reports again, did it choose to speak, or did something make it speak?

A row opens when a device's silence passes a share of its own freeze limit, well before any judgment. How early a row opens is adjustable via the episode recording threshold on the Advanced screen.

The row records when the silence began, the device's rhythm and freeze window at that moment, how long the silence ran, how it ended, and, where relevant, how long the device was unreachable. The row closes in one of two ways:

• Resumed: The device reported on its own.
• Intervention: Something happened that revived it: a restart, an unclean shutdown, a broker outage, an integration reloading, or a bridge or hub reconnecting. An intervention truncates the record rather than completing it, because all we know is that the device had been silent at least that long.

The LAG column is the point of the file. It is filled when a device speaks after an intervention, and it measures the time from the lever, the restart or reconnect, to that first report.

• Seconds mean the intervention revived a stuck device. If you see the same devices at seconds night after night, you have a stuck-radio problem that wider freeze windows would only hide.
• Hours mean the device was never stuck; it was just quiet on a rhythm longer than anything the statistics have been able to observe, because interventions keep interrupting the silence before it completes. Those devices are healthy, and their windows will widen on their own as their real gaps start completing unaided.

Episodes are kept for fourteen days, matching the window every verdict is judged on. How much of the underlying daily history is kept is separate and is set on the Advanced screen.

The LEARNED Column

The LEARNED column says whether the completed gap reached the fourteen-day statistics, and when it did not, or was limited, why. The row explains itself:

• yes: Learned in full.
• no (unavailable) or no (unknown): The device sat in that state partway through its silence for longer than a brief hiccup, so its return may have been a hand fix rather than a real self-recovery. The integration cannot see a hand on a device; the only clue is how long it was unreachable, which the UNAVAIL column records. That column is what the two blip-tolerance settings on the Advanced screen are tuned from. A stretch of only a few seconds is treated as a passing hiccup, the gap is learned normally, and the UNAVAIL cell stays blank. Historical rows may read the older form no (taint, unavailable).
• no (bridge down): The silence overlapped a coordinator outage that ended with the bridge reconnecting. The outage explains the silence, so the row names the cause rather than the state the device happened to show.
• no (pairing): The device came back during a Zigbee pairing window, which is a manual re-pair, so the gap is discarded.
• no (maintenance): The device recovered inside an open Maintenance Mode window, so the return is read as your fix and the silence is set aside rather than learned.
• no (disabled): The silence spans a spell when the device was disabled in Home Assistant. A disabled device cannot speak, so the gap measures the switch rather than the hardware, and the daily maximum it would have set is retracted.
• no (startup grace): The silence straddled the first moments of a session, when what came before could not have been observed.
• capped (74m -> 15m): The device stood convicted of a freeze when it spoke again, and what unfroze it cannot be known. The witnessed silence stays in the row exactly as measured, but the statistics learn at most the device's rhythm plus a modest allowance, shown as the second figure, so one mysterious resurrection cannot widen a freeze window for two weeks. A genuinely slowed device will still teach its new pace within a few detections.

Gaps ended by an intervention are not learned at all, because their endpoint measures the intervention rather than the device.