Understanding MQTT Payloads

Zigbee2MQTT publishes structured JSON for each device. Understanding the message format is crucial for debugging:

mosquitto_sub -h localhost -t 'zigbee2mqtt/+' | jq '.'

Example output:

{
  "linkquality": 127,
  "power": 3.1,
  "current": 0,
  "voltage": 230,
  "energy": 45.23,
  "state": "ON"
}

Common Issues

Issue: Entity Not Found in Home Assistant

Symptoms: Integration discovers device but entity shows “Entité non trouvée”

Solution: Check core.entity_registry in Home Assistant’s storage directory or enable entity discovery in MQTT settings.

Issue: Remote Buttons Not Triggering Actions

Symptoms: STYRBAR remote buttons don’t control lights

Root Cause: Zigbee2MQTT publishes JSON payloads, but MQTT triggers expect plain text. Missing value_template extraction.

Fix: Add value_template: "{{ value_json.action }}" to automation triggers.

trigger:
  - platform: mqtt
    topic: zigbee2mqtt/Remote
    value_template: "{{ value_json.action }}"
    payload: 'on'

Issue: Sensor Stuck at Zero

Symptoms: Current sensor always reads 0A despite power consumption

Diagnosis:

• Verify linkquality is above 100 (good connection)
• Check device reports updates via mosquitto_sub
• Hardware sensor threshold may be too high

Workaround: Accept other measurements (power, voltage, energy) and consider sensor defective.

Debugging Workflow

1. Check MQTT Connectivity: mosquitto_pub -h localhost -t test -m "hello"
2. Monitor Device Messages: mosquitto_sub -h localhost -t 'zigbee2mqtt/+' | grep 'device-name'
3. Verify Home Assistant Receipt: Check logs in Developer Tools → Logs
4. Test Automation: Publish test message: mosquitto_pub -h localhost -t 'zigbee2mqtt/device' -m '{"action":"on"}'
5. Review Entity Registry: Check Home Assistant’s stored configuration for disabled entities

Performance Tuning

Add reporting parameters to configuration.yaml for faster response times:

'0x348d13fffe06ef9c':
  friendly_name: Prise bureau
  reporting:
    power: {min_interval: 5, max_interval: 300, change: 0.5}
    current: {min_interval: 5, max_interval: 300, change: 0.01}