The Device Page - TheThinkingHome/device_sentinel GitHub Wiki

The Device Page

This page describes the central hub for the integration: the Device Sentinel "device" page in Home Assistant. You can find it by navigating to Settings > Devices and Services > Device Sentinel.

Home Assistant does not provide helper text for entities on this page, so an entity's name and its state are the whole explanation. This guide breaks down what each control and sensor tells you, and how to use them to curate your network.

1. Active Controls & Maintenance

These buttons are how you actively manage the integration, enable diagnostics, and pause learning when you need to work on your hardware.

Maintenance Mode (Key Workflow)

Because the integration cannot see your hands, a manual fix (like a battery swap, a power cycle, or a device re-pair) looks identical to a device recovering on its own from a long silence. If the system learns that long silence, it will widen the freeze window for that device, making future detections much slower. Maintenance Mode covers the whole workflow.

Maintenance Mode tells the system you are actively working on the hardware.

How to use it:

  1. Press Maintenance Mode before you touch the hardware.
  2. Perform your repair (swap the battery, press the wake button, re-bind it, etc.).
  3. Press the button again to end the window early, or simply let it expire automatically (defaults to 10 minutes).

Note: Any device that recovers while this window is open is treated as your fix, and its silence gap is safely discarded rather than learned.

The Three Enable Buttons

Most integrations ship their diagnostic entities disabled by default. Device Sentinel cannot learn from what is switched off. These three buttons sweep your registry and turn on the entities Device Sentinel needs:

  • Enable Last Seen: Turns on last-contact entities. This is the most reliable clock a device can offer and drastically speeds up freeze detection.
  • Enable Battery: Turns on battery-percentage sensors (which feed the battery discharge history).
  • Enable Signals: Turns on link-quality (LQI) or signal strength (RSSI) entities so Device Sentinel can establish a signal baseline.

Note: These buttons only target watched devices. Devices you have explicitly set aside or excluded are ignored.

Regenerate Reports

Instantly forces Device Sentinel to judge every device right now and rewrite all diagnostic files (.md files) and web reports (.html files). Use this if you just fixed a frozen device and want your daily_brief.html or battery_report.html to reflect the fix immediately rather than waiting for the next system tick.

2. Verdicts at a Glance (Sensors)

These sensors provide a live, at-a-glance summary of everything currently wrong in your home. Note: Most finding counts ship switched off by default. Enable the ones you want to view on this page or on a dashboard.

  • Problem List (Todo Entity): The central hub for actionable alerts. Contains frozen/unavailable devices, low/falling batteries, and stuck signals. Checking a row acknowledges it, silencing notifications while keeping the item on the list until the device actually recovers.
  • Status: Reads Watching, Learning, or Problem. It will read "Learning" until your very first device establishes a rhythm. "Problem" means Device Sentinel's own storage is unhealthy.
  • Device: Frozen: How many devices are currently frozen, unavailable, or unknown. The attributes contain the full list of downed devices.
  • Battery: Low: How many batteries have crossed your flat low-battery threshold (15% by default).
  • Battery: Falling: How many batteries are projected to hit 0% within your warning horizon (e.g., 30 days), based on their actual rate of decay. This catches dying lithium cells that still read a high percentage.
  • Signal: Rails: How many devices are reporting a false, stuck signal (e.g., pinned at 255 LQI or -128 RSSI for 3+ days).
  • Signal: Weak: How many devices are currently reporting a signal significantly worse than their own historical normal. This is live: devices appear here while struggling and drop off the moment they recover.

3. Upstream Health (Coordinators & Network)

When a coordinator or broker stops, every device behind it goes quiet at once. These sensors tell you when the plumbing has failed, rather than blaming the individual devices. The Bridge and Broker Sensors covers each one in full.

  • Bridge: Zigbee2MQTT / Bridge: ZHA: Reads running, down, or unknown.
    • down: The coordinator has stopped. Freeze verdicts for its devices are paused, and you will receive one notification naming the coordinator rather than dozens of alerts for the devices behind it.
    • binding (Z2M only): A pairing window is open. Any device that returns during this state is treated as a manual re-pair, and its silence is discarded rather than learned.
  • Bridge: WiFi: Reads running or down. Exists only if WiFi outage watching is configured.
  • Broker: MQTT: Reads running, down, or unknown. Because a bridge cannot report that its own transport has failed, the broker is monitored separately. A broker outage outranks a bridge outage.

4. Under the Hood (Diagnostics)

These sensors expose Device Sentinel's internal bookkeeping. They are disabled by default as they answer questions you usually only ask when troubleshooting.

The Tracking Funnel

  • Devices: Watched: The total number of devices currently being observed and learned.
  • Devices: Learned: How many devices have successfully established a reporting rhythm (enough days to be judged for a freeze). This will always be lower than Watched, as button-remotes with no heartbeat never establish a rhythm.
  • Device: Tracked: How many devices are eligible for freeze detection (Learned), minus any devices you have explicitly freeze-muted.
  • Battery: Tracked: How many devices are eligible for battery judgment, minus any devices you have explicitly battery-muted.
  • Signal: Tracked: How many devices are eligible for signal judgment, minus any devices you have explicitly signal-muted.
  • Devices: Set Aside: Devices that Device Sentinel is deliberately ignoring (e.g., cloud services, disabled entities, or integrations you added to the Exclude list).

Data Depth

These sensors (Data: Freeze, Data: Battery, Data: Signal) tell you how much history stands behind each area of judgment. They will count up the days until they reach their required learning windows (e.g., 7 days to arm, 14 days to fully learn a rhythm), after which they will read Armed, Tracking, or Learned.

The diagnostics download from this page also records how long each coordinator, the MQTT broker and each integration took to load after the last restart, which answers the question of whether something was slow to start or genuinely down.