Diagnosing a Zigbee Mesh Without a Debugger
Zigbee2MQTT is powerful and its diagnostics are dense. Most people don't need more data about their mesh — they need someone to just tell them what's actually wrong.
Zigbee2MQTT is excellent software, and its logs and network map are built for people who already understand mesh networking — routing tables, LQI values, channel congestion, orphaned child devices. When a Zigbee mesh starts degrading — a light that's suddenly slow to respond, a sensor that drops offline randomly — that raw diagnostic data is all technically available and almost entirely useless to the person actually trying to fix it.
Zigbee2MQTT Doctor exists to close that specific gap: paste in your network's state export, and instead of a table of signal strengths and device roles, get a plain-English read on what's actually degrading the mesh — a weak route through a specific device, a channel with too much Wi-Fi overlap, a device that's lost its parent and never found a new one.
Diagnosis is a different skill than data collection
The hard part of this tool wasn't parsing Zigbee2MQTT's export format — that's a solved, documented problem. It was building the judgment layer on top: knowing that a device three hops out with marginal signal quality is a normal, healthy mesh, while the same signal quality on a device that should be one hop away from a router is the actual problem. That distinction requires understanding what "healthy" looks like for a given topology, not just reading the numbers off the page.
That's the same instinct that shows up in every diagnostic tool worth building: raw data isn't insight. The value is in the judgment that turns data into "here's the one thing to fix," and that judgment is usually the part that took the most iteration to get right, even though it's invisible in the final product.
Why I keep building tools like this
There's a pattern across a lot of what I ship: take something technically legible only to an expert, and make the diagnosis legible to anyone who has the problem. It's the same thing KerfOS does for cut lists and Kith does for a smart home's status. The tools change. The instinct — find where expertise is gatekeeping a fix that should be simple — doesn't.