MaddoScientisto
6cc281d372
- 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`.
41 lines
2 KiB
Markdown
41 lines
2 KiB
Markdown
---
|
|
name: mqtt-z2m-diagnostics
|
|
description: 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
|
|
|
|
```powershell
|
|
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
|