Project: Zigbee2MQTT + Mosquitto with Home Assistant (MQTT discovery), and when ZHA is the better pick

[ZerOne]

This is a practical walkthrough for running Zigbee2MQTT (Z2M) alongside Home Assistant using an MQTT broker. Everything here is based on the official Zigbee2MQTT and Home Assistant docs as at October 2026 (Z2M 2.14.x, Home Assistant 2026.10.x). I have not tested every variation, so please post corrections.

ZHA or Zigbee2MQTT?

Both talk to a Zigbee coordinator and both work well. Differences that matter in practice:

• ZHA is built into HA, is auto-discovered when you plug in a supported coordinator, and there is nothing else to install. Simplest path for a HA-only setup.
• Zigbee2MQTT is a separate service with its own web frontend, and it publishes everything to MQTT. That makes it independent of HA: the same Z2M network can feed Home Assistant, openHAB, ioBroker or Domoticz, and you can rebuild or move the automation platform without re-pairing devices. The price is two extra moving parts (broker + Z2M).
• Only one of them can own a given coordinator at a time. Switching later generally means re-pairing devices (the Z2M docs have an adapter-migration FAQ - read it before changing anything).

What you need

• A supported coordinator, flashed with coordinator firmware (some come pre-flashed). The Z2M adapters page has recommended zStack (Texas Instruments) and EmberZNet (Silicon Labs) options. Adapters ending in "P" (e.g. CC2652P) have a power amplifier (20 dBm vs 5 dBm for "R"/"RB" parts), and only zStack/Ember adapters support coordinator backups.
• A USB adapter close to the host but away from USB 3 ports/SSDs (a short USB extension helps) - general Zigbee practice rather than a doc quote.
• Prefer a locally connected USB/UART adapter. The Z2M docs warn that adapters connected over WiFi can be unstable, and recommend a wired Ethernet network adapter if you cannot use a local one.

Option A: Home Assistant OS (apps)

On HAOS or Supervised, Z2M is available as an app (the Z2M docs still call it the "Home Assistant addon"). Per its page: only 64-bit hosts are supported, and a Raspberry Pi 3 may be unstable, so use a Pi 4 or newer.

1. Install and start the Mosquitto broker app, and add the MQTT integration in HA (Settings > Devices & services > Add Integration > MQTT).
2. Install the Zigbee2MQTT app following the official instructions. When Z2M talks to the Mosquitto app, the Z2M docs say to use core-mosquitto as the MQTT server host.
3. Set the serial port to your adapter's /dev/serial/by-id/... path and the adapter type.
4. Make sure the Home Assistant integration is enabled in Z2M (see the config below).

Option B: Docker (HA Container, or any Docker host)

Step 1 - Mosquitto. Mosquitto 2.x refuses remote connections unless you configure a listener and decide on authentication. A minimal setup with a password file:

Code: Select all

# mosquitto/config/mosquitto.conf
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd

Code: Select all

# create the password file (run once, then restart the broker)
docker run --rm -it -v "$(pwd)/mosquitto/config:/mosquitto/config" eclipse-mosquitto:2 \
  mosquitto_passwd -c /mosquitto/config/passwd z2m

(The Domoticz wiki's example uses allow_anonymous true, which lets anything on your LAN publish to the broker. I would use credentials, especially if you have IoT devices on the same VLAN.)

Step 2 - Zigbee2MQTT. Official docker compose example, trimmed (check your adapter path with ls -l /dev/serial/by-id):

Code: Select all

services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: ghcr.io/koenkk/zigbee2mqtt
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - 8080:8080          # Z2M frontend
    environment:
      - TZ=Australia/Sydney
    devices:
      - /dev/serial/by-id/YOUR-ADAPTER-by-id:/dev/ttyACM0

Step 3 - configuration.yaml (in the data folder). This follows the structure of the generator on the Z2M docs site. The Z2M docs caution not to rely on unverified AI-generated configs, so compare it to the configuration page:

Code: Select all

version: 5
mqtt:
    base_topic: zigbee2mqtt
    server: mqtt://<BROKER_IP>:1883
    user: z2m
    password: <your password>
serial:
    port: /dev/serial/by-id/<YOUR-ADAPTER>
    adapter: zstack          # or ember, deconz, zigate, zboss - see your adapter's page
advanced:
    channel: 11              # pick a channel away from your WiFi 2.4 GHz channels
    network_key: GENERATE
    pan_id: GENERATE
    ext_pan_id: GENERATE
frontend:
    enabled: true
homeassistant:
    enabled: true

If you start Z2M without a config you will be taken through an onboarding page on port 8080 instead.

Connecting to Home Assistant

1. Add the MQTT integration in HA pointing at the broker (same user/password).
2. With homeassistant: enabled: true Z2M publishes MQTT discovery messages under the homeassistant topic. Keep the discovery topic different from the base topic (zigbee2mqtt) - the Z2M docs call this out.
3. Open the Z2M frontend (port 8080), click Permit join (All) (it opens the network for 254 seconds), then put the device in pairing mode. Check the device's page on the Z2M supported devices list for pairing instructions.
4. The device and its entities show up in HA automatically via the device registry. Rename entities in HA without restarting.

Buttons and remotes

The recommended method per the Z2M docs is MQTT device triggers. They are discovered after the device generates an action at least once, so press every button on the physical remote once, then pick "Device" as the trigger type in the automation editor. The "action sensor" approach is deprecated, and the event-entity approach is flagged experimental.

Gotchas

• Always use the /dev/serial/by-id/ path rather than /dev/ttyUSB0 - numbering can change on reboot.
• Never give the same coordinator to ZHA and Z2M at once.
• Do not expose the Z2M frontend or the broker to the internet. If the frontend is reachable by untrusted devices, look at the frontend authentication options in the frontend docs.
• MQTT Explorer (mqtt-explorer.com) is very handy for confirming discovery and state topics are actually being published.

Question for the group: are you running Z2M or ZHA with Home Assistant, and which coordinator are you using? If you have migrated between the two, what did you learn the hard way?