Project: Zigbee in ioBroker - the direct zigbee adapter vs Zigbee2MQTT in Docker with the zigbee2mqtt adapter

[ZerOne]

ioBroker gives you two main routes to Zigbee. Both are community-maintained adapters; the details below come from their READMEs/wikis (October 2026). The zigbee2mqtt adapter was at version 3.2.10 (2026-10-24) when I looked, and Zigbee2MQTT itself at 2.14.x.

Route A - ioBroker.zigbee (direct)

The zigbee adapter talks directly to a Zigbee coordinator and manages the network itself, with no vendor bridge or extra gateway. The README says compatibility covers more than 4,000 devices from more than 450 vendors.

• One coordinator per adapter instance, flashed with coordinator firmware. Common chips: Texas Instruments CC26xx, Silicon Labs EZSP, ZiGate. The README recommends CC2652/CC1352-based devices; CC253x devices are still supported but no longer recommended.
• Only CC26xx/CC1352/CC2538 devices support extracting the NVRAM backup, which is what lets you swap coordinator hardware without re-pairing everything.
• Firmware for TI devices: Koenkk/Z-Stack-firmware. Supported coordinators are listed on the Zigbee2MQTT adapters page.
• Good fit if: ioBroker is your only platform and you want the fewest moving parts.

Route B - Zigbee2MQTT in Docker + ioBroker.zigbee2mqtt

Here Zigbee2MQTT owns the coordinator and the Zigbee network. The zigbee2mqtt adapter reads the Z2M devices into ioBroker data points and lets you control them. Good fit if you want Z2M's frontend and device support, or want the same Zigbee network available to other systems (Home Assistant, openHAB, Domoticz) or the freedom to move away from ioBroker later without re-pairing.

Points from the adapter's get-started guide:

• If the coordinator was used somewhere else before, it must be reset, otherwise errors will happen.
• Z2M always needs an MQTT server to start. The adapter doesn't use MQTT for its data itself in the recommended setup, but one still has to exist. Either use the adapter's option to create a dummy MQTT server (the docs use port 1885 by default), or run your own broker such as Mosquitto.
• The recommended adapter connection type is WebSocket to the Z2M frontend (IP of the Z2M host, port 8080 by default). If you use Z2M's frontend auth token, note the adapter says special characters aren't supported in it.
• If you view ioBroker over HTTPS, the Z2M web UI connection configured in the adapter must be HTTPS too.

Docker compose for Z2M (based on the official Z2M Docker docs; 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:
      - ./zigbee2mqtt/data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - 8080:8080
    environment:
      - TZ=Australia/Sydney
    devices:
      - /dev/serial/by-id/YOUR-ADAPTER-by-id:/dev/ttyACM0

configuration.yaml (in ./zigbee2mqtt/data; compare with the official generator and the adapter's own recommended config before use):

Code: Select all

version: 5
mqtt:
    base_topic: zigbee2mqtt
    server: mqtt://<IOBROKER_IP>:1885       # the dummy MQTT server port you chose in the adapter
serial:
    port: /dev/ttyACM0
    adapter: zstack                         # or ember / deconz / zigate / zboss - see your adapter's page
frontend:
    enabled: true
    port: 8080
    host: 0.0.0.0
homeassistant:
    enabled: false                          # not needed for ioBroker
advanced:
    channel: 11
    network_key: GENERATE
    pan_id: GENERATE
    ext_pan_id: GENERATE

Steps:

1. In ioBroker, install the zigbee2mqtt adapter from the Adapters tab and (if needed) tick "Create dummy MQTT server" in its settings.
2. Start the Z2M container (docker compose up -d) and check the frontend at http://<docker-host>:8080.
3. In the adapter settings choose WebSocket and enter the Z2M host IP and port.
4. Permit join in the Z2M frontend (it opens the network for 254 seconds) and pair devices following the pairing guide. They appear as ioBroker objects.

Migrating from the direct zigbee adapter: the adapter wiki has an English guide "Installation incl. moving from ioBroker/Zigbee adapter" that lets you reuse the same Zigbee network so devices don't need re-pairing. It requires converting the PAN ID to hex and rewriting the extended PAN ID and network key in Z2M's notation. Back everything up first and read the full guide at the adapter wiki; I have not tested it.

Which should you pick?

• Single platform, minimum components: Route A.
• Z2M's tooling, shared network, or the option to change platforms later: Route B.
• Either way, never let two systems control the same coordinator at once.

Related: Tasmota and ONVIF cameras

For Tasmota switches/plugs, the sonoff adapter is the simplest if Tasmota is your only MQTT source; otherwise use the mqtt adapter in broker mode. For cameras, the onvif adapter discovers ONVIF cameras and exposes events and PTZ presets as states you can use from JavaScript.

Question for the group: which route are you using for Zigbee in ioBroker, and what coordinator? If you migrated from the direct adapter to Zigbee2MQTT (or the other way), how did it go?