Zigbee and Z-Wave on Raspberry Pi: Adding Zigbee2MQTT and Z-Wave JS to Home Assistant

This site's ESPHome and MQTT/Node-RED guides both build smart-home sensors on WiFi — which is cheap and easy to get started with, but it doesn't scale well past a handful of devices. Every WiFi sensor is a full TCP/IP client competing for router airtime and DHCP leases, battery life is mediocre because the WiFi radio is power-hungry, and range from a battery-powered sensor in a back bedroom is often marginal. Zigbee and Z-Wave were purpose-built to solve exactly this: low-power mesh radio protocols where battery sensors sip power for years, every powered device extends the mesh as a repeater, and a single USB coordinator on your Raspberry Pi can manage dozens to hundreds of devices without touching your WiFi network at all. If your Home Assistant setup (see this site's Pi-based Home Assistant install guide) has outgrown WiFi sensors, this is the natural next layer.

Zigbee vs Z-Wave vs WiFi: Where Each Fits

ProtocolPower drawRange per hopMesh repeatingBest for WiFi (ESPHome)Highest — poor coin-cell battery lifeGood, but shares your router's congestionNo native meshPowered sensors, cameras, anything already needing real bandwidth ZigbeeVery low — coin-cell sensors last 1-2+ yearsShorter per hop, but mesh extends reachYes — every mains-powered Zigbee device repeats for battery onesDoor/window sensors, motion sensors, smart bulbs, button remotes Z-WaveVery low, similar to ZigbeeLonger per-hop range than Zigbee, sub-GHzYes, same mesh-repeating modelLocks, garage door controllers, larger-home coverage where Zigbee's 2.4GHz range struggles

None of these are exclusive — a mature Home Assistant setup on a Pi often runs WiFi, Zigbee, and Z-Wave devices simultaneously without conflict, since they use entirely separate radios and Home Assistant treats them as just more entities on the same dashboard.

Choosing a Coordinator/Dongle

Zigbee: the Sonoff Zigbee 3.0 USB Dongle Plus (based on the Texas Instruments CC2652P) is the community-favorite default — well supported, reasonably priced, and works with both of the Zigbee integration paths below. The ConBee II is a solid alternative, particularly if you're already leaning toward deCONZ.
Z-Wave: the Aeotec Z-Stick 7 (or the older Gen5) is the standard USB Z-Wave controller for Home Assistant setups. Check your region's Z-Wave frequency before buying — Z-Wave is region-locked at the radio level (908.42MHz in the US, 868.42MHz in the EU, and other bands elsewhere), and a stick bought for the wrong region will not pair with region-correct devices.

Plug the dongle directly into a rear USB port if your Pi case allows it, or use a short USB extension cable to get the radio antenna a few inches away from the Pi's own case and any nearby WiFi/Bluetooth interference — this alone measurably improves range and pairing reliability, especially with the Pi tucked in a metal enclosure or a crowded network cabinet.

Zigbee Integration Path 1: ZHA (Native, No Extra Broker)

ZHA (Zigbee Home Automation) is built directly into Home Assistant — no separate service, no MQTT broker required. Go to Settings > Devices & Services > Add Integration > ZHA, select your coordinator's USB device path, and Home Assistant takes over the Zigbee network directly. This is the simplest path and the right default choice if you don't have another reason to want Zigbee2MQTT's extra flexibility.

Zigbee Integration Path 2: Zigbee2MQTT (via Mosquitto)

Zigbee2MQTT runs as its own service (commonly installed as a Home Assistant add-on) and publishes every Zigbee device's state to an MQTT broker, which Home Assistant then subscribes to. It's more moving parts than ZHA, but it supports a broader and faster-updating device compatibility list, exposes richer configuration options per device, and — because it's just publishing to MQTT — plays well if you're already running Node-RED or other MQTT-based automation on the same Pi (as in this site's MQTT/Node-RED sensor network guide).

Install the Mosquitto broker add-on from the Home Assistant add-on store if it isn't already running.
Install the Zigbee2MQTT add-on, and point its configuration at your coordinator's USB serial path (find it with ls /dev/serial/by-id/ on the Pi rather than trusting the raw /dev/ttyUSB0 name, which can shift if you plug in other USB serial devices).
Start the add-on and confirm in its log that it detects the coordinator firmware version correctly — a firmware mismatch here is the most common first-run failure and usually means flashing the coordinator with the firmware version Zigbee2MQTT's documentation specifies for your exact dongle.
Enable pairing mode ( "permit join" ) from the Zigbee2MQTT web UI, then put each device into pairing mode per its own instructions — hold-button sequences vary by manufacturer.
Once paired, devices appear automatically as MQTT topics, and the Home Assistant MQTT integration picks them up as entities without manual YAML in most cases.

Z-Wave Setup with Z-Wave JS UI

Install the "Z-Wave JS UI" add-on from the Home Assistant add-on store.
Point it at your Z-Wave stick's USB path (same /dev/serial/by-id/ approach as above).
Open the Z-Wave JS UI web interface, put the controller into inclusion mode, and then trigger inclusion on the device itself (usually a specific button press sequence — check the device's manual, as this varies more between Z-Wave manufacturers than Zigbee ones).
Add the Z-Wave JS integration in Home Assistant proper, pointing it at the add-on's WebSocket address, and paired devices appear as entities.

Troubleshooting Common Pairing Issues

SymptomLikely causeFix Device won't enter pairing modeWrong button sequence, or device already paired to another networkFactory-reset the device per its manual before retrying — most Zigbee/Z-Wave devices need an explicit reset if they were ever paired elsewhere Device pairs but drops offline repeatedlyWeak mesh coverage — too far from coordinator or nearest repeaterAdd a mains-powered Zigbee device (a smart plug is an easy, cheap repeater) partway between the coordinator and the struggling device Coordinator not detected / wrong serial pathUSB device path shifted after a reboot or added USB deviceAlways reference the stable /dev/serial/by-id/ path in add-on configuration, never the raw /dev/ttyUSBx path Zigbee2MQTT reports firmware version mismatch on startupCoordinator shipped with, or was previously flashed with, an incompatible firmware versionRe-flash the coordinator with the exact firmware version specified in Zigbee2MQTT's supported-adapters documentation for your dongle model

A Note on Legality and Interference

Z-Wave's region-locking is a real regulatory boundary, not just a compatibility suggestion — devices and controllers are certified and sold for specific frequency bands, and mixing region-mismatched hardware won't pair reliably even where it's not an outright regulatory violation. Zigbee shares the 2.4GHz band with WiFi and Bluetooth; if you're seeing flaky Zigbee performance in a WiFi-dense environment (apartment buildings are the classic case), check your WiFi channel plan — Zigbee channels 15, 20, and 25 are commonly recommended to sit clear of the most heavily used WiFi channels in North America.

Once a coordinator is running, adding devices is fast — a battery sensor takes under a minute to pair and then reports reliably for a year or more on a single coin cell, which is a different experience entirely from babysitting WiFi sensor battery life. Start with ZHA if you want the simplest possible setup, and move to Zigbee2MQTT specifically if you need a device it supports that ZHA doesn't yet, or you want your Zigbee state flowing through the same MQTT bus as an existing ESP32 sensor network.

Related Guides

Loading_