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
-
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
. -
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. -
Create the
docker-compose.yml
file and add the followingdocker-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
. -
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.