zigbee is a wireless communication standard that many smart device companies like philips hue amazon acara and sonoff use to control their products when you press the button on a hue dimmer switch it sends a wireless signal to your philips hue hub over the zigbee protocol which in turn sends another zigbee signal to your philips hue light bulb telling it to turn on if you want to know more about what zigbee is and how it works i strongly recommend you check out the video i made about this which explains it in more detail i put a link to it in the description below the problem with this though is that even though philips hue and akara use the same zigbee standard to control their products these companies are competitors and all want to sell you their own hubs and ecosystems they also usually need you to sign up to some cloud account to fully utilize their product so yet another company gets access to your data luckily those of us running home assistant can do away with all these different companies hubs and connect many different zigbee products directly to home assistant using one of these a zigbee usb coordinator and some software called zigbee to mqtt in this video i'm going to explain what zigbee2mqtt is and how to install it with home assistant hey home automation guy start the show zigbee to mqtt is a piece of software that lets you control and manage zigbee devices using something called mqtt mqtt is a lightweight messaging protocol that passes messages between devices for example you can have a temperature sensor that tells the mqtt broker how hot it feels every time the temperature changes the mqtt broker records this down and if any other devices want to know what the last temperature reading is it can ask that broker other devices can also subscribe to a topic or device which means that the mqtt broker will tell that device whether a new temperature reading has been received you can also publish messages directly to the broker to tell the devices to do certain things like turn a light on or make it blue mqtt lets you manage potentially hundreds of thousands of network connected devices using a single service if you want more information about how mqtt works then check out the video that i made about this which is linked below but all you really need to know is that mqtt is a scalable and fast way to control lots of smart home tech and it works really well with home assistant zigbee to mqtt acts as a bridge translating messages between your zigbee devices and mqtt which in turn talks to home assistant on the face of it it sounds overly complicated and a lot of people will wonder why don't you just use the default zigbee home automation or zha to manage your devices you can definitely do that and it's what i usually recommend people start out with because it's really easy to use and install in fact i've previously made videos about the differences between zha and zigbee to mqtt which you should definitely check out before you commit to this path ultimately though zha and zigbee to mqtt both do the same thing they both let you use a variety of zigbee devices in-home assistant without needing to buy a different zigbee hub for each new manufacturer that you work with i personally use zigbee to mqtt because it offers a bit more flexibility and it supports a larger variety of zigbee devices if you want to go ahead and use zigbee to mqtt then you will need a working home assistant installation and a usb zigbee coordinator the zigbee to mqtt website lists a bunch of supported usb adapters that they recommend and where to buy them from i would also recommend getting a zigbee usb extension cable so that you can move the zigbee antenna away from the raspberry pi or whatever device you're running home assistant on which keeps it away from any electronic interference the zigbee stick will need to have some special firmware or software installed onto it when i bought my stick i chose the zigbeto mqtt compatible firmware so that it came pre-installed if you get the choice between a router or coordinator firmware then choose coordinator once you've got your usb coordinator plug it into a spare port on the computer that you're running home assistant on you will then also need to install an mqtt broker the one that works best for home assistant is called mosquito with two t's i made an entire video about how to use mqtt with home assistant if you've not already seen that video go and watch it now and follow the steps to install mosquito we'll wait here for you to catch up you can then skip back to this part of the video when you're done by using the chapters that i've created below you can also skip forward to your preferred installation method depending on whether you're using home assistant add-on or a docker container right welcome back now that we have the mqtt broker installed and connected to our home assistant installation we can install the zigbee to mqtt software the first method we'll look at installing is the home assistant add-on this is the most popular way to install it and the way that i would recommend if you're using the home assistant operating system or the supervised version unfortunately zigbee to mqtt is not an official home assistant add-on so we'll need to go and manually add it as a third-party add-on you can find the instructions that i'm going to take you through here listed on the zigbee to mqtt website follow the links to the installation instructions and then to the home assistant add-on section from there we need to go to the zigbee to mqtt add-on github page and copy this url now switch back to home assistant and navigate to the add-on store section once you're there click the three dots in the top right corner and click on repositories paste the url you copied earlier into the bottom area and click add this will add the zigbee to mqtt repository to home assistant and you should now see it listed on the add-on page to install click on the normal one not edge and install it like any other add-on it will probably take quite a while i'd recommend auto-starting it on boot and showing it in the sidebar which will make it easier to get to when you want to add or manage your devices then click the start button to start zigbee to mqtt these log files will tell you of any errors and the configuration can be modified directly on the page here i'd also recommend reading the documentation to familiarize yourself with the add-on and zb2mqtt itself once it's started you can load the zigbee to mqtt interface using the link in the menu it may take a couple of minutes to load up the user interface so if you get an error try again in a few seconds in my setup here the user interface didn't seem to load no matter how long i waited switching back to the log files showed me that zigbee to mqtt had trouble finding the zigbee usb dongle that i plugged in it was looking at the slash dev tty acm 0 which is usually fine for most usb dongles it seems that my usb stick was located somewhere differently to fix this we could open a terminal session to the home assistant server which is really easily done using the terminal add-on in this terminal we can now run a command to list out all of the usb devices that are plugged in and you can see that my usb dongle is on tty usb0 rather than ttyacm0 so we now need to tell zigbee to mqtt where to find our dongle and this can be done by adding a few lines to the configuration of the add-on in the serial section of the configuration tell zigbee to mqtt that the usb device can be found on port dev tty usb0 when you make the change you'll need to restart the add-on hopefully the log files show no more errors and when we now go back to the sidebar it loads up zigbee to mqtt as we expect you now have zigbee to mqtt installed and running we can now take a quick spin through the user interface and then add our first zigbee device directly to home assistant when you first load up the ui you'll see a list of your devices or no devices because you haven't actually added any yet the other place i usually go to is the settings page which lets you configure a bunch of stuff like the zigbee channel that it uses the usb adapter location the mqtt server settings and a bunch of other things that i don't really understand when it comes to adding a new device you need to click the permit join button which will allow you to pair a new zigbee device for a short period of time once that button has been clicked you can pair whatever device you want to add by pressing the pairing button on the device itself or however that particular device needs to be paired the zigbee to mqtt website will often give you tips on how you can pair these devices it's a really good resource i like to flick over to the log files while i'm pairing my devices as it's going to show me whether or not the pairing works properly or not i've noticed that with some devices i often need to do the pairing process a couple of times to get it to work properly once the device is paired i like to give it a proper name so that i can find the right device in the list when i need it a proper naming convention for your smart home devices is crucial any changes that you make to zigbee to mqtt will now be reflected in home assistant as well you can go back to zigbee to mqtt at any time to change any specific device settings but i find i rarely need to do anything at all in this user interface once i've paired the devices and given them a proper name now if you're running the home assistant container version on docker you'll need to install zigbee to mqtt a little bit differently in this example i'm going to be installing the zigbee to mqtt docker container using docker compose and connecting it to home assistant this is going to be a pretty technical process with lots of commands and templates that you need to copy and paste in perfect order to get them to work to make it easier for you i've written a blog post with step-by-step instructions and commands that you can copy and paste so you can set this up in your own time without having to constantly pause the video you can find this blog post linked below firstly we need to find the location of the zigbee usb dongle or we'll end up with the same problem that we had previously when installing the zb2mqtt add-on and it had no idea what device to use i've previously written a blog on how to find this which i've linked in the description as well essentially you need to ssh into your linux computer that has the dongle plugged into it and docker running run the same command that we did before to list out all the usb serial devices and make a note of where your device is registered you can also do this through a terminal session in vs code you should have already previously set up your mqtt broker you've plugged your dongle in and you know where it's located so we can now go to the zigbee2mqtt website and follow the instructions for a docker compose install copy the example docker compose section and then switch to your vs code or whatever you use to edit your docker compose yaml file and paste it into the bottom i keep the name and the image the same as the example but i do update the data volumes to make sure that my zigbee to mqtd data is stored in my slash op directory alongside all my other docker container files i also make sure that the time zone is set correctly too now make sure that your usb dongle is correctly mapped through from your host operating system to the container i want to map my tty usb 0 port from the host to the acm 0 port in the docker container itself my usb dongle is located at slash tty usb 0. so the sample file is already correct for me but you may need to update yours accordingly now save that file and we move on to creating a zigbee to mqtt configuration file if we don't do this step before we start the container it will fail to load up i use vs code to create the zb2mqtt folder and put another folder inside that called data this creates the path that i specified in the volume section of the zigbee to mqtt docker compose entry now let's open a terminal to the linux server and we're going to download a sample zb2mqtt configuration file using the wget command don't worry this command is listed in the companion blog post i spoke about earlier first navigate to the folder you just created and then run the command you can see that this has created a new configuration.yaml file and if we open that up you can see the sample the first thing we want to edit is the home assistant part set that to true so that zigbee to mqtt knows that it's talking to home assistant then set the ip address and the credentials for your mqtt broker and the username that you created when you first set up mosquito you should be able to leave the location of the port alone if you kept the mapping the same in the docker compose file now that we have our docker compose file updated and our zigbee to mqtt configuration created let's navigate back to the slash op directory where our docker compose file lives and run the now familiar docker compose up hyphen d command to create the new container switching back to home assistant we should now see the zb2mqtt docker container running inside portena the last thing that i like to do is edit my homeassistantconfiguration.yaml file to create a sidebar navigation link to the zigbee to mqtt user interface i copy one of the existing iframe panel entries and edit that as a starting point zigbee to mqtt runs on port 8080 and i like to use the zigbee icon save the file and then go back and restart home assistant once it's restarted you should see the xb2mqtt item in the navigation menu and you're done adding devices and everything else should be exactly the same as what i previously showed you in the user interface of the add-on it doesn't matter which way you choose to install zigbee2mqtt once it's installed you use it the exact same way you now have a great zigbee platform upon which you can go and start adding any of your devices all of the links to the videos and blog posts i mentioned are in the description below if you want to know more about how i use home assistant to automate my smart home then make sure you subscribe to the channel so that together we can make your home smarter