Z-Wave & Zigbee Mesh Health

Radio-mesh diagnosis is a different axis from code debugging. The data comes from three undocumented JSON endpoints (skills/_reference/endpoints.md); skills/_scripts/hub_mesh.py fetches and flags, the mesh-health skill interprets. Hubitat publishes no numeric "bad" thresholds — flag unambiguous signals and rank the rest; never assert an invented cutoff.

A clean radio is not a working device. Every metric here describes the radio path. Commands reach a device over a separate command path (app → hub mesh → owning hub → radio), and a broken command path leaves every radio metric green. Radio evidence can never conclude "the mesh is healthy, so the devices are fine" — see The command path.

Z-Wave node metrics (grounded meanings)

• nodeState FAILED — the node is unreachable. Split it by deviceId (hub_mesh.py tags failure_kind): FAILED with a bound deviceId is a real device currently unreachable — may be transient (recover it, do NOT delete); FAILED with no deviceId is an orphan ghost (a pairing that never bound a device) — safe to remove. Never force-remove a real device thinking it is a ghost.
• lastTime — when the hub last heard the node; absent on a node never heard at all (zwave.never_heard[]). Such a node is reported nodeState:OK and passes every radio check, so no FAILED-keyed check sees it. A never-heard node with no deviceId is a ghost by the split above; with a deviceId it is a real device that has never spoken — judge it, don't assume either way.
• per — cumulative packet-error count ("accumulation of packet errors for a node"), not a percentage. Lower is better; 0 is ideal. Nonzero means errors are occurring; judge severity relative to the node's msgCount and to peers.
• On the zwaveJS backend (2.5.1.140), per is not reliably corroborated by the wire. Do not rank a node on it alone. Confirm a suspected packet-error offender against the transmit log (hub_radiolog) before calling it one; read packet_errors[] in summary.warnings as a lead, not a verdict.
• averageRtt — round-trip time in ms; lower is better. No spec cutoff — rank, don't threshold.
• listening — the always-on indicator. true identifies a mains-powered classic-mesh node that can repeat. false identifies a sleepy node.
• Use listening instead of guessing repeater capability from device type.
• beaming means the node requires beam wake-up. It does not mean the node sends beams or repeats.
• The JSON beaming field was false even for sampled FLiRS locks on 2.5.1.132.
• Use the Z-Wave Details UI Beaming column when that requirement matters.
• Never use the JSON beaming key as repeater proof.
• routeChanges — classic-mesh stability indicator; frequent changes mean the Last Working Route keeps failing. Reported by the legacy backend; N/A on the zwaveJS backend.
• neighbors — how many nodes a classic-mesh node hears. 0 for Long Range nodes (a star has none — see below), not a backend artifact.
• A Z-Wave device's deviceNetworkId is hex; nodeId and every node-facing surface are decimal (skills/_reference/endpoints.md).
• Never pass a deviceNetworkId to anything taking a node id.
• Never read an empty capture as proof a device is silent. Re-check the id form first.
• Convert with hub_radiolog.py --dni, or filter by --device-id instead.
• Zigbee is unaffected. zigbeeId is hex on both sides.
• route — hexadecimal node ids with hub (01) first, the destination itself last, and repeaters only between them. 01 -> 57 reaches node 0x57 directly. 01 -> 1B -> 57 uses repeater 0x1B. hub_mesh.py reads intermediate hops into zwave.route_fan_in and a per-node hops count (0 direct, N repeaters, null no readable route).
• lwrRssi is the last hop INTO the hub, as Zigbee's lastHopRssi is. On a routed node it is the final repeater→hub link, not the end device's own radio.
• Never rank RSSI across hops. hub_mesh.py splits ranked.by_rssi_direct / by_rssi_routed / by_rssi_route_unknown. Compare within one list.
• A reading from one list is not comparable to a reading from another, in either direction.
• weak_signal_heuristic[] entries carry hops too. A flag on a routed node names the repeater's link into the hub, not the device's own.

