Home Assistant Add-on: Zigbee2mqtt

Run Zigbee2mqtt as a Home Assistant Add-on

Installation

Add the repository URL under Supervisor → Add-on store → ⋮ → Manage add-on repositories:

https://github.com/danielwelch/hassio-zigbee2mqtt

The repository includes two add-ons:

• zigbee2mqtt is a stable release that tracks the released versions of zigbee2mqtt.
• zigbee2mqtt-edge tracks the dev branch of zigbee2mqtt, so you can install the edge version if there are features or fixes in the dev branch that are not yet released.

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.

Adding Support for New Devices

If you are interested in adding support for new devices to zigbee2mqtt you will need to use one of the methods below to allow you to change the required files.

Using devices.js override in add-on

Set the optional, top-level zigbee_shepherd_devices option to true in your configuration.

zigbee_shepherd_devices: true

When set, the add-on will scan your data_path for a devices.js file, and will run zigbee2mqtt using this custom file.

⚠️ If you want to make sure that the version of devices.js fits your add-on, make sure to follow the steps below:

1. Identify your stable zigbee2mqtt version from the add-on (ex. 1.14.3)
2. Navigate to https://github.com/Koenkk/zigbee2mqtt/tags and find tag (ex. 1.14.3)
3. Click on the commit hash (ex. f8066e8) and then browse files button
4. Find package.json and identify zigbee-herdsman-converters version (ex. 12.0.161)
5. Navigate to https://github.com/Koenkk/zigbee-herdsman-converters/tags and find tag (ex. 12.0.161)
6. Click on the commit hash (ex. 3a5abc7) and then browse files button
7. Find devices.js file and download it (use raw version)

Using external_converters

Using external_converters option you will have more flexibility to add support but also allow you to maintain a DIY device support. Follow the documentation to get started.

If you are searching to edit specific files, please find the Line reference in the example converter where to make your changes:

• fromZigbee.js: https://github.com/Koenkk/zigbee2mqtt.io/blob/master/docs/externalConvertersExample/dummy-converter.js#L15
• homeassistant.js: https://github.com/Koenkk/zigbee2mqtt.io/blob/master/docs/externalConvertersExample/dummy-converter.js#L66

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

• danielwelch
• ciotlosm
• Koenkk for zigbee2mqtt