Repository files navigation

Official Zigbee2MQTT Home Assistant add-on

1. If you don't have an MQTT broker yet; in Home Assistant go toSettings → Add-ons → Add-on store and install theMosquitto broker add-on, then start it.
2. Go back to theAdd-on store, click⋮ → Repositories, fill in
   https://github.com/zigbee2mqtt/hassio-zigbee2mqtt and clickAdd → Close or click theAdd repository button below, clickAdd → Close (You might need to enter theinternal IP address of your Home Assistant instance first).
   
3. 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 thedev 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.
4. Click on the add-on and pressInstall and wait till the add-on is installed.
5. Start the add-on by going toInfo and clickStart
6. Wait a few seconds and pressOPEN WEB UI, you will now see the onboarding page. More information about the onboarding can be foundhere.
7. Fill in the desired settings, for most setups changing the following is enough:
   • Select your adapter underFound Devices, this will configure theCoordinator/Adapter Port/Path andCoordinator/Adapter Type/Stack/Driver.
   • Fill in theClosests WiFi Channel to select the most optimal Zigbee channel.
8. PressSubmit, Zigbee2MQTT will now start, wait a few seconds and refresh the page. You should now see the Zigbee2MQTT frontend.
   • If it shows502: Bad Gateway wait a bit more and refresh the page.
   • If this takes too long (e.g. 2 minutes +) check theLog tab to see what went wrong.
   • In case the add-on fails to start with the following error:USB adapter discovery error (No valid USB adapter found). Specify valid 'adapter' and 'port' in your configuration., we need to fill in theserial section. Format can be foundhere, but skip the initialserial: indent. e.g.:
     

     adapter:zstackport:/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00

     If you don't know the port and you have just one USB device connected to your machine try/dev/ttyACM0 or/dev/ttyUSB0 or/dev/ttyAMA0. Else use theHome Assistant CLI and executeha hardware info to find out.

For more information seethe documentation.

1. Ensure that both environments are running the same version
2. Ensure you canSSH to your Home Assistant OS (NOT to the SSH Add-on)
3. Backup your standalone environmentdata folder (possibly leaving out thelogs/ folder)
4. Start the Zigbee2MQTT HA add-on with a non-existingtty device, to create thedata folder
5. Restore yourdata folder contents into/mnt/data/supervisor/homeassistant/zigbee2mqtt, e.g. viascp -O -P 22222 -i PATHTOUSEDSSHKEY ./data/* root@hass:/mnt/data/supervisor/homeassistant/zigbee2mqtt/
6. Configure your serial port and MQTT settings using the HA add-on configuration UI
7. 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)
8. Start the add-on

The format is based onKeep a Changelog.

All notable changes to this project will be documented in theCHANGELOG.md file.

Version for releases is based onZigbee2MQTT format:X.Y.Z.

Any changes on the add-on that do not require a new version of Zigbee2MQTT will use the format:X.Y.Z-A whereX.Y.Z is fixed on the Zigbee2MQTT release version andA is related to the add-on.

Edge version will not maintain a CHANGELOG and doesn't have a version.

If you find any issues with the add-on, please check theissue 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 theZigbee2MQTT 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 thezigbee2mqtt 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 thezigbee2mqtt container

docker restart $(docker ps | grep zigbee2mqtt | cut -d" " -f 1)

• Refresh the web UI and perform your testing.

• danielwelch
• ciotlosm
• Koenkk