The Bridge and Broker Sensors

The Bridge and Broker Sensors

Device Sentinel watches every device in your home, and it also watches the layers those devices depend on: the coordinator your radio devices talk through, and the MQTT broker underneath it. These two sensors are the view onto that.

Where a coordinator was found, both arrive switched on; where none was, the broker sensor exists but stays off so it does not read unknown forever. The details are in Whether You Have Them Already below. This page explains what each state means and what the sensors read underneath.

What the Sensors Read

Bridge: Zigbee2MQTT

One sensor for each coordinator Device Sentinel finds. It shows one of four states:

• running: The coordinator is online and no pairing window is open. This is what you see almost all the time.
• binding: A pairing window is open right now. This is what shows while you are adding or re-pairing a device, and the sensor's attributes carry when the window is due to close.
• down: The coordinator is offline, or it has gone quiet and Device Sentinel can no longer read its state.
• unknown: Device Sentinel has not yet heard from the coordinator, which you may see briefly right after a restart.

Its other attributes are the stack it belongs to, the base topic it reads, when it was last heard from, and availability_enabled: whether Zigbee2MQTT's own availability feature is switched on, read from the bridge's information topic. It reads true, false, or unknown before the bridge has spoken. Device Sentinel reports this setting and never changes it, because enabling availability is Zigbee2MQTT's configuration rather than this integration's. The Zigbee2MQTT page explains what turning it on adds.

The bridge is sampled once a minute, which sets the resolution of what it can say. A four-second blip between two samples is not recorded, deliberately, because a blip that short is noise rather than an outage. It also means a duration is accurate to within one sample: an eleven-second outage reads as one minute.

Broker: MQTT

Home Assistant exposes no broker entity of its own, and a bridge cannot see its own transport fail. Without this sensor a broker outage produced no record of any kind. It shows one of three states: running, down, or unknown.

It reads one topic, $SYS/broker/uptime, which Mosquitto publishes on a timer, and watches for two signals. If the uptime value goes backwards the broker restarted, and the value itself says when it came up. Silence past a threshold means the broker cannot be heard. The first signal is the stronger of the two, because it still works when Home Assistant was restarting at the same time and nothing here was running to notice the silence.

There is nothing to configure. The threshold is learned from the broker's own publishing interval rather than set, so a broker publishing on a different schedule is judged correctly without being asked about. Where the observed interval is 10 seconds, the threshold settles at 60.

Its attributes are when the broker started, its uptime, when it was last heard from, the learned publish interval, the learned threshold, and the topic. The useful one is broker_started. If that moves when you did not restart anything, your broker is restarting unnoticed, which nothing else in Home Assistant would tell you.

Where there is no MQTT, or where a broker publishes no statistics, the sensor reads unknown and nothing else changes.

Whether You Have Them Already

On a house with a coordinator Device Sentinel recognized, both arrive switched on and there is nothing to do. The bridge sensor only exists where its stack does, so its presence is already the reason to show it, and the broker sensor follows it.

On a house with no coordinator stack, the broker sensor is created but switched off, because it would read unknown forever. If your MQTT devices make it worth watching, turn it on from the entity's own settings: Settings, then Devices and Services, open Device Sentinel, find Broker: MQTT, and enable it.

If you installed Device Sentinel before this became the default, your sensors keep whatever state you already gave them. Home Assistant applies a default only when an entity is first registered, so nothing you chose is overridden by an update.

Both publish their state on the same one-minute cycle the rest of the integration runs on, and the broker sensor needs two of its messages before it will claim anything. So a fresh sensor can read unknown for up to a minute before showing its real state. That is normal and not a fault.

You Do Not Have to Enable Them

This matters, so it is stated plainly: Device Sentinel reads these states whether or not the sensors are enabled.

A sensor is a window onto a state for you to see; it is not where the reading happens. The work these states support runs from the coordinator's and the broker's own reports in the background. Leaving a sensor turned off costs you the view, not the behavior.

Why the States Matter

Reading these states is the groundwork for detection that would otherwise be impossible. It solves three problems.

Distinguishing a Hand-Fix from a Recovery

When a device goes quiet and then comes back, Device Sentinel cannot see whether a person fixed it or whether it recovered on its own, and the two look identical. But if the coordinator was in a pairing window when the device came back, that recovery was almost certainly a person re-pairing it by hand. That means the silence before it should not be learned as the device's normal rhythm. The episode report marks the gap as no (pairing).

Catching Whole-Mesh Outages

The down state does the same work for whole-mesh events. When a coordinator goes down and comes back, every silence it interrupted is closed as an intervention, a bridge reconnect. Any gap spanning that outage is set aside and marked in the episode report as no (bridge down), because the outage explains the silence: the gap measures the outage rather than the device. The coordinator's down and up moments are recorded as system events with the outage duration, so a mesh-wide incident is one line rather than sixty separate mysteries.

An outage that spans a restart of Home Assistant now closes as well. The last state is kept across the restart, so an outage that began at 03:40 and ended while the house rebooted at 03:42 is recorded with its real length instead of appearing to have begun and never finished.

Establishing the Outer Scope

A bridge reader is blind to its own broker. When the broker stops, nothing delivers the bridge's last message, because the broker is the deliverer, so the bridge sensor goes on reading running through an outage that has silenced everything behind it. That is not a theory: on the reference system, sixteen minutes with the broker stopped took 75 devices offline and the bridge state never moved.

The broker is therefore the outer scope. While it is known to be down, no bridge event is written, because a bridge that cannot be heard is not a bridge that is down. One event is recorded rather than two. A restart of the whole machine is likewise reported once, as a restart, rather than also as a broker outage covering the same minutes.

Zigbee2MQTT's Second Opinion

For a freeze verdict on a Zigbee2MQTT device, the daily brief and the problem list also carry what Zigbee2MQTT says about that particular device.

It never lifts a verdict, and the reason is measured. Zigbee2MQTT allows a mains device 10 minutes of silence before calling it offline, and a battery device 1500 minutes, which is 25 hours. On a fleet that is mostly battery devices, an online reading can be true of something that stopped reporting yesterday. That is why the timeout always travels with the reading rather than the state being shown on its own.

Which Systems Are Covered

Zigbee2MQTT and the MQTT broker are covered now. ZHA, Z-Wave and Matter are detected, and each records what is known about it and what is unverified, but none has a reader or a sensor. Nothing ships for hardware that cannot be tested, so those wait for someone who runs them.

See Also

• How Device Sentinel Learns, for how a device's normal rhythm is learned and why a hand-fix should not pollute it.
• The Reports, for how to read the episode vocabulary these states produce: no (pairing), no (bridge down).
• Maintenance Mode, for telling Device Sentinel that a recovery was your own hand.