Zigbee2MQTT

Zigbee2MQTT

Device Sentinel recognizes four coordinator stacks and can only read one of them. This page covers the whole of what it does with Zigbee2MQTT, so a person running it knows exactly what they get, and a person running something else can see what they are missing and why.

Zigbee2MQTT is the stack this project was developed against. It is not better supported because it is a better protocol. It is better supported because it is the one running on the author's own fleet. The other stacks lack these features because they cannot be tested.

How Zigbee2MQTT Is Recognized

Not by the mqtt integration domain, which every MQTT device shares. Device Sentinel looks for the bridge device itself, which Zigbee2MQTT publishes through MQTT discovery.

The stack is recognized by a name ending in "Zigbee2MQTT Bridge", or by a model of "Bridge" under the manufacturer "Zigbee2MQTT". The name is checked first because it carries whatever coordinator hardware sits behind it, which keeps the test independent of any one adapter. If the bridge device is present, Zigbee2MQTT is present. Nothing else counts.

What Is Read

Four retained MQTT topics, read and never written.

• zigbee2mqtt/bridge/state: whether the bridge is online or offline.
• zigbee2mqtt/bridge/info: carries permit_join and the absolute permit_join_end, plus the availability settings described below.
• zigbee2mqtt/bridge/devices: the roll of what actually exists, carrying each device's IEEE address, friendly name, and power source.
• zigbee2mqtt/+/availability: what Zigbee2MQTT itself says about each device, online or offline.

Retained means the current value arrives the moment Device Sentinel subscribes, so a restart in the middle of a pairing window loses nothing.

Nothing is ever published. Device Sentinel does not ask Zigbee2MQTT to do anything.

What the Bridge State Buys

Reading the bridge state makes two kinds of detection possible.

Pairing windows. When a device goes quiet and comes back, a recovery during an open pairing window was almost certainly a person re-pairing it by hand. The silence before it is set aside rather than learned as the device's rhythm. The episode report marks it no (pairing).

Bridge outages. A coordinator going down and coming back is recorded as two system events with the outage duration. Every silence spanning it is set aside as no (bridge down), because the gap measures the outage rather than the device.

Both are covered in more detail on The Bridge and Broker Sensors and on What Is Recorded About Your House.

Reachability, and Why It Is Weaker Than It Sounds

Zigbee2MQTT publishes its own opinion of every device. Device Sentinel reads it and shows it beside a freeze verdict, and it never lifts a verdict. The reason is measured rather than cautious.

The two timeouts are read from your own bridge. Zigbee2MQTT allows a mains device 10 minutes of silence before calling it offline, because it can ping one. It cannot ping a sleeping end device, so it judges those on silence alone and allows 1500 minutes, which is 25 hours. Both numbers come from zigbee2mqtt/bridge/info rather than being assumed, so an install with different settings is described correctly.

What that means on a real fleet: on the reference system, 55 of the 74 devices are battery end devices. For three quarters of them an online reading is true of a device that stopped reporting twenty hours ago, and Device Sentinel's own learned windows are nothing like that long. Letting an online reading clear a verdict would suppress true convictions across most of the fleet.

So the reading always travels with its timeout, and you see what it is worth: "Zigbee2MQTT confirms it is offline", or "reads it as online, and it pings a mains device every 10 minutes", or "reads it as online, though it allows a battery device 25 hours of silence before saying otherwise".

Where availability is switched off in your Zigbee2MQTT settings, nothing appears and nothing else changes. Device Sentinel will not turn it on for you: a monitor should not change the thing it monitors.

How a Device Is Matched

Availability topics are keyed by friendly name, and Home Assistant knows a device by the IEEE address inside its identifier, which reads ('mqtt', 'zigbee2mqtt_0x282c02bfffeafa5b'). The topic zigbee2mqtt/bridge/devices is the only thing carrying both, which makes it the join.

Matching on name alone would already be wrong on the reference fleet, where one switch is named "Switch Master Entryway" in Home Assistant and "Switch Hall Master" in Zigbee2MQTT.

The same roll rejects anything with no device behind it. On the reference fleet there were 81 availability topics against 75 device entries. Three of the extras were groups, one was a device removed long ago, and two were left behind by renames and still read online. A retained topic reading online for a device that no longer exists is precisely the thing that would contradict a correct verdict, so a topic with no entry in the roll answers nothing.

What a Zigbee2MQTT User Gets That Others Do Not

This is the answer to why other stacks are not fully supported. A Zigbee2MQTT user gets:

• Pairing windows recognized, so a hand re-pair does not teach a false rhythm.
• Bridge outages recorded and named, and the silences they caused set aside.
• A second opinion on every freeze verdict.
• A Bridge: Zigbee2MQTT sensor.

Everything else Device Sentinel does works identically on every stack, because it is built on the Home Assistant event bus rather than on any radio.