Thread Diagnostics continuously records the state of your Thread network and Matter devices, so that “why did my device drop at 3 AM” finally has an answer. It grew out of the Matter devices are unavailable discussion, where the missing piece was always the same: by the time you notice a device is gone, the interesting data is gone too.
Test version: Thread Diagnostics | Homey
Source code: GitHub - stefan-schweiger/dev.schweiger.thread-diagnostics: Homey app that continuously logs Thread mesh and Matter device diagnostics · GitHub
Issues: Issues · stefan-schweiger/dev.schweiger.thread-diagnostics · GitHub
What it logs
- Every 10s: Homey’s Thread role, leader data, partition ID, router/neighbor/child tables incl. RSSI, and radio counters
- Every 10s: OpenThread history events (role/partition changes, neighbors added/removed). These come from the OT stack’s internal event tracker, so nothing is missed between polls
- Every 60s: the Thread network topology (the same data as the developer tools)
- Every 15min: the Matter node inventory plus per-node Thread diagnostics (the device’s own view of its neighbors and signal strength)
- Realtime: Matter devices becoming unavailable/available, with the reason and the device’s mesh identity (RLOC16 / extended address)
Everything is written as structured JSONL to daily log files that you can view, copy or open from the app’s settings page, plus a set of Insights graphs for long-term trends (router count, unavailable devices, average neighbor RSSI, and more). Log lines include device names, so you don’t have to cross-reference addresses by hand. All intervals are configurable.
The API key
Out of the box the app logs topology, Matter nodes and availability changes. For the deep diagnostics (router/neighbor tables, counters, history events)
it needs to call Homey.thread.executeCommand, and Homey does not allow apps to do that with their own permissions: the homey:manager:api token only
carries the homey.system.readonly scope, while that endpoint requires homey.system. The workaround is to create an API key with full access under
my.homey.app → Settings → API Keys and paste it into the app’s settings. The key never leaves your Homey. If Athom ever opens up a read-only diagnostics
scope for apps, the key requirement can go away.
Good to know
- This is a debugging tool, not something to run forever. It writes a few MB of logs per day (capped at 25 MB by default, oldest files are pruned first) and polls constantly. Capture your problem, export the logs, then pause or uninstall it.
- The frequent polls are radio-silent local reads; only the topology call (every 60s) and the per-node Matter reads (every 15min) generate a small amount of mesh traffic.
- Log files are one JSON object per line, so they are easy to analyze with jq. The README has example queries.
- Requires a Homey Pro (Early 2023) or newer, since it needs the built-in Thread border router.
If you’re one of the people affected by unstable Thread/Matter devices, I’d love to hear whether the logs help pin down what’s happening in your setup. Feedback, ideas and PRs welcome.
If you like what I have created you can buy me a beer through Paypal.
