← Back to Homelab & Automation
Homelab & Automation

Smart Home Automation: Integrating Home Assistant and Zigbee2MQTT

Smart home technology is incredible, but relying on vendor cloud servers (like Tuya, SmartLife, or SmartThings) introduces latency, internet-dependency, and privacy issues.

In this guide, we will look at how to build a local-first smart home by running Home Assistant in your homelab and integrating it with Zigbee2MQTT using a USB coordinator.

1. The Architecture

By shifting to local-first Zigbee devices, your smart home communicates entirely within your own walls:

  1. Zigbee Devices (motion sensors, smart switches, bulbs) talk to a coordinator.
  2. The coordinator (e.g., Sonoff Zigbee 3.0 USB Dongle Plus) is plugged into your homelab server.
  3. Zigbee2MQTT translates the raw Zigbee signals into JSON payloads and publishes them to an MQTT broker.
  4. Home Assistant listens to the MQTT broker and surfaces these devices as standard entities ready for automation.

2. Setting Up the MQTT Broker (Mosquitto)

If you are running Docker or Docker Compose in your homelab, setting up Eclipse Mosquitto is simple:

version: '3.8'
services:
  mosquitto:
    image: eclipse-mosquitto:2.0
    container_name: mosquitto
    ports:
      - "1883:1883"
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log
    restart: unless-stopped

Ensure you create a basic configurations file under ./mosquitto/config/mosquitto.conf:

listener 1883
allow_anonymous true

3. Configuring Zigbee2MQTT

Plug your Zigbee coordinator into the server, check its path (usually /dev/ttyUSB0 or /dev/serial/by-id/...), and deploy Zigbee2MQTT:

  zigbee2mqtt:
    image: koenkk/zigbee2mqtt:latest
    container_name: zigbee2mqtt
    depends_on:
      - mosquitto
    volumes:
      - ./zigbee2mqtt-data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - 8080:8080
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    restart: unless-stopped

In your data/configuration.yaml:

homeassistant: true
permit_join: true
mqtt:
  base_topic: zigbee2mqtt
  server: 'mqtt://mosquitto:1883'
serial:
  port: /dev/ttyUSB0
frontend:
  port: 8080

Once running, navigate to http://<server-ip>:8080 to access the Zigbee2MQTT dashboard and begin pairing your smart bulbs, switches, and sensors.

4. Integration with Home Assistant

In Home Assistant:

  1. Navigate to Settings > Devices & Services.
  2. Click Add Integration and search for MQTT.
  3. Point the integration to your MQTT Broker (<server-ip>:1883).
  4. Because we set homeassistant: true in the Zigbee2MQTT configuration, all paired devices will automatically populate in Home Assistant instantly!

5. Writing Local Automations

Now you can create smart routines. Let’s write an automation that turns on a smart plug when a motion sensor detects occupancy, but only after sunset:

alias: "Turn on Office Lamp on Motion after Sunset"
trigger:
  - platform: state
    entity_id: binary_sensor.office_motion_occupancy
    to: "on"
condition:
  - condition: sun
    after: sunset
action:
  - service: switch.turn_on
    target:
      entity_id: switch.office_lamp_plug

This runs with sub-millisecond latency because it doesn’t need to hop to a distant server and back. It works even if your WAN internet connection is completely down.

Stay tuned for more guides on advanced automation scripting and self-hosted dashboards!