Zigbee2MQTT — A simple step-by-step guide on how to have all your Zigbee devices under your full control

Why Zigbee?

The hardware

  • A Raspberry Pi, preferably the Pi 4 with 2 or 4 GB of RAM
  • A USB (C for the Pi 4, Micro USB for the older ones) power supply with around 3.0A
  • A microSD card, 16+GB from a reliable manufacturer, should be fast: class 10/UHS-1
  • Optional: a case (with cooling) for the Pi
  • Optional: if you don’t have one yet buy a SD card reader/writer
  • Optional: Network access. Either a LAN cable or if you are not using a newer Pi a seperate Wifi USB dongle.
Cheap but powerful Zigbee Aqara devices


Zigbee2MQTT setup

// find the serial port the USB adapter is connected to. Check with
ls -l /dev/ttyACM0 // <- standard port
// you need to install Node.js 12 for this to work which is unfortunately not (yet) in the normal repos. So do it this way
sudo curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
sudo apt-get install -y nodejs git make g++ gcc
// check with
node --version # Should output v12.X or v10.X
npm --version # Should output 6.X
// now clone the actual software from Github
sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
sudo chown -R pi:pi /opt/zigbee2mqtt // replace pi with your user
// and install dependencies
cd /opt/zigbee2mqtt
npm ci
// installation should be done :) Now open the config file for Zigbee2MQTT
nano /opt/zigbee2mqtt/data/configuration.yaml
homeassistant: false
permit_join: true
base_topic: zigbee2mqtt
server: 'mqtt://localhost'
# user: my_user
# password: my_password
port: /dev/ttyACM0
network_key: GENERATE
// ... see rest of tutorial
sudo apt update // get newest packages
sudo apt install mosquitto // install mosquitto

Pairing a device

tail -f /opt/zigbee2mqtt/data/log/TheDateYouStartedTheService/log.txt
// use the newest date; the log file is sometimes called log2, log3, ...
// if a log statement like this appeared pairing was successful
"Successfully interviewed '0x00158d0001dc126a', device has successfully been paired"
'0x00158d0002b7f7fe': // this is the id of the new device, don't change it
friendly_name: MotionSensor1 // this will initially be the id too. Change it to a name you can recognize for easier use later on
retain: false // I don't see why we should save messages, so disable this

Smart home controller integration — OpenHab 2




I am a DIY, smart home and automation enthusiast. I am sharing my journey here and on my blog thesmarthomejourney.com

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

DataDownload: Tech companies and BLM. Actions or Words?

Oppo Reno7 Pro 5G

Why EVERY Man Should Wear a Watch

Stories that aren’t immersive aren’t remembered.

Web3 Fashion Community Events in New York City + More

The digital disconnect

‘Voice usage is abysmal.’

Best Accessories for Samsung Galaxy Z Fold 3 or Z flip 3

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store


I am a DIY, smart home and automation enthusiast. I am sharing my journey here and on my blog thesmarthomejourney.com

More from Medium

How Are Agate Beads Used In DIY Jewelry Making

How Much Information Can Be Sent Reliably from Halifax to Dartmouth Under the Water?

A friendly reminder. Martin Luthers King Jr.'s murders mindset is alive and well today.

The Weeknd: The Dawn FM Review – a cinematic joyride for the ages