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.