Knowledge Center

Popular Search mod
View Categories

Zigbee2MQTT

Table of Contents
Zigbee
Zigbee USB stick CC2531 met antenne 02

Using MQTT to retrieve data from zigbee devices, using a Zigbee CC253x stick on a Orange/Raspberry Pi.

Docker #

We are going to use Docker for conveniance, because nodejs could cause conflict when using in combination with Node-Red.

Install Docker:

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose docker-compose-plugin

Install docker zigbee2mqtt

sudo docker pull ghcr.io/koenkk/zigbee2mqtt

output:

Using default tag: latest
latest: Pulling from koenkk/zigbee2mqtt
6e771e15690e: Pull complete
c24049c7dede: Pull complete
523dbe2d38ce: Pull complete
16ed23037b9d: Pull complete
bc3e2cb750a0: Pull complete
ae159a47c44a: Pull complete
97f671261fa7: Pull complete
ba47a1e3e308: Pull complete
5662f55c57b8: Pull complete
7308ceab2344: Pull complete
6bba0a1b9aa5: Pull complete
Digest: sha256:5c1f0ca9669292b1bdabc7b6d9927642049bc2c1ee53f42b7299181e93dd7d8f
Status: Downloaded newer image for ghcr.io/koenkk/zigbee2mqtt:latest
ghcr.io/koenkk/zigbee2mqtt:latest

Using docker compose #

docker-compose.yaml #

sudo nano ~/docker-compose.yaml

contents:

services:
    zigbee2mqtt:
        container_name: zigbee2mqtt
        image: ghcr.io/koenkk/zigbee2mqtt
        restart: unless-stopped
        volumes:
            - ./data:/app/data
            - /run/udev:/run/udev:ro
        ports:
            # Frontend port
            - 8080:8080
        environment:
            - TZ=Europe/Amsterdam
        devices:
            # Make sure this matched your adapter location
            - /dev/ttyACM0:/dev/ttyACM0

configuration.yaml #

In this file (if not already created) make sure mqtt server is set to: “server: ‘mqtt://172.17.0.1“

mkdir -p ~/data/ && touch ~/data/configuration.yaml

sudo nano ~/data/configuration.yaml

contents:

version: 4
mqtt:
  base_topic: zigbee2mqtt
  server: 'mqtt://172.17.0.1'
serial:
  port: /dev/ttyACM0
  adapter: zstack
  baudrate: 115200
  rtscts: false
advanced:
  log_level: info
  channel: 11
  network_key:
    - 89
    - 115
    - 112
    - 226
    - 251
    - 12
    - 151
    - 12
    - 83
    - 121
    - 172
    - 204
    - 94
    - 86
    - 35
    - 251
  pan_id: 46370
  ext_pan_id:
    - 132
    - 245
    - 213
    - 13
    - 127
    - 9
    - 126
    - 99
frontend:
  enabled: true
  port: 8080
homeassistant:
  enabled: false

Start Zigbee2MQTT #

Start the container with this command:

sudo docker compose up -d zigbee2mqtt

(NOTE to restart compose with command: sudo docker-compose restart)

Output:

[+] Running 2/2
 ✔ Network pi_default     Created                                                                                                                       0.2s
 ✔ Container zigbee2mqtt  Started

Test MQTT bridge with the command:

ping 172.17.0.1

Output:

PING 172.17.0.1 (172.17.0.1) 56(84) bytes of data.
64 bytes from 172.17.0.1: icmp_seq=1 ttl=64 time=0.191 ms
64 bytes from 172.17.0.1: icmp_seq=2 ttl=64 time=0.115 ms
64 bytes from 172.17.0.1: icmp_seq=3 ttl=64 time=0.136 ms
64 bytes from 172.17.0.1: icmp_seq=4 ttl=64 time=0.163 ms

View the LOG if everything is ok:

sudo docker-compose logs

Follow/running log (CTRL+C to exit)

sudo docker-compose logs -f

Example output:

