Zigbee2MQTT

Overview

Zigbee2MQTT allows you to use your Zigbee devices without the need for proprietary bridges or gateways. It bridges events from the Zigbee network to the Mosquitto MQTT broker, which are then discovered by Home Assistant.

This module exists in modules/nixos/services/zigbee2mqtt.nix, but it is currently disabled in hosts/nixos/configuration.nix.

Hardware

Current Setup (V3)

• Coordinator: SONOFF Zigbee 3.0 USB Dongle Plus.
• Connection: Local USB Port.
• Path: /dev/serial/by-id/usb-...
• Reason for Migration: Improved stability and lower latency. By using USB, we eliminate dependencies on internal network routing and static IPs (iotDongleIp).

Legacy Setup (V2)

• Coordinator: SONOFF Zigbee/Thread PoE Dongle MAX (Dongle-M).
• Connection: Ethernet/PoE (Remote TCP Bridge).
• Port: tcp://192.168.1.101:6638.

Legacy Setup (V1)

• Coordinator: Texas Instruments CC2531 USB Stick.

Ports

Port	Protocol	Description
8080	HTTP	Web Interface (Frontend)
6638	TCP	Remote Zigbee-over-TCP (Default for Dongle-M)

External Access

The Web UI is accessible externally via the Cloudflare Tunnel:

• URL: https://zigbee2mqtt-home.javiersc.com
• Internal: http://localhost:8080

Secrets

MQTT credentials are required to connect to Mosquitto.

Secret Path	Key	Environment Variable
op://Homelab/Mosquito/username	username	ZIGBEE2MQTT_CONFIG_MQTT_USER
op://Homelab/Mosquito/password	password	ZIGBEE2MQTT_CONFIG_MQTT_PASSWORD

Backup

• Paths: /var/lib/zigbee2mqtt (Device database and state).
• Exclusions: *.log, configuration_backup_*.yaml, log/.

[!IMPORTANT] Coordinator Migration: When moving from a CC2531 (Z-Stack) to a Dongle-M (EZSP/Ember), you MUST wipe the /var/lib/zigbee2mqtt directory. The backup files from the old coordinator are incompatible and will prevent the service from starting.

Troubleshooting

Connectivity

If Zigbee2MQTT cannot reach the coordinator, ensure the Dongle is powered via PoE and its IP is fixed to 192.168.1.101 with port 6638 enabled in its web interface.

Checking Logs

journalctl -u zigbee2mqtt -f

Reverting to Ethernet/PoE

If you decide to go back to a network-based coordinator (like the Dongle-M):

1. Add the coordinator IP as an explicit option or value in the Zigbee2MQTT service module.
2. Update modules/nixos/services/zigbee2mqtt.nix to use tcp://<ip>:6638 as the zigbeePort.
3. Ensure the device has a static IP lease in your router.

Pairing Devices

1. Access the Web UI.
2. Click “Permit join (All)”.
3. Put your device in pairing mode (e.g., hold the reset button for 5 seconds).
4. The device should appear in the list.