Route fan-in (a repeater's blast radius)

• Fan-in is how many nodes route THROUGH a repeater — the classic-mesh counterpart of a hub-mesh peer's shared_device_count, and read the same way: blast radius, not a fault. zwave.route_fan_in.repeaters[] ranks every repeater by dependent_count; each node also carries its own dependent_count.
• A repeater carrying 12 nodes is a normal mesh. Fan-in alone is never a finding, reaches neither summary counter, and needs no remedy. Hubitat publishes no "too many dependents" cutoff — rank, never threshold.
• What fan-in changes is the reading of a repeater that is itself flagged. zwave.route_fan_in.load_bearing_concerns[] is that cross: a repeater that is never_heard, FAILED, weak, or carrying packet errors, ranked by how many nodes sit behind it. A never-heard leaf is one silent device; a never-heard repeater carrying 12 is 12 nodes whose path runs through something the hub has no evidence is alive. Both sit in never_heard[] and only dependent_count tells them apart.
• The concern is already counted; the fan-in is not a second finding. A never-heard repeater warns once, via never_heard. Quote its dependent_count as the scope of that one warning — never add it up as extra faults.
• Fresh dependents behind a flagged repeater are evidence the repeater relays. A repeater cannot be dropping everything while a node behind it reported a minute ago. Read the dependents' freshness before blaming the hop.
• Classic mesh only. LR is a star with no repeaters, so LR nodes are excluded and carry dependent_count: null — the question does not apply, which is not the same as zero. route_fan_in.anomalies[] holds routes that do not run hub → node (stale or malformed records) and unknown_node marks a hop absent from nodes[]; both are data gaps, not mesh faults.

The command path (hub mesh)

• Actuator vs reporter is the diagnostic split, not Z-Wave vs Zigbee. A reporter (lock, motion, presence) transmits on its own, so a fresh lastTime proves the radio works. An actuator (shade, outlet, lamp) transmits only after being commanded, so its lastTime is when a command last landed — silence is unknown, not broken.
• Reporters fresh + actuators frozen = the command path is broken, not the radio. When it spans both radios at once, no radio fault can explain it — two radios do not fail in the same second. Read zwave.stalest / zigbee.stalest this way. hub_mesh.py ranks staleness and never flags it — the classification is yours.
• Actuator timestamps clustered in one narrow window mark the last window in which commands landed; a scheduled automation is the usual source.
• hub_mesh.problems[] is critical: a peer that cannot carry commands is as dead as a failed radio. peer_unreachable / peer_identity_mismatch come from probing the recorded address; peer_offline / peer_inactive / peer_warning are the hub's own claims.
• The hub's peer fields do not detect a stale record — a peer holding a dead address reports active:true, offline:false, warning:null with lastActive ticking. Never read those three as an all-clear; only the probe is evidence. The peer table is asymmetric — each hub keeps its own record, and one side can be right while the other is stale.
• Re-adding a peer is hub-UI work, and shared_device_count is its blast radius: every shared device is a link an app can bind to, and removing the peer unbinds them. Quote the count before advising a re-add, and prefer editing the address over remove-and-re-add. A hub whose address drifts re-breaks the record — a DHCP reservation on the hub's current IP is the durable fix.

The backend split (RSSI scale + timestamp traps)

• lastTime is stamped differently per backend: legacy emits an explicit +0000 (true UTC); zwaveJS emits a naive stamp in the hub's local zone (timeZone in /hub/details/json). Reading naive as UTC ages every zwaveJS node by the hub's UTC offset. Zigbee's lastActivity carries +0000 on both.
• lwrRssi is reported on two different scales depending on the Z-Wave backend. Read zwaveJS first.
• zwaveJS:true — absolute dBm (negative, e.g. -78db); closer to 0 is stronger. Silicon Labs receiver sensitivity: −97 dBm (700-series, 100 kbps GFSK) and −110 dBm (800-series LR channel, 100 kbps O-QPSK); the classic GFSK floor on 800 is a few dB higher. A route near the floor is genuinely weak.
• zwaveJS:false (legacy) — dB above the noise floor (positive, e.g. 27dB); ≤ 0 is at/below noise.
• Higher is better on both scales, so worst-first ranking is the same; a fixed numeric cutoff is wrong across backends. routeChanges is also N/A under zwaveJS — a backend limit, independent of topology.

Classic mesh vs Long Range (LR)

• A C-8 Pro runs both at once. Node id ≥ 256 = a Z-Wave LR node; id ≤ 232 = classic mesh. Classify by id before advising — hub_mesh.py tags each node's topology.
• LR is a star: every LR node talks directly to the hub — no routing, no hops, no repeaters (Z-Wave Alliance / Silicon Labs). neighbors:0 and a direct route (01 -> <node>) are inherent to LR, not faults. LR uses per-transmission dynamic power control over a long link budget, so a distant LR node sitting at −85…−93 dBm can be normal.
• Never suggest a repeater or a Z-Wave repair for an LR node — neither exists in a star. An unreliable LR device at distance (weak signal and/or high RTT, intermittently FAILED) is a genuine tradeoff, not one fix. Improving the direct link (hub antenna/placement, LR channel/interference) keeps LR's simplicity and its reliability-when-the-link-holds. Re-including as classic mesh gains repeater routing for a marginal link but takes on mesh's routing flakiness (route changes, LWR failures, slow hops). The choice is situational and contested — many networks find LR more reliable than mesh, so do not default to mesh — surface the tradeoff and let the owner decide.
• Classic mesh (id ≤ 232) is the only place neighbors, multi-hop route, routeChanges, repeaters, and Z-Wave repair apply.
• A sleepy battery node has no on-demand route rebuild. Its Z-Wave Details row offers only Refresh · State — no per-node "Rebuild route". Only a global network rebuild reaches it (GET /hub/zwaveRepair2, skills/_reference/endpoints.md), and its route rebuilds on its next wake, sitting in the rebuild's Pending list and completing async. For a marginal battery node the durable fix is RF/topology — a repeater near it — not a repair click.
• A newly added repeater with high hears but near-zero heard by (/hub/zwaveTopology) is a hypothesis to verify, not a verdict. It may be an unpropagated neighbour table rather than a placement fault. Read heard by and corroborate before concluding a fresh repeater is badly placed. Unverified (n=1, one build, reboot confounded with a version change): a zwaveRepair2 rebuild may not refresh neighbour tables where a hub reboot did. Treat "reboot after adding repeaters" as a lead to test, not standing guidance.

Zigbee: liveness, and where signal actually lives

• The zigbeeDetails snapshot exposes no per-device LQI or RSSI — from it, judge liveness, not signal.
• Per-device LQI lives in a different surface: GET /hub/zigbee/getChildAndRouteInfo (the neighbor/route table, text — LQI:<n> per router). Per-frame LQI+RSSI come from the live zigbeeLogsocket. Don't rank Zigbee signal off the snapshot; use one of those.
• Per-device active is not liveness. Long-dead devices can remain active:true.
• Do not treat either active value as a freshness verdict.
• Read lastActivity and rank its age.
• A missing or unparseable lastActivity timestamp is unknown, not fresh.
• A generic name:"Device" of type:"Device" is a join that never initialized — the Zigbee ghost.
• Network-level problems: networkState ≠ ONLINE, healthy:false, or weakChannel:true (interference on the current channel). Zigbee uses 2.4 GHz channels 11–26; weakChannel overlaps busy Wi-Fi.

Live radio traffic (the log sockets)

• ws://<ip>/zwaveLogsocket and ws://<ip>/zigbeeLogsocket stream per-frame decoded traffic — distinct from the driver /logsocket. Tail via skills/_scripts/hub_radiolog.py; the snapshot says who is weak, the log shows it happening.
• Read them for live signal (Zigbee lastHopLqi/lastHopRssi, Z-Wave per-frame RSSI: -NN dBm), sequence gaps (a soft missed-frame hint, not a hard drop count — the counter is shared across the device's traffic), and which cluster/command a device uses.
• lastHopLqi/lastHopRssi are the last hop into the hub — for a routed device that is the repeater→hub link, not the end device's own radio. ZCL cluster names for the common clusters; 0xFC00–0xFFFE is manufacturer-specific, 0xE000–0xEFFF is reserved space vendors (Tuya) use off-spec.
• The Z-Wave TransmitReport (hub_radiolog --summary → transmit_report) gives the noise floor and SNR at both ends. An elevated or spiky hub noise floor with hub_snr well below dest_snr means the hub's own receiver is the bottleneck, from its RF environment rather than the device or distance. Common culprits are co-located 900 MHz radios, USB3, and gear clusters. The fix gets the hub's receiver out of that noise by relocating the hub, fitting an external antenna, or separating co-located hubs. Never the device.
• transmit_report may be absent (observed 2.5.1.140: the transmit lines carried ACK RSSI only, no noise floor). Confirm transmit_report is present before relying on it for the hub-receiver split. The present transmit fields (transmit status, routing attempts, route speed, took) still separate a real drop from a slow S2/FLiRS exchange.
• The hub's own noise floor is measurable without transmit_report. A zwaveJS hub polls GetBackgroundRSSI unprompted (~30 s) and the raw serial response is already in zwaveLogsocket. hub_radiolog --summary decodes it into background_rssi: per-channel min/mean/max dBm, plus polls and samples. Read it against the receiver sensitivity above. A floor near sensitivity means the hub is noise-limited. No device-side work moves it.
• The floor samples only on an idle radio. The controller polls when its queues go idle and answers only some polls. samples well below polls means the radio was busy, never that the hub lacks the measurement.
• A rebuild returns zero samples. Noise measurement and zwaveRepair2 are mutually exclusive. Re-measure once neighbour-update traffic stops.
• Read ch1 and ch2 as one channel, not two.

Device lifecycle & removal

• LR devices join via SmartStart, not classic inclusion — the DSK/QR is added to the hub's provisioning list and the device auto-includes on power-up (no add-mode, no button). LR inclusion is S2-mandatory; the new node gets an id ≥ 256.
• Graceful removal is two steps and one is physical: remove the device from the SmartStart provisioning list (else it re-includes), and exclude/factory-reset the physical device. An agent cannot do the physical step — so removal is guide-the-user, not automate.
• The tooling confirms a removal, it does not trigger one. Including or excluding a real device is hub-UI + physical — no endpoint triggers it. Confirm a removal two ways: the snapshot node-count/id diff, and the radio-log signature (skills/_reference/zwave-lifecycle.md).
• Force-remove (RemoveFailedNode) applies only to a FAILED orphan ghost, never a recoverable real device — groundable via POST /hub/zwave/nodeRemove. A full Z-Wave network rebuild is groundable too, via GET /hub/zwaveRepair2 — both in skills/_reference/endpoints.md.
• /hub/zwaveRepair2 is a trigger, never a status check. Called on an idle hub it starts a rebuild, and its {"success":false,"message":"Inclusion or rebuild is already running"} is a side effect of one already running. Poll GET /hub/zwaveRepair2Status or GET /hub/checkZwaveRepairRunning instead (skills/_reference/endpoints.md).

Grounding sources

• Field meanings: Hubitat docs (Z-Wave Details, Zigbee Details, Troubleshoot Z-Wave/Zigbee) and staff mesh-details explanations.
• LR star topology, no repeaters, node-id ≥ 256, dynamic power, S2-only: Z-Wave Alliance and Silicon Labs LR overview.
• Protocol constants: Silicon Labs Z-Wave 700/800 receiver sensitivity (per modulation); IEEE 802.15.4 §8.1.2.2 (channels 11–26), LQI 0–255.
• Backend-vs-topology split and node/device shapes: verified live on 2.5.1.128 across a zwaveJS ("Apps") and a legacy ("Devices") hub (skills/_reference/endpoints.md).