Smart plugs that depend on a vendor cloud are useless the moment your ISP path dies. A local Zigbee mesh plus Zigbee2MQTT keeps door sensors, buttons, and relays talking to Home Assistant over MQTT on your LAN—even when the internet (or a flaky Wi‑Fi AP) is having a bad day.

This DIY walkthrough follows official Zigbee2MQTT, Mosquitto, and Home Assistant docs. You will pick a supported USB coordinator, install Mosquitto, install the Zigbee2MQTT Home Assistant app, complete onboarding, and harden the radio against 2.4 GHz interference—especially relevant in dense South African suburbs where every neighbour’s router sits on the same band.

Why Zigbee2MQTT (and why USB)

Zigbee2MQTT sits between a Zigbee adapter and an MQTT broker. Devices join the Zigbee network; state and commands flow as MQTT messages that Home Assistant can discover automatically. Project getting-started guide: https://www.zigbee2mqtt.io/guide/getting-started/

• Local by design — no vendor cloud required for day-to-day control once devices are paired.
• Huge device library — pair by following each device’s page in the supported-devices list (linked from the getting-started guide).
• Home Assistant discovery — enable MQTT discovery so entities appear without hand-written YAML. Docs: https://www.zigbee2mqtt.io/guide/usage/integrations/home_assistant.html

Official adapter notes recommend zStack and EmberZNet families. Avoid aging CC2530/CC2531 sticks for anything beyond a tiny lab mesh—the project calls them out as poor performers. Supported adapters overview: https://www.zigbee2mqtt.io/guide/adapters/

Prefer a modern USB stick based on CC2652/CC1352 (zstack) or a current EmberZNet dongle. Ethernet/PoE coordinators are excellent when you can place the radio centrally; this guide focuses on the common USB path. The adapters page also warns that Wi‑Fi-linked “network” serial bridges can be less stable than USB or wired Ethernet because the serial protocol does not tolerate packet loss well.

What you need

• Home Assistant OS (or Supervised) with the Add-on Store, or any host where you can run Mosquitto + Zigbee2MQTT.
• A supported USB Zigbee coordinator (preflashed for coordinator firmware—check your adapter’s page before buying).
• A USB extension cable (~50 cm or longer, preferably shielded)—not optional if you care about range.
• A few Zigbee end devices to pair (sensor, button, or mains-powered bulb/plug that can also act as a router).

Important: do not run Zigbee Home Automation (ZHA) and Zigbee2MQTT on the same USB coordinator at the same time. If ZHA already claimed the stick, disable/remove that integration first or Zigbee2MQTT will fail to open the serial port. Troubleshooting notes: https://www.zigbee2mqtt.io/guide/installation/20_zigbee2mqtt-fails-to-start_crashes-runtime.html

Step 1: Install Mosquitto (MQTT broker)

Zigbee2MQTT requires an MQTT broker. On Home Assistant, the straightforward choice is the official Mosquitto broker app. Home Assistant’s MQTT integration docs recommend it and note that you can set it up when you add the MQTT integration: https://www.home-assistant.io/integrations/mqtt/

1. Settings → Add-ons → Add-on store → install Mosquitto broker → Start.
2. Settings → Devices & services → add/configure the MQTT integration (it often appears as discovered). Enable discovery if prompted.
3. Create a dedicated MQTT user/login for Zigbee2MQTT in the Mosquitto app configuration (do not reuse chat-pasted passwords; generate your own).

Mosquitto app documentation (official add-on DOCS): https://github.com/home-assistant/addons/blob/master/mosquitto/DOCS.md

Step 2: Install the Zigbee2MQTT Home Assistant app

Add the official repository and install the stable Zigbee2MQTT app:

1. Settings → Add-ons → Add-on store → ⋮ (menu) → Repositories.
2. Add https://github.com/zigbee2mqtt/hassio-zigbee2mqtt then refresh.
3. Install Zigbee2MQTT (stable), not the edge build, unless you intentionally want unreleased fixes.
4. Start the app, then open its Web UI for onboarding.

Repository / install instructions: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
Onboarding overview: https://www.zigbee2mqtt.io/guide/getting-started/

Step 3: Onboarding — serial port, adapter type, MQTT

On first start (no configuration.yaml yet), Zigbee2MQTT serves an onboarding page (same URL as the frontend; on HA this is the app’s Web UI).

• Coordinator — pick your stick under Found Devices when discovery works. That fills port and adapter type.
• MQTT server — for the Mosquitto Home Assistant app use mqtt://core-mosquitto:1883 (Zigbee2MQTT MQTT docs mention core-mosquitto specifically for that add-on). Docs: https://www.zigbee2mqtt.io/guide/configuration/mqtt.html
• MQTT user/password — the dedicated login you created.
• Home Assistant integration — enable it so discovery payloads are published (homeassistant.enabled: true in YAML terms). See: https://www.zigbee2mqtt.io/guide/usage/integrations/home_assistant.html
• Wi‑Fi-aware channel hint — if the wizard asks for your nearest 2.4 GHz Wi‑Fi channel, answer honestly so it can suggest a less-colliding Zigbee channel.

If discovery fails with USB adapter discovery error (No valid USB adapter found), set the serial section manually. On Linux, prefer the stable by-id path:

ls -l /dev/serial/by-id

Example shape from the adapter-settings docs (replace with your by-id string and adapter type):

