Home Assistant Zigbee and Z-Wave Integration

By LK Wood IV · 2026-05-22 · ~15 min read · St. Louis County, MO

Home Assistant running as a VM on Proxmox with no smart home protocol connected is a machine with no sensors. This guide adds Zigbee and Z-Wave: the two protocols that cover the vast majority of serious smart home devices, both running fully local with no cloud account required.

This builds directly on the Home Assistant on Proxmox setup guide. If HAOS isn’t running yet, start there.

Protocol choice: Zigbee, Z-Wave, or both

The honest breakdown:

Zigbee:

• 2.4 GHz frequency (shared with WiFi and Bluetooth)
• Device selection: enormous — most brands have Zigbee options (Aqara, Sonoff, Philips Hue, IKEA TRÅDFRI, SmartThings)
• Price per device: low ($10–25 for sensors, $15–30 for plugs)
• Mesh routing: automatic via mains-powered devices
• Interference sensitivity: moderate — a busy WiFi environment requires attention to channel selection

Z-Wave:

• 800–900 MHz frequency (no WiFi interference, essentially)
• Device selection: smaller but mature — Zooz, Inovelli, Aeotec, HomeSeer
• Price per device: higher ($35–80 for most devices)
• Mesh routing: automatic, 232 device max per network
• Interference sensitivity: very low

Recommendation for a new build: start with Zigbee. Add Z-Wave for specific devices (Z-Wave locks are often preferred for the certification requirement) or if Zigbee interference becomes a genuine problem in a dense WiFi environment.

Hardware you need

For Zigbee:

• Sonoff Zigbee 3.0 USB Dongle Plus ($15–20): CC2652P chip, USB-A connector, widely supported in Zigbee2MQTT. The “Plus” model (not the E model) is the correct one for Zigbee2MQTT.
• Or: SMLIGHT SLZB-06 ($40): network-connected coordinator, no USB cable needed, connects to Zigbee2MQTT over TCP/IP.

For Z-Wave:

• Zooz 800 Series USB Stick ZST39 LR ($40): Z-Wave 800 series chip, Long Range support, USB-A connector.
• Or: Aeotec Z-Stick 7 Plus ($50): widely supported, Z-Wave 700 series.

If running HAOS on Proxmox, the USB coordinator plugs into the Proxmox host and passes through to the HAOS VM.

USB passthrough to HAOS VM on Proxmox

This step is covered in the HAOS on Proxmox guide, but here’s the exact process:

1. Plug the USB coordinator into the Proxmox host
2. Identify it: lsusb — look for the Silicon Labs or Texas Instruments entry
3. In the Proxmox web UI → VM → Hardware → Add → USB Device
4. Select the coordinator by vendor/device ID (e.g., 10c4:ea60 for CP2102-based Sonoff dongles)
5. The VM must be stopped to add USB passthrough, then restarted

Verify it appears inside HAOS: Home Assistant → Settings → System → Hardware — the USB device should be listed.

Zigbee2MQTT setup

Zigbee2MQTT runs as a Home Assistant add-on inside HAOS. Install it:

1. Home Assistant → Settings → Add-ons → Add-on Store
2. Search “Zigbee2MQTT” (it’s in the community add-ons repository — if it doesn’t appear, add the repository: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt)
3. Install → Start
4. Configuration tab:

data_path: /config/zigbee2mqtt
socat:
  enabled: false
mqtt:
  server: mqtt://core-mosquitto
serial:
  port: /dev/ttyUSB0
  adapter: ezsp

Adjust serial.port to match where your coordinator appears (check Settings → System → Hardware). Common values: /dev/ttyUSB0, /dev/ttyACM0, /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus....

Using the /dev/serial/by-id/ path is more reliable — the ttyUSB0 assignment can shift if you plug in other USB devices.

MQTT broker: if Mosquitto isn’t installed, add it first: Add-on Store → Mosquitto broker → Install. Zigbee2MQTT writes device state to MQTT topics; Home Assistant reads those topics to create entities.

Pair your first Zigbee device

1. Open Zigbee2MQTT dashboard (the “Open Web UI” button in the add-on)
2. Click “Permit join” — Zigbee2MQTT opens the network for 60 seconds
3. Put your device in pairing mode (varies by device: usually a long button press or remove/reinsert battery)
4. The device appears in the Devices list within seconds
5. Rename it to something useful: “Living Room Motion Sensor”, “Kitchen Smart Plug”

Home Assistant automatically creates entities for the device via the MQTT discovery integration. New entities appear in Settings → Entities without any manual configuration.

Zigbee channel selection

Zigbee operates on channels 11–26 in the 2.4 GHz band. WiFi channels 1, 6, and 11 are the standard non-overlapping channels. The overlap looks like this:

Best Zigbee channels to avoid WiFi overlap: 15, 20, 25, or 26.

Set your Zigbee channel before pairing any devices — changing channels after pairing requires re-pairing everything. In Zigbee2MQTT configuration:

advanced:
  channel: 25

Use channel 25 if your router is on WiFi 11, or channel 20 if your router is on WiFi 6.

Z-Wave JS UI setup

