Configuration and other files to create a new Home Assistant installation, using Zigbee2MQTT (and Eclipse Mosquitto) to monitor and control Zigbee devices. To run, you need a suitable hardware platform (x86 and arm will do) and a Zigbee adapter attached to it. See Zigbee2MQTT's recommended adapters for suitable devices.
- Clone this repository to a suitable machine and change into the created directory (
homeassistant-zigbee2mqtt) - Create an
.envfile in that directory with the required environment variable names and values (see below) - Use
docker compose configto validate the compose file and variable substitution - Use
docker compose up -dto start the stack - After some time, open a browser and point it to http://<hostname or -ip>:80/ to open Home Assistant UI and start onboarding
- at the last step of the onboarding dialog, click on the MQTT symbol to configure the connection to mosquitto (screenshot)
- in the modal subdialog, simply enter
mosquittoas MQTT server name and submit (screenshot)
The stack requires configuration by environment variables. Easiest solution is to create a file named .env next to the docker compose file. See Docker's documentation on .env-files for details.
You may use the provided script env.sh to gather the required information in a usable format. The following command will create (overwrite) the .env file from the gathered information:
sh ./env.sh > .env
Either way the following environment variables must be defined:
| Name | Purpose | Example |
|---|---|---|
| SERIAL_DEVICE | Path of the Zigbee adapter serial device | /dev/serial/by-id/usb-...-if00-port0 |
| TZ | Local timezone | Europe/Berlin |
| ZIGBEE2MQTT_CONFIG_ADVANCED_NETWORK_KEY | Zigbee network key as array of bytes (decimal notation) | [ 1, 3, 5, 7, 9, 11, 13, 15, 0, 2, 4, 6, 8, 10, 12, 13 ] |
Hint: On Linux, you can create the following command to create a new, random network key: shuf -i0-255 -n16 | paste -sd ','. Changing the network key requires re-pairing of all Zigbee devices!
- the Home Assistant UI is mapped to port 80 on the host, no proxy is in-place
- the Home Assistant container is not using the host's network, discovery of integrations in Home Assistant will not work.
- the Zigbee2MQTT frontend is disabled
- the Mosquitto MQTT service is attached to the stack's internal network only
The project focusses on ease-of-use and does not provide any additional security measures. Use in a secure, controlled environment only.