serial:
port: /dev/serial/by-id/usb-…-if00
adapter: zstack

Allowed adapter values documented there include zstack, ember, deconz, zigate, and zboss. Full guide: https://www.zigbee2mqtt.io/guide/configuration/adapter-settings.html

On Home Assistant OS you can also inspect hardware under Settings → System → Hardware, or via ha hardware info on the CLI, as noted in the hassio-zigbee2mqtt README.

Step 4: Move the stick off the Pi (USB extension)

Before you blame “bad Zigbee,” read the official range guide. Plugging a USB coordinator straight into a Raspberry Pi (especially next to USB 3 / SSD / HDMI) is a classic way to murder the radio.

• Use a USB extension of about 50 cm minimum; shielded cables often behave better.
• Keep the stick away from Wi‑Fi routers, USB 3 ports, and SSDs.
• Prefer a USB 2 port when you have the choice.
• Rotate the dongle slightly while watching linkquality—orientation matters.

Source: https://www.zigbee2mqtt.io/advanced/zigbee/02_improve_network_range_and_stability.html

For load-shedding households: park the coordinator where the mesh can still reach rooms that stay on UPS (passage lights, study sensors), not buried behind a metal PC case in a far garage.

Step 5: Pair your first devices

In the Zigbee2MQTT frontend, enable join / permit join, then put the device into pairing mode per its supported-devices page. A successful interview looks like the log line in the getting-started guide (“Successfully interviewed… device has successfully been paired”).

• Pair close to the coordinator the first time.
• For battery devices, keep them awake (button presses) during interview.
• Add at least a few mains-powered routers (many AC bulbs/plugs route; no-neutral relays often do not)—the range guide explains why end devices need a healthy return path.

Supported devices index (start from the site nav / getting-started “Connect a device” section): https://www.zigbee2mqtt.io/guide/getting-started/

Step 6: Reduce Wi‑Fi vs Zigbee fights

Zigbee and Wi‑Fi share 2.4 GHz. If you see timeouts, unreachable devices, or MAC_CHANNEL_ACCESS_FAILURE, change the Zigbee channel in configuration (know that some devices may need re-pairing). The improve-network guide and FAQ cover channel choice and coexistence: https://www.zigbee2mqtt.io/advanced/zigbee/02_improve_network_range_and_stability.html · https://www.zigbee2mqtt.io/guide/faq/

Practical SA tip: map your own AP’s 2.4 GHz channel in the router UI, then pick a Zigbee channel that sits further away in spectrum. Also watch for neighbour Wi‑Fi density, Bluetooth audio dongles, and leftover Hue bridges on conflicting channels—the same official page calls those out.

Step 7: Confirm Home Assistant entities

With MQTT discovery on and homeassistant.enabled: true, new Zigbee devices should appear under Settings → Devices & services → MQTT. Rename friendly names in the UI; the Zigbee2MQTT Home Assistant integration guide explains device-registry behaviour: https://www.zigbee2mqtt.io/guide/usage/integrations/home_assistant.html

From there, build boring-but-gold automations: door open → notify; button → toggle a light; motion → night light. Prefer these local Zigbee entities for “grid just died” shedding so you are not waiting on a cloud API while the UPS clock is ticking.

Common failures (check these first)

• 502 Bad Gateway on the frontend right after start — wait and refresh; if it persists, read the app Log tab.
• No valid USB adapter — set port + adapter explicitly; use /dev/serial/by-id/….
• ZHA still holding the stick — disable ZHA, restart Zigbee2MQTT.
• MQTT ECONNREFUSED on localhost — from inside the HA app network you usually want mqtt://core-mosquitto:1883, not localhost. MQTT config reference: https://www.zigbee2mqtt.io/guide/configuration/mqtt.html
• Flaky pairing on a Pi — extension cable, USB 2 port, powered hub for other peripherals (FAQ).

Load-shedding design notes

• Keep Home Assistant, Mosquitto, the Zigbee stick, and your main AP/router on the same UPS essentials circuit.
• Use Zigbee (or other local) switches for the loads you shed when NUT reports on-battery—cloud plugs may already be unreachable.
• Build the mesh with routers in lived-in rooms; a coordinator alone in a rack will not cover a typical house.

What success looks like

Zigbee2MQTT frontend shows your coordinator online, at least one device interviewed, MQTT messages flowing, and matching entities in Home Assistant—all without any vendor cloud login. When Wi‑Fi guests jam the 2.4 GHz band or the fibre ONT reboots after a stage-4 blip, your Zigbee buttons and sensors should still answer on the LAN.

Next upgrades once the stick is happy: add router devices room-by-room, export a network map via the bridge MQTT request documented in the range guide, and only then chase exotic battery gadgets.

Official links checklist

• Getting started: https://www.zigbee2mqtt.io/guide/getting-started/
• Supported adapters: https://www.zigbee2mqtt.io/guide/adapters/
• Adapter settings: https://www.zigbee2mqtt.io/guide/configuration/adapter-settings.html
• Improve range & stability: https://www.zigbee2mqtt.io/advanced/zigbee/02_improve_network_range_and_stability.html
• HA app repo: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
• Home Assistant MQTT: https://www.home-assistant.io/integrations/mqtt/
• Zigbee2MQTT ↔ Home Assistant: https://www.zigbee2mqtt.io/guide/usage/integrations/home_assistant.html