Configuring ZigBee radio for Home Assistant

I use the Zig-a-zig-ah! (AKA ZZH) is a ZigBee radio to connect to lights and sensors within my home.
Instructions for setting up a new ZZH can be found on the electrolama website.
The below instructions are for passing a configured ZZH (or other radio of choice) from the physical port on a Proxmox host, through to the Linux VM hosting Home Assistant.

 

Step 1 - Connect radio and assign USB device to VM

Plug in the radio to an available USB port (Note, to avoid interference it is recommended to use a USB extension to place the radio away from the computer)
From the Proxmox host shell run

lsusb

and we should see the radio listed as "CH340 Serial Converter" or something similar

Take note of the ID number before the device name

Now assign the device to the Home Assistant VM with

qm set <VM ID> -usb0 host=<device ID>

eg

qm set 100 -usb0 host=1a86:7523

Restart the VM and we should see it is connected in the GUI

This can also be achieved through the GUI by choosing Hardware -> Add -> USB Device -> "Use USB Vendor/Device ID" and selecting the device from the list.

Step 2 - Configure device within Home Assistant VM

After restarting the VM run

sudo dmesg

And check for the new device, it may be necessary to filter out some of the output

sudo dmesg | grep USB

Drivers for the CH340 chip in the ZZH have been part of the Linux kernel for some time, so the device should automatically be found.

Step 3 & 4 - Set up Zigbee2MQTT and Mosquitto

In order to make use of ZigBee within home assistant we need 2 docker containers, Zigbee2MQTT (to manage the ZigBee radio and pass messages to an MQTT broker) and Mosquitto (MQTT broker)

Step 3a - Mosquitto

Add the following to docker-compose.yml under services: (do not start it yet)

  mosquitto:
    container_name: mosquitto
    image: eclipse-mosquitto
    restart: unless-stopped
    environment:
      - TZ=Europe/Dublin
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
      - ./mosquitto/log:/mosquitto/log
    ports:
      - 1883:1883
      - 9001:9001  

Before starting the container we need to make some configuration files. Navigate to /mosquitto/config (create folders if not already present) and within this folder make mosquitto.conf

Add the following config to the file

persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
listener 1883

## Authentication ##
#allow_anonymous false
#password_file /mosquitto/config/password.txt

Now start the container

docker-compose up -d

After starting the container, we should enable authentication

docker-compose exec mosquitto mosquitto_passwd -c /mosquitto/config/password.txt <username>

You will the be prompted to enter a password for the new user

Next go back to /mosquitto/config/mosquitto.conf and uncomment the last 2 lines:

persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
listener 1883

## Authentication ##
allow_anonymous false
password_file /mosquitto/config/password.txt

Then restart the container

docker-compose restart mosquitto

Step 3b - Connect Home Assistant to Mosquitto

Open the Home Assistant webpage and go to Settings -> Devices & Services -> Add Integration
Then search for MQTT

Enter the IP address of the Home Assistant server (which is also hosting the MQTT broker), leave the port at 1883, and enter the username and password just created.

Click Submit and if everything is set up right you will get a success message

 

Step 4 - Zigbee2MQTT

Add the following to docker-compose.yml

  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt
    restart: unless-stopped
    environment:
      - TZ=Europe/Dublin
    volumes:
      - ./zigbee2mqtt-data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - 8080:8080
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0

Be sure to change /dev/ttyUSB0 to where the device is connected to

Next create ./zigbee2mqtt-data/configuration.yaml and add the following to it

# Home Assistant integration (MQTT discovery)
homeassistant: true

# allow new devices to join
permit_join: true

# MQTT settings
mqtt:
  # MQTT base topic for zigbee2mqtt MQTT messages
  base_topic: zigbee2mqtt
  # MQTT server URL
  server: mqtt://<MQTT IP address>:1883
  # MQTT server authentication, uncomment if required:
  user: <username>
  password: <password>

# Serial settings
serial:
  # Location of CC2531 USB sniffer
  port: /dev/ttyUSB0
  
advanced
  network_key: GENERATE

Be sure to add the MQTT IP address (this should be the docker0 bridge, 172.17.0.1) and the username and password set earlier

Zigbee2MQTT should now be available at http://<Server IP address>:8080

The when ZigBee devices are added to ZigBee2MQTT they will be added in to Home Assistant automatically.

Sources

https://pve.proxmox.com/wiki/USB_Devices_in_Virtual_Machines
https://www.homeautomationguy.io/docker-tips/configuring-the-mosquitto-mqtt-docker-container-for-use-with-home-assistant/
https://www.zigbee2mqtt.io/guide/installation/01_linux.html#configuring