Installing Z2M

Instead of installing Z2M as a separate docker component, you should be able to also install it using HA.

See this YouTube video of Tom's Smart Home series for more details.

However, when you go to the Apps section (formerly known as Add-ons) and search for Z2M, you won't find it.  The reason for this is that Z2M is a separate project, so we have to add that project's repository to HA.

To install Z2M do:

• copy the link of the GitHub repository of hassio_zigbee2mqtt: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

• go to Settings -> Apps -> Install app -> ⋮ -> Repositories -> Add

• paste the link you copied into the URL field and click Add
  What happens behind the scene:
  Once you click the Add button, Home Assistant will get the Github repository in the background and place it in (in my case at least with the Armbian Home Automation distro) in /var/lib/homeassistant/apps/git/<some_commit_hash>

• check if the new repository has been added to the list of repositories

Once the URL is listed, go back to the App store (click the <- key in the left upper corner, next to Repositories)

If you then go back to the App store and search for Zigbee2MQTT, you will see 3 versions of Z2M:

• Zigbee2MQTT <= that's the one we need

• Zigbee2MQTT Edge (latest and maybe greatest version of Z2M)

• Zigbee2MQTT Proxy (seems you can run Z2M externally than, whatever that means), never done that...

If you click on Zigbee2MQTT, you will be able to install it in HA.

Install the application, but don't start it yet!

Once Z2M is installed, the next step is to set up an MQTT broker.  See next section.

This means that all MQTT messages also will be sent to that very specific MQTT broker and there I can do whatever I want with the MQTT messages.  I can consume them, I can forward them to another MQTT broker, I can... do whatever I want (well, almost...).

Once Z2M is installed, configure it first.

Z2M needs an MQTT broker, be it an internal one or an external one.

Using the internal Home Assistant broker

If you want to use an internal MQTT broker, you have to install the Mosquitto broker which is part of Home Assistant.  

To do this, do:

• select Settings -> Devices & services -> Add integration

• In the search field of the popup with title Select brand, type MQTT

• select MQTT

• select again MQTT in the next popup window (with the > token at the right side of the popup)

  • or select to use the official Mosquitto Broker app by Home Assistant

  • or select to manually enter the MQTT broker connection details

The difference between the two is that in the former case all the info is pre-filled (e.g. core-mosquitto is the broker and no username or password is given) and in the latter case you have to provide the hostname or IP address of the broker.

Using an external broker can come in handy if you don't want to use the Home Assistant broker but your own already exisiting broker running on another device.
The only thing you have to give, is the IP address of that other device.

Using the external Home Assistant broker

For this to be arranged, you then don't need the Mosquitto broker app.  The only thing you have to do is to open the Z2M application and select the Configuration tab.

In there, expand the mqtt section and add the following in the server field:

mqtt://<IP_address_of_external_MQTT_broker>:1883

The rest can be left untouched.

Once this is done, this means that all MQTT messages will be sent to that very specific MQTT broker and there I can do whatever I want with the MQTT messages. 
I can consume them, I can forward them to another MQTT broker, I can... do whatever I want (well, almost...).

Once Z2M is installed, configure it first.

To do this, select the Configuration tab in the Z2M installation environment.  To get there, select Settings -> Apps -> and click the Zigbee2MQTT tile.

You should see the data path already filled in.  Most probably, this will be /config/zigbee2mqtt.

However, next to this, you also need the serial parameters.  Since we're using the Sonoff Zigbee 3.0 USB Dongle Plus we're working serial.

Click on serial to expand the section.  There, we need 3 parameters:

• port

• adapter

• baudrate

To find the port, go back to Settings -> System -> Hardware and select the tab System hardware.  In the search bar, start typing the brand name of the dongle you're using as your Zigbee dongle.  In my case this is Sonoff, so I'm starting to type Sonoff.

Once this is done, you see (most likely) something like ttyUSB0.  Click on that and a popup will open.

The first section of this popup is called DEVLINKS and it will show you different representations of the whole path that has been assigned to ttyUSB0 (well, in fact /dev/ttyUSB0).

Copy the first line (the line that contains by-id in the path), because that's what we need to fill in into the serial section when configuring Z2M.  In my case this is:

/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_4028ea51b0a0ef1199df9fa361ce3355-if00-port0

Next item to fill in, is the adapter.  Depending on the type of Zigbee dongle, the chipset used will be from TI or from Silicon Labs.

In case the chipset is TI, you have to fill in zstack.  In case the chipset is Silicon Labs, you have to fill in ember.  Different chips have different adaptors, so it's important to choose the correct one.

So, in the end we have:

• Port:
  /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_4028ea51b0a0ef1199df9fa361ce3355-if00-port0

• Adapter:
  zstack

• Baudrate:
  115200

Once this is done, make sure the following items in the Info tab are set under the Controls section:

• Start on boot

• Watchdog

• Show in sidebar

IP address: http://<HA_ip_address>:8080

There's a whole AI chat I did about installing Home Assistant and also Zigbee2MQTT the docker way.  It's quite complex, I had lots of issues...  In short: not advisable.  At least not for me since Armbian now has a nice Home Assistant image in which I can add Zigbee2MQTT as an app without any issues.  

In the past the Add-ons (now called Apps) were not present in a none-original Home Assistant installation since the superviser was not present.  The only possibility you had was through Docker.

But this is not needed anymore now.  If you take the Armbian Home Assistant image the Apps section is present and you can add extra apps which are not in the default app repository by adding the repository link of the app and you're done.