Home Lab Series Part 8: Zigbee, Z-Wave, and The "Dongle"

Up until now, our Home Lab has lived entirely inside the computer. It organizes files and blocks ads. But it doesn't do anything in the physical world.

To control lights, locks, and sensors, you need a radio. While you can buy Wi-Fi smart plugs, they clog up your router and usually rely on a Chinese cloud server to function. The pro move is to use Local Mesh Networks.

Zigbee vs. Z-Wave

These are the two heavyweights of local automation. Both create a "Mesh," meaning every lightbulb you add acts as a repeater for the next one.

The Hardware: The "Dongle"

Your server doesn't have a Zigbee radio inside it. You need a USB Coordinator.

For this guide, we recommend the Sonoff Zigbee 3.0 USB Dongle Plus (Model "P"). It costs about $25, has a massive external antenna, and works perfectly with open-source software.

1. Plug the USB Dongle into your Server/Pi.
2. We need to find out where Linux sees it. In your terminal, run:

ls -l /dev/serial/by-id

Copy the long string it spits out (e.g., /dev/serial/by-id/usb-ITead_Sonoff_Zigbee...). You will need this for the Docker stack.

The Software: MQTT & Z2M

To make this work, we need two pieces of software:

1. Mosquitto (MQTT Broker): Think of this as a chat room for your devices. Sensors post messages ("I am open"), and Home Assistant reads them.
2. Zigbee2MQTT (Z2M): The driver that talks to the USB stick and translates the radio signals into MQTT messages.

The Zigbee Stack

In Portainer, create a new Stack called zigbee and paste this:

services:
  mqtt:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
    restart: unless-stopped

  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt
    restart: unless-stopped
    volumes:
      - ./zigbee2mqtt/data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - 8081:8080 # This is the Web Dashboard
    environment:
      - TZ=America/New_York
    devices:
      # PASTE YOUR LONG SERIAL ID HERE:
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2-if00:/dev/ttyACM0

Pairing Your First Device

Once the stack is running, go to http://[YOUR-IP]:8081. This is the Zigbee2MQTT dashboard.

1. Click "Permit Join (All)" in the top bar. The countdown starts.
2. Take your Zigbee sensor (like an Aqara Door Sensor) and hold the reset button for 5 seconds until it flashes blue.
3. Watch the dashboard. You will see "Device Joined" and it will interview the device to find out what it is.
4. Give it a friendly name (e.g., "Front Door").

Congratulations! You are now receiving live data from the physical world.

Conclusion

You have laid the physical foundation for a smart home. You have the radio (Dongle), the translator (Z2M), and the messenger (MQTT).

Coming Up in Part 9: We will connect all of this into the "Brain" of the operation: Home Assistant.