- If you don't have an MQTT broker yet; in Home Assistant go to Settings → Add-ons → Add-on store and install the Mosquitto broker addon, then start it.
- Go back to the Add-on store, click ⋮ → Repositories, fill in
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
and click Add → Close or click the Add repository button below, click Add → Close (You might need to enter the internal IP address of your Home Assistant instance first).
- The repository includes two add-ons:
- Zigbee2MQTT is the stable release that tracks the released versions of Zigbee2MQTT. (recommended for most users)
- Zigbee2MQTT Edge tracks the
dev
branch of Zigbee2MQTT such that you can install the edge version if there are features or fixes in the Zigbee2MQTT dev branch that are not yet released.
- Click on the addon and press Install and wait till the addon is installed.
- Click on Configuration
- If you are not using the Mosquitto broker addon fill in your MQTT details (leave empty when using the Mosquitto broker addon). Format can be found here, but skip the initial
mqtt:
indent. e.g.:
Note: If theserver: mqtt://localhost:1883 user: my_user password: "my_password"
password
includes certain special characters (reserved by yaml specification), the enclosing quotes are required. So it is recommended to always quote it when in doubt. - Fill in the serial details (e.g. port of your USB coordinator). Format can be found here, but skip the initial
serial:
indent. e.g.:
port: /dev/ttyUSB0
- If you don't know the port and you have just one USB device connected to your machine try
/dev/ttyUSB0
. Else use the Home Assistant CLI and executeha hardware info
to find out. - Click Save
- Tip: it is possible to refer to variables in the Home Assistant
secrets.yaml
file (not the Zigbee2MQTT one!) by using e.g.password: '!secret mqtt_pass'
- If you are not using the Mosquitto broker addon fill in your MQTT details (leave empty when using the Mosquitto broker addon). Format can be found here, but skip the initial
- Start the addon by going to Info and click Start
- Wait till Zigbee2MQTT starts and press OPEN WEB UI to verify Zigbee2MQTT started correctly.
- If it shows
502: Bad Gateway
wait a bit more and refresh the page. - If this takes too long (e.g. 2 minutes +) check the Log tab to see what went wrong.
- If it shows
For more information see the documentation.
- Ensure that both environments are running the same version
- Ensure you can SSH to your Home Assistant OS (NOT to the SSH Addon)
- Backup your standalone environment
data
folder (possibly leaving out thelogs/
folder) - Start the Zigbee2MQTT HA addon with a non-existing
tty
device, to create thedata
folder - Restore your
data
folder contents into/mnt/data/supervisor/homeassistant/zigbee2mqtt
, e.g. viascp -O -P 22222 -i PATHTOUSEDSSHKEY ./data/* root@hass:/mnt/data/supervisor/homeassistant/zigbee2mqtt/
- Configure your serial port and MQTT settings using the HA addon configuration UI
- Edit the
/usr/share/hassio/homeassistant/zigbee2mqtt/configuration.yaml
file:- Ensure that the serial port section matches the one configured with the UI
- Remove any irrelevant sections from the config (e.g.
mqtt
(if not needed),advanced/log_syslog
,frontend
)
- Start the add-on
The format is based on Keep a Changelog.
All notable changes to this project will be documented in the CHANGELOG.md file.
Version for releases is based on Zigbee2MQTT format: X.Y.Z
.
Any changes on the addon that do not require a new version of Zigbee2MQTT will use the format: X.Y.Z-A
where X.Y.Z
is fixed on the Zigbee2MQTT release version and A
is related to the addon.
Edge version will not maintain a CHANGELOG and doesn't have a version.
If you find any issues with the add-on, please check the issue tracker for similar issues before creating one. If your issue is regarding specific devices or, more generally, an issue that arises after Zigbee2MQTT has successfully started, it should likely be reported in the Zigbee2MQTT issue tracker.
Feel free to create a PR for fixes and enhancements.
If you're submitting a PR and wish to test it locally:
- Gain root access to your Home Assistant installation
- In the Add-on Settings, Ensure "Watchdog" is turned off so the container isn't automatically restarted when it's stopped via the CLI
- Enter the
zigbee2mqtt
container interactively.
docker exec -it $(docker ps | grep zigbee2mqtt | cut -d" " -f 1) /bin/sh
- Edit the file you'd like to test & save.
vi node_modules/zigbee-herdsman-converters/converters/toZigbee.js
- Back on the Home Assistant installation, restart the
zigbee2mqtt
container
docker restart $(docker ps | grep zigbee2mqtt | cut -d" " -f 1)
- Refresh the web UI and perform your testing.