Home Assistant

A setup of Home Assistant with Zigbee2MQTT

Installation

This setup assumes, that you have a USB zigbee adapter, that is supported by Zigbee2Mqtt. You can find a list of supported adapters here.

For this guide we will use the ITead Sonoff Zigbee 3.0 USB Dongle Plus V2 model "ZBDongle-E". Make sure to flash it with the coordinator firmware, by following the instructions linked on the Zigbee2Mqtt website.

Pre-Installation

  1. Find your Zigbee Adapter. If it is working correctly, it should be available under /dev/serial/by-id/<device>, e.g.: /dev/serial/by-id/usb-ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_20221101103853-if00.

  2. Create config/zigbee2mqtt/configuration.yaml and add the following:

    config/zigbee2mqtt/configuration.yaml
    permit_join: true
    mqtt:
      base_topic: zigbee2mqtt
      server: mqtt://mqtt:1883
      user: mqtt
      password: <password>
      include_device_information: true
    homeassistant: true
    serial:
      adapter: ezsp
      port: >-
        <z2m_device>
    frontend:
      host: 0.0.0.0
      port: 8090
    advanced:
      network_key: GENERATE
      homeassistant_legacy_entity_attributes: false
      legacy_api: false
      legacy_availability_payload: false
    device_options:
      legacy: false
    

    Make sure to replace <z2m-device> by the path /dev/serial/by-id/<device> of your adapter. Also replace the <password> by a password of your choice. You will need it later for the homeassistant setup.

  3. Create the docker-compose.yml file and add the following

    docker-compose.yml
    version: '3.8'
    services:
      mqtt:
        image: eclipse-mosquitto:2.0
        container_name: mqtt
        restart: unless-stopped
        volumes:
          - "./data/mosquitto:/mosquitto"
        ports:
          - "1883:1883"
          - "9001:9001"
        command: "mosquitto -c /mosquitto-no-auth.conf"
    
      zigbee2mqtt:
        container_name: zigbee2mqtt
        restart: unless-stopped
        image: koenkk/zigbee2mqtt
        volumes:
          - ./data/zigbee2mqtt:/app/data
          - ./config/zigbee2mqtt/configuration.yaml:/app/data/configuration.yaml
          - /run/udev:/run/udev:ro
        ports:
          - 8090:8080
        environment:
          - TZ=${TZ}
        devices:
          - ${Z2M_DEVICE}:${Z2M_DEVICE}
        labels:
          traefik.enable: true
          traefik.http.routers.z2m.entrypoints: websecure
          traefik.http.routers.z2m.middlewares: secured@file
          traefik.http.routers.z2m.rule: Host(`z2m.${SITE}`)
          traefik.http.services.z2m.loadbalancer.server.port: 8090
      homeassistant:
        container_name: homeassistant
        image: "ghcr.io/home-assistant/home-assistant:stable"
        volumes:
          - ./config/homeassistant:/config
          - /etc/localtime:/etc/localtime:ro
        restart: unless-stopped
        privileged: true
        environment:
          PUID: ${PUID}
          GUID: ${PGID}
        labels:
          traefik.enable: true
          traefik.http.routers.homeassistant.entrypoints: websecure
          traefik.http.routers.homeassistant.rule: Host(`ha.${SITE}`) && !Path(`/api/prometheus`)
          traefik.http.services.homeassistant.loadbalancer.server.port: 8123
    

    Make sure to add Z2M_DEVICE=/dev/serial/by-id/<device> in your .env.

  4. Start the applications by running docker compose up -d

Zigbee2MQTT setup

After you have installed everything as described no the page before, you should be able to reach the zigbee2mqtt frontend on https://z2m.<site>.

You can now add devices by searching for the model on the Zigbee2MQTT Website and following the given instructions.


Note: After you have added all your devices, set permit_join to false in config/zigbee2mqtt/configuration.yaml. If you want to add devices later, you can still do so via the frontend.


Updating devices

You can update the firmware of most of your devices by going to the OTA tab on the frontend. This probably takes quite some time and has a tendency to get stuck. If that happens, simply restart the Zigbee2MQTT container and restart the update. It should continue where it has last stopped.

Home Assistant setup

You can change a lot of settings in config/homeassistant/configuration.yaml. For the beginning it should look something like this:

config/homeassistant/configuration.yaml
# Loads default set of integrations. Do not remove.
default_config:

# Load frontend themes from the themes folder
frontend:
  themes: !include_dir_merge_named themes

# Text to speech
tts:
  - platform: google_translate

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

http:
  server_port: 8123
  ip_ban_enabled: false
  login_attempts_threshold: 3
  use_x_forwarded_for: true
  trusted_proxies:
    - 192.168.0.0/24  # Local Lan
    - 172.42.1.0/24  # Docker network

homeassistant:
  external_url: "https://ha.<SITE>" # note no port number
  internal_url: "http://192.168.0.2:8123" # internal ip address of my HA with port number

Make sure to replace your network settings accordingly.

Addind your devices

You can add devices, that you have setup in Zigbee2MQTT by using the Home Assistant MQTT-Integration.

Adding alexa support

Add the following to config/homeassistant/configuration.yaml:

alexa:
  smart_home:

Then, follow the instructions on the Home Assistant website.