zigbee2mqtt    | [2025-04-14 19:03:20] info:    z2m: Starting Zigbee2MQTT version 2.2.1 (commit #a14feef8c13f5ce49b0ac358d98d3234d21d7ff4
zigbee2mqtt    | )
zigbee2mqtt    | [2025-04-14 19:03:20] info:    z2m: Starting zigbee-herdsman (3.4.11)
zigbee2mqtt    | [2025-04-14 19:03:20] info:    zh:adapter:discovery: Matched adapter: {"path":"/dev/ttyACM0","manufacturer":"Texas Instruments","serialNumber":"__0X00124B001CCC7D22","pnpId":"usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B001CCC7D22-if00","vendorId":"0451","productId":"16a8"} => zstack: 4
zigbee2mqtt    | [2025-04-14 19:03:20] info:    zh:zstack:znp: Opening SerialPort with {"path":"/dev/ttyACM0","baudRate":115200,"rtscts":false,"autoOpen":false}
zigbee2mqtt    | [2025-04-14 19:03:20] info:    zh:zstack:znp: Serialport opened
zigbee2mqtt    | [2025-04-14 19:03:20] info:    z2m: zigbee-herdsman started (resumed)
zigbee2mqtt    | [2025-04-14 19:03:20] info:    z2m: Coordinator firmware version: '{"meta":{"maintrel":3,"majorrel":2,"minorrel":6,"product":0,"revision":20180507,"transportrev":2},"type":"zStack12"}'
zigbee2mqtt    | [2025-04-14 19:03:20] info:    z2m: Currently 0 devices are joined.
zigbee2mqtt    | [2025-04-14 19:03:20] info:    z2m: Connecting to MQTT server at mqtt://172.17.0.1
zigbee2mqtt    | [2025-04-14 19:03:20] info:    z2m: Connected to MQTT server
zigbee2mqtt    | [2025-04-14 19:03:20] info:    z2m:mqtt: MQTT publish: topic 'zigbee2mqtt/bridge/state', payload '{"state":"online"}'
zigbee2mqtt    | [2025-04-14 19:03:21] info:    z2m: Started frontend on port 8080
zigbee2mqtt    | [2025-04-14 19:03:21] info:    z2m: Zigbee2MQTT started!

Here in the log you can see the Zigbee stick is found and there is a connection with the MQTT server (bridge), the webinterface is running on port 8080

Autostart Docker #

To autostart docker on reboot, use the command:

sudo systemctl enable docker

Output:

Synchronizing state of docker.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable docker
Created symlink /etc/systemd/system/multi-user.target.wants/docker.service → /lib/systemd/system/docker.service.

Add Zigbee devices #

To add Zigbee devices go to the webinterface on port 8080 and click the BUTTON above to add devices (in a 4-5 minute time window):

After pressing the button you can add devices, by pressing the reset button on them (the led will flash 3 times), the zigbee devices will be found and added to the system, you can rename them if you want:

MQTT messages #

The MQTT messages are all JSON, you can view the LOG file to see the TOPIC and data that is send to the MQTT server:

zigbee2mqtt    | [2025-04-14 21:26:20] info:    z2m:mqtt: MQTT publish: topic 'zigbee2mqtt/schakelaar', payload '{"action":"single","battery":100,"linkquality":136,"voltage":3900}'
zigbee2mqtt    | [2025-04-14 21:26:29] info:    z2m:mqtt: MQTT publish: topic 'zigbee2mqtt/deursensor', payload '{"battery":100,"battery_low":false,"contact":true,"linkquality":131,"voltage":3000}'
zigbee2mqtt    | [2025-04-14 21:26:31] info:    z2m:mqtt: MQTT publish: topic 'zigbee2mqtt/deursensor', payload '{"battery":100,"battery_low":false,"contact":false,"linkquality":131,"voltage":3000}'
zigbee2mqtt    | [2025-04-14 21:18:06] info:    z2m:mqtt: MQTT publish: topic 'zigbee2mqtt/tempsensor', payload '{"humidity":38.53,"linkquality":168,"temperature":28.42}'

Node-Red #

In Node-Red install the palette: node-red-contrib-zigbee2mqtt

You can configure the nodes and select the MQTT server and device to get the JSON messages:

Products #

Source #

https://www.zigbee2mqtt.io/guide/installation/02_docker.html