zigbee2mqtt Setup in Docker for Home Automation

Summary

Allows off the shelf zigbee devices to report to mqtt server. Total cost <NZ$10 if you can borrow a debugger. Obviously you need a server to run the services on – I used docker, and have a NUC for this that already runs mosquitto, homeassistant etc.

A Zigbee repeating device (mesh store/forward) is called a Router, and the main device that receives the zigbee signals and passes it to the server is called the coordinator.

Arguably, the cost of zigbee end devices can be more than a D1 Mini and a sensor, but having router/mesh capability, months of battery operation etc can make it viable. I plan to use for various temp sensing, leak detection and possibly smoke/fire detection in some spaces where cabling is harder. My temp/humid sensors were $20 each.

From getting the firmware on the stick to getting temp data displaying on my phone was less than an hour… most of that was due to not following instructions well enough, and copying/pasting from the website (that has minor formatting and text errors – I’ve pushed fixes)

Instructions & Links

The main site to follow: https://www.zigbee2mqtt.io/
The Docker instructions: https://www.zigbee2mqtt.io/information/docker.html
The Flashing instructions: https://www.zigbee2mqtt.io/getting_started/flashing_the_cc2531.html
Building a router: https://www.zigbee2mqtt.io/how_tos/how_to_create_a_cc2530_router.html
Using CC2531 for a Router: https://ptvo.info/cc2531-based-router-firmware-136/
Helpful info if the container won’t start (it won’t if it can’t find the serial device) https://www.zigbee2mqtt.io/information/FAQ.html

My original docker command (when testing)

docker run \
-it \
-v /dockervolumes/zigbee2mqtt:/app/data \
--device=/dev/ttyACM1 \
-e TZ=Pacific/Auckland \
-v /run/udev:/run/udev:ro \
--privileged=true \
   koenkk/zigbee2mqtt

Docker Compose file

version: '3'
services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt:1.15.0
    volumes:
      - /myvolumes/zigbee2mqtt/data:/app/data
      - /run/udev:/run/udev:ro
    devices:
      - /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B00194AD8B7-if00:/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B00194AD8B7-if00
    restart: unless-stopped
    network_mode: host
    environment:
      - TZ=Pacific/Auckland

Equipment Used

Note that all you need is a CC2531 – the other stuff is just to change the firmware. In fact there are other ways to flash them, but this was very simple and around NZ$20 in parts all up.

CC2531 USB stick (approx NZ$6.50)
Debug Board & Cable (approx NZ$1.70)
https://www.aliexpress.com/item/32907079395.html

TI CC Debugger
https://www.aliexpress.com/item/32901173622.html (approx NZ$12.50)

CC2531 USB stick with antenna (approx NZ$12.70)
https://www.aliexpress.com/item/32982628286.html
I also got this to compare with the non-external antenna version, and/or make a zigbee repeater (router).

Stumbling blocks

• I expected to see the CC2531 at /dev/ttyACM0, and didn’t do the checks to confirm it was there ok. I forgot I had another serial device internally in my NUC and the CC2531 was bumped to /dev/ttyACM1 (I would have known had I followed the instructions more closely…)
• I then ended up using the actual /dev/serial name to ensure it always survived a reboot
• I hate YAML. It requires annoyingly exact formatting

Other Notes

• You need the debug cables, the pin headers on the debug board are pretty tight. $1.70 well spent.
• The CC Debugger took ages to receive from the Aliexpress supplier. Past the delivery dispute timeframe and the supplier didn’t extend. They responded to my questions, but I put in a dispute anyway. It eventually turned up.
• The photo here shows the correct direction for all the cables.  https://www.zigbee2mqtt.io/getting_started/flashing_the_cc2531.html (some connectors are not keyed) Note that I had 2 debugger cables to the board as one came with the debugger and one with the adaptor board. Each set was wired inversely – ie the cable exited the opposite side of the plug.
  

Devices

Currently supported zigbee devices: https://www.zigbee2mqtt.io/information/supported_devices.html

I bought some of these temp/humidity/pressure sensors for around NZ$20 each. I didn’t realise how tiny they were, and the boxes they ship in are huge by comparison. I thought they were about the size of a standard thermostat, but they are only 36x36x9mm. They have a button cell, 2 year battery life and a spare adhesive mount.
https://www.aliexpress.com/item/32966216308.html

It was way too easy to get them connected – they came out of the box with battery installed and working. I just saw a button on them which I pressed and within 5 seconds they appeared in mqttexplorer.

Next Steps

• I have a couple of temp sensors connected fine and they are a couple of rooms away from the USB Stick (with out external antenna). Gives a link quality of 44 so that isn’t bad. Will look at building a couple of routers (zigbee repeaters) and have ordered a CC2530+CC2591 combo https://www.aliexpress.com/item/1000007390542.html
• Most ‘powered’ zigbee items act as routers anyway, so you you have zigbee lightbulbs etc there is less need to build routers.
• You can get the CC2531 with a shell, which might be tidier but I plan to put mine up higher in a small box (clear lid obviously for flashy light!) with an extension USB cable for slightly better range.
• you need more routers etc if you add more than 20 devices anyway (see the FAQ page at the bottom) https://www.zigbee2mqtt.io/information/FAQ.html
• There are nice integrations for homeassistant, Node Red etc which gives things like a graphical switch to turn on/off pairing etc. Will play with these at some stage. There is even a hass.io plugin that runs zigbee2mqtt if you are a hass fan and don’t want to install/run the services directly.
• as of 2021, I’ve also bought more zigbee devices including leak detectors, vibration sensors, LCD temp/humidity sensors, PIRs. Zigbee devices aren’t for every situation, but they are a handy easy way to gather data if you don’t mind them being non-critical, and changing batteries occasionally.
• Also as at 2021 I’ve ordered a sonoff zigbee bridge to play with… there is a version of tasmota with (what is essentially) zigbee2mqtt embedded in it that can be used with this for a bridge that does not need a PC headend. https://tasmota.github.io/docs/Zigbee/
  

Zigmee2mqttassistant

This is a good idea to run
https://github.com/yllibed/Zigbee2MqttAssistant

version: '3.3'
services:
  zigbee2mqttassistant:
    ports:
      - '8880:80'
    environment:
      - Z2MA_SETTINGS__MQTTSERVER=192.168.X.XXX
      - Z2MA_SETTINGS__MQTTUSERNAME=uname
      - Z2MA_SETTINGS__MQTTPASSWORD=passwd
    restart: unless-stopped
    image: carldebilly/zigbee2mqttassistant:latest
    container_name: zigbee2mqttassistant