For Z-Wave, the official Home Assistant integration uses Z-Wave JS directly. The simplest setup:

1. Home Assistant → Settings → Devices & Services → Add Integration → Z-Wave
2. Select “Z-Wave JS (Recommended)”
3. If Z-Wave JS isn’t running yet, HA prompts you to install the “Z-Wave JS” add-on — install it
4. In Z-Wave JS add-on configuration, set the USB path to your Z-Wave coordinator
5. Start the add-on, complete the HA integration setup

The Z-Wave JS UI add-on (separate from Z-Wave JS) adds a web interface for device management, network health visualization, and device configuration parameters. Install it alongside Z-Wave JS for anything beyond basic pairing:

Add-on Store → “Z-Wave JS UI” → Install

Z-Wave JS UI replaces the basic Z-Wave JS add-on — configure it with your coordinator path and the HA integration to use port 3000 instead of the default Z-Wave JS port.

Pairing Z-Wave devices

Z-Wave pairing (called “inclusion”) must happen with the device close to the coordinator — typically within 3 meters. Once paired, move the device to its permanent location.

1. Z-Wave JS UI web interface → Network → Add Node
2. Select “Secure Inclusion” (S2 authenticated for locks, S0 or S2 unauthenticated for sensors/switches)
3. Follow the device-specific pairing procedure (usually a button sequence on the device)
4. After inclusion, the device appears in HA automatically

Security classes matter for Z-Wave: smart locks should always be included with S2 Authenticated. Sensors and switches that don’t need security use S2 Unauthenticated or no security (unencrypted, faster for battery-powered devices).

Building automations with Zigbee/Z-Wave devices

Home Assistant automations in YAML or the GUI editor work the same regardless of whether the device is Zigbee, Z-Wave, or WiFi.

Example: Motion-activated light with time condition

alias: "Motion light - living room"
trigger:
  - platform: state
    entity_id: binary_sensor.living_room_motion
    to: "on"
condition:
  - condition: time
    after: "19:00:00"
    before: "23:00:00"
action:
  - service: light.turn_on
    target:
      entity_id: light.living_room_main
    data:
      brightness_pct: 80
      color_temp_kelvin: 3000

Example: Zigbee door sensor triggers alarm notification

alias: "Front door open - alert"
trigger:
  - platform: state
    entity_id: binary_sensor.front_door
    to: "on"
    for:
      minutes: 5
condition:
  - condition: state
    entity_id: input_boolean.alarm_armed
    state: "on"
action:
  - service: notify.mobile_app_phone
    data:
      message: "Front door has been open for 5 minutes"
      title: "Home Alert"

Example: Z-Wave smart plug energy monitoring

Zooz Z-Wave plugs with energy monitoring expose kWh and watt sensors automatically. Create a dashboard card:

type: sensor
entity: sensor.office_plug_current_consumption
name: "Office Wattage"

Or integrate with the Energy dashboard: Settings → Energy → Add Individual Device.

Zigbee mesh health

A healthy Zigbee mesh requires router devices distributed through your home. Key rules:

Mains-powered Zigbee devices are automatic routers. Smart plugs, smart bulbs, and in-wall switches extend the mesh. Battery-powered devices (sensors, remotes) are end devices that must connect to either the coordinator or a router device.

Avoid gaps. If battery sensors are more than 10–15 meters from the nearest router, pairing will succeed but reliability will degrade. Add smart plugs between the coordinator and distant sensors.

Avoid RF-dense areas for coordinator placement. Place the Zigbee coordinator USB stick away from WiFi routers, Bluetooth audio devices, and microwave ovens. A 2-meter USB extension cable to move the stick away from the Proxmox server’s USB ports (which sit near network cards) can significantly improve range.

Check mesh health in Zigbee2MQTT: Dashboard → Map — the network map shows each device and its uplink path to the coordinator. Devices showing high LQI values (≥80) are healthy. Devices showing LQI below 50 need a router device closer to them.

Troubleshooting

Device won’t pair: check that “Permit join” is active in Zigbee2MQTT. For Zigbee devices, pair close to the coordinator. For Z-Wave devices, ensure the distance is under 3 meters during inclusion.

Device pairs but disappears after a few hours: RF interference. Check Zigbee channel overlap with your WiFi channel. Move the USB coordinator away from the server’s WiFi card.

Z-Wave device not responding: check Z-Wave JS UI → Network → Network Health. A device showing dead status needs to be healed (Z-Wave JS UI → Device → Heal Node) or re-paired.

Zigbee2MQTT won’t start: check the MQTT broker is running and the serial port path is correct. Run “Check Configuration” in the add-on before starting.

Wrong entity units or values: Zigbee2MQTT’s device database sometimes maps sensors to wrong units for certain firmware versions. Check the device’s entry at zigbee2mqtt.io/supported-devices for known issues and configuration overrides.

This guide builds on the Home Assistant OS on Proxmox setup guide — start there if HAOS isn’t running yet. For remote access to your Home Assistant from outside the home network, the Tailscale remote access guide covers the HA Tailscale add-on setup. For monitoring all your home services including HA uptime, the Docker Compose starter stack covers Uptime Kuma configuration.