/hassio-zigbee2mqtt

Official Zigbee2MQTT Home Assistant add-on

Primary LanguageShellApache License 2.0Apache-2.0



Official Zigbee2MQTT Home Assistant addon

Installation

  1. If you don't have a MQTT broker yet; in Home Assistant go to Settings → Add-ons → Add-on store and install the Mosquitto broker addon.
  2. Go back to the Add-on store, click ⋮ → Repositories, fill in
    https://github.com/zigbee2mqtt/hassio-zigbee2mqtt and click Add → Close.
  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 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.
  4. Click on the addon and press Install and wait till the addon is installed.
  5. Click on Configuration
    • If you are using the Mosquitto broker addon, you should add base_topic: zigbee2mqtt to the mqtt configuration field or the corresponding YAML block if editting in raw YAML.
    • If you are not using the Mosquitto broker addon fill in your MQTT details. Format can be found here, but skip the initial mqtt: YAML key if using the configuration UI and typing into the mqtt field. e.g.: 
      server: mqtt://localhost:1883
user: my_user
password: my_password
    • 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 execute ha 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'
  6. Start the addon by going to Info and click Start
  7. 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.

For more information see the documentation.

Changelog

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.

Issues

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.

Credits