---
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