maddo/HomeNetwork
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
HomeNetwork/.github/skills/mqtt-z2m-diagnostics/SKILL.md
MaddoScientisto 6cc281d372 Add MQTT/Zigbee diagnostics tool and documentation updates 
- Introduced `scripts/mqtt_z2m_diag.py` for reusable MQTT and Zigbee2MQTT diagnostics.
- Added `copilot-instructions.md` section for MQTT/Zigbee diagnostics tool usage.
- Created `docs/mqtt-broker-broad-analysis.md` for comprehensive MQTT broker analysis.
- Documented Salotto Overview Switch investigation in `docs/salotto-overview-switch-investigation.md`.
2026-04-17 18:25:37 +02:00

2 KiB
Raw Blame History

name description
mqtt-z2m-diagnostics Use the repository MQTT/Zigbee2MQTT diagnostics script for broker-level Home Assistant and Zigbee2MQTT investigations.

MQTT and Zigbee2MQTT diagnostics

Use scripts\mqtt_z2m_diag.py for broker-level diagnostics in this repository instead of ad hoc one-off MQTT scripts.

When to use this skill

  • Zigbee2MQTT devices are stale, unavailable, or not responding to Home Assistant
  • Home Assistant entity state does not match broker state
  • You need device records, retained state, get responses, device/configure probes, permit-join, or pair watches
  • You want to compare a broken Zigbee device with a known-good one

Requirements

  1. Check .local\mqtt-home.env first.
  2. If it is missing, incomplete, or stale, ask the user for the current broker details before going deeper.
  3. Treat .local\mqtt-home.env as local machine state, not repository configuration.

Primary commands

python scripts\mqtt_z2m_diag.py health
python scripts\mqtt_z2m_diag.py device-record nitori_salotto_1
python scripts\mqtt_z2m_diag.py state nitori_salotto_1
python scripts\mqtt_z2m_diag.py get nitori_salotto_1 --keys state_left state_center state_right
python scripts\mqtt_z2m_diag.py configure nitori_salotto_1
python scripts\mqtt_z2m_diag.py compare nitori_salotto_1 Switch_Cucina_Neo --configure
python scripts\mqtt_z2m_diag.py permit-join --time 90 --watch
python scripts\mqtt_z2m_diag.py pair-watch nitori_salotto_1 --time 90 --duration 95

Guidance

  • Prefer read-only commands first: health, device-record, state, get, compare, watch
  • Use configure, permit-join, pair-watch, or publish only when the investigation clearly needs them
  • When comparing devices, use the same command flow on a known-good device to prove whether the fault is in the broker path or the device itself
  • If the script reveals a new recurring diagnostic need, extend scripts\mqtt_z2m_diag.py and keep this skill aligned with it