Raspberry Pi as a Zigbee gateway: Zigbee2MQTT, Mosquitto and Home Assistant

Zigbee sensors, switches and lights from different brands normally need each vendor's hub and app. A Raspberry Pi with a USB Zigbee adapter replaces them all.

Architecture

Zigbee devices ))) USB Zigbee adapter ── Zigbee2MQTT ── MQTT broker (Mosquitto) ── Home Assistant / Node-RED / your code
                       (coordinator)          on the Raspberry Pi

• Zigbee adapter (coordinator): forms the Zigbee network. Zigbee2MQTT's docs single out adapters based on zStack and EmberZNet firmware as reliable; check its adapter list before buying.
• Zigbee2MQTT: translates Zigbee messages to MQTT topics and back.
• MQTT broker: Mosquitto is the recommended broker.
• Home Assistant (optional): picks devices up automatically via MQTT discovery.

Hardware notes

• Use a USB extension cable for the adapter. Zigbee2MQTT's guide calls this the first thing to do for timeouts, pairing failures or devices dropping off. It moves the adapter away from the Pi and other USB devices, which avoids interference and improves range.
• Power: an SSD, adapter and radio on one Pi 5 need the full 27 W supply (see the power item).
• For Home Assistant OS, Home Assistant recommends a Raspberry Pi 5 or 4 with at least 2 GB RAM, and warns against phone chargers and computer USB ports as power sources.
• Storage: Home Assistant's database writes a lot; prefer SSD/NVMe, or at least a ≥ 32 GB A2 card (see the SD card item).

Home Assistant integration

1. Enable the MQTT integration in Home Assistant, pointing at the broker.

2. In Zigbee2MQTT's configuration.yaml set:

   homeassistant:
     enabled: true
   

3. Devices paired in Zigbee2MQTT then appear in Home Assistant through MQTT discovery, including renames made in Home Assistant.

Operating tips

• Back up the Zigbee2MQTT data directory (configuration, network key and device database). Without it, a new installation means re-pairing every device.
• Pair devices near their final location. The mesh routes through mains-powered devices, so add routers (plugs, bulbs) before battery sensors far away.
• Secure the broker: create users and passwords in Mosquitto, and don't expose port 1883 to the internet.
• Run Zigbee2MQTT and Mosquitto as services (containers or systemd) so they restart after power loss.