Home Assistant 101: How to Integrate MQTT Devices

today I'll cover how to take a device that offers mqtt and integrate that device into home assistant when a native integration isn't available with this type of integration you can not only get data back from the device to show on dashboards but usually control some features of that device and use it in your automations and scripts I'll explain and show the step-by-step process on how you can add these devices to your home assistant even if you are somewhat new to mqtt [Music] hi and welcome to resin cam Tech about a year or so ago I did a video on adding mqtt to your own DIY Electronics projects so you could integrate those into home assistant now while that video was primarily targeted towards those of you who are writing your own code like Arduino or python it did include a short section on the steps needed to add those devices to home assistant a number of you reached out to to me and ask if I would go into a little bit more detail on the home assistant integration side because you're not writing your own code but you're using Code or projects developed by others that have mqtt so that's what I'm going to cover in today's video but there are a few prerequisite prequisites however there are a few prerequisites that you need to be aware of you need to at least have a basic understanding of mqtt and how it works things like topics and payloads Publishing and subscribing all that is new to you you might quickly check out the video that I'm going to post here and don't worry there'll be a link down in the video description if you miss it here and at least watch the first part of that that describes some of the Core Concepts of mqtt and how it works now obviously you're going to need an mqtt broker the home assistant add-on is fine and you're going to need to have mqtt integrated and configured in home assistant note you don't need to do this manual process if there is an integration in home assistant tasmota and things like wed are perfect examples not too far in the past you actually had to do all of your manual configuration for mqtt in yaml now you can just use the Integrations and don't need to do this manual configuration but this is needed for things that have mqtt that don't have a native integration and home assistant and don't worry about trying to capture all the yaml that I show on the screen there will be a link down in the video description to a Blog that will have copies of all this and some additional examples and yes I did say yaml unfortunately as of the time of this recording it is required to use yaml to integrate these types of mqtt devices into home assistant but don't worry I'm going to go through it step by step to try to make the process easy to understand and easy to replicate with that let's get started if this is your first time integrating custom mqtt devices into home assistant and unless you're using a split configuration or home assistant packages we'll be working in the main configuration. yaml file now if you are using a split configuration or packages you probably already know how to set this part up so you can use the links down below to skip this section if you have no idea what I'm talking about when I say a split configuration or home assistant packages well then hang around because this section is for you in your main configuration. yaml file it should start out with a home assistant tag and then have specific information for your home assistant install underneath that somewhere in your configuration file you should see some Integrations listed things like lights switches sensors you may not have all of these but you'll probably have one or two and it could include things like climate or cover where you might have done some other custom Integrations and if you do have any custom Integrations defined such as a custom light or a custom switch they're going to appear underneath the integration section so all of your custom light Integrations will appear underneath light switches under switch so on and so forth now as you can imagine if you start to have a lot of these it can make for a very long and hardto manage configuration. yo file and that's where this split configuration comes into play you can create separate yaml files for say everything like your lights and your switches and then you can include those in your main configuration. file again this really isn't about split configuration there are a lot of videos out there on how to do that or let me know down in the comments if you'd like to see me make a video on how to do a split configuration but back to our mqtt now only about a year ago actually exactly a year ago starting with 20222 release of Home assistant a change was made to mqtt prior to that mqtt was a platform so if I needed to Define an mqtt light I would put it underneath my light integration with a platform of mqtt but they made a change with 20222 which made a whole lot of work for a lot of us who had literally hundreds of mqtt Integrations but that's a subject for another video but starting with that release of Home assistant mqtt is now its own integration so to add mqtt entities into home assistant we need to have this mqtt top level integration tag in our configuration. file just like lights and switches and sensors all of our mqtt custom Integrations and entities are going to be defined under the mqtt tag and again as you imagine this could make for a very long configuration. yo file if you start having a lot of mqtt entities so just like the other ones you can actually use an include tag and put all of your mqtt entities and definitions into its own yl file regardless of whether using a split configuration doing your configuration. file or even in packages how you handle things under this primary mqtt integration tag are the same so underneath the mqtt tag we then Define the actual integration or device type like a light a sensor or a switch again it's a little confusing to me why this is better than having one light with a platform of mqtt but I'm sure they had their reasons this is the way that it is so in this case I have an mqtt light so I have a light integration or device type and underneath that I'm going to actually Define the mqtt light so you might ask okay now I have an mqtt sensor I need to add how do I do that you might think you do mqtt with a sensor like this nope it doesn't work like that remember there is only one mqtt section across all of your configuration unless you're using packages so if you have mqtt repeated anywhere across all of your configuration files you're going to get a configuration error so all of your mqtt entities need to be defined underneath a single mqtt integration tag all right so let's say I've got my light defined now I need to define a second mqtt light from a completely different device if you do it like this adding a second light nope it's not like that either just like the base Integrations all of your mqtt lights need to be defined underneath the light tag it is a little bit confusing but as you start to add a lot of mqtt entities your configuration is going to look something like this you're going to have one mqtt tag at the top then you're going to break that out by the different types of mqtt entities light with all of your lights sensor with all of your sensors switch covers so on it doesn't matter if these are from the same or different devices they all get grouped together underneath the appropriate tag okay with that let's go ahead and start taking a look at how you actually defined the entities for mqtt devices so before we can start actually creating the Integrations themselves you are going to need to know the mqtt topics and the types and formats of payloads that the device supports usually you can find that in the documentation that comes with the device or maybe it's in a GitHub repost somewhere if you're using a GitHub code or a project developed by somebody else but somewhere there should be a list of mqtt topics and payloads once you have that in hand you're ready to start the Integrations now home assistant supports a long list of different types of mqtt devices and entities as you can see here and occasionally new ones are even added to the list now it would be time prohibitive for me to try to cover each and every one of these types of mqtt entities so today I'm going to focus on three of the most common than the ones you're most likely to use in your own Integrations and those are sensors switches and lights but even within those we take a look at sensor here you're going to see a long list of available options again it would be time prohibiting for me to try to describe every single one of these so I'm going to show the basic integration steps with the hopes that once you have a little bit better understanding you can come back to this documentation and add additional options as you need them we're going to start out by taking a look at how to create a basic mqtt sensor to create an mqtt sensor first need to locate the mqtt integration in our configuration file underneath that we're going to look for a sensor section or sensor tag now it's the very first time you've done this one or the other of these may not exist if not you need to add them for the first time I'm going to go ahead and pop in my documentation here so that I can see what the actual topics and expected payloads are from this device so the first thing I need to do is I just need to give this device a name I'm just going to call this Matrix mode next thing I need to do is I need to list the state topic and what we mean by a state topic and you'll see how this is different from a command Topic in a little bit but a state topic is something that home assistant subscribes to that means it's going to receive data into this entity and for this one right on the documentation we can see that our state topic is stat Matrix mode that's all we need to do and now all I have to do is actually just save my configuration file I come over to my yaml tab underneath my developer tools it's always a good idea to check your configuration as long as you don't get any errors there now if you added mqtt integration for the very first time you do need to do a full restart of Home assistant but you only need to do that one time once the mqtt integration is there from that point forward you can come down here and just reload your manually configured mqtt entities as long as you get a green check mark you're good to go now we can come over to our states tab do a search for our new sensor and there you can see it in home assistant now if your device does not publish its states with retained Flags then the initial State might be unavailable or unknown Until That device actually publishes an mqtt message on this topic but anytime a new message on this topic gets published it will automatically update this sensor in home assistant so back in my configuration file I'm going to go ahead and create sensors for these other two that shows us being available in the documentation so again I do it in the same exact way I give it a name I give it the state topic right out of the documentation and you can see I've added a couple of optional items to these too for the Matrix brightness I've gone ahead and I've defined an icon and for my temperature I've given it both a friendly name and a unit of measure again those are optional and there are a lot of other things that you can add to the sensor and that is in the documentation but that's really all we need now I can go back out and I can reload my manually configured mqtt entities I don't need to restart home assistant and I will now have three sensors available and here you see I've added all three of those sensors directly onto my home assistant dashboard I'm showing my Matrix mode the current brightness and the current temperature once they're in home assistant as sensors they can be treated just like any other sensor regardless of whether it was mqtt or not now the the fact that these are sensors means I can't control anything on the clock because I've only subscribed I'm only receiving data from the mqtt device we're going to talk in a minute about how we publish data back to the mqtt device for controlling it and again anytime a new mqtt message is published by the clock say if something were to change like the brightness or even the mode it automatically updates the sensor in home assistant before I move on to talking about the next type of mqtt entity I do need to talk about payloads for just a second in this particular example it's very simple because the device is publishing a single value to the payload for a given topic but not all devices do that some devices and a lot of mqtt devices will publish multiple values in a single payload to a single topic and they do that by formatting the payload in Json so here's an example actually an energy monitoring smart plug that I have in my home we take a look at the mq TT this is a topic that it has of waser state and here's the actual payload that gets published it contains all these values in a single payload and here's another example with a topic of washer sensor again multiple values published in a single payload so how do we extract out a single value to place into a sensor and home assistant well let's go back to the editor and take a look right back over here in the editor let's go ahead and pop up our documentation and for this first sensor let's say we want to create one that shows the load average for our washer so again still underneath our sensor tag of our mqtt integration just like any other one we need to go ahead and give it an entity name and we need to indicate the state Topic in this case once again it is Telly for Telemetry washer state but now to extract a single value out of here we're going to use something called a value template value template is going to use a template in home assistant and a template in home assistant starts out with two curly braces the value that we want to be extracted and we close it with two curly braces now what goes in here the nice thing is there's a nice function available that allows us to extract a single value out of a Json file and that is just Valore Json with a DOT and then the value that we want to extract out of our Json payload so in this case it's load AVG or load average do note that with most mqt Brokers capitalization is important so uppercase State versus lowercase state are two different topics the same way here for the value we're trying to extract so now what will happen is this particular sensor will have the value in this case of 19 because it's able to extract that data out of the Json file let's try a couple more examples and in this case let's pull the the wats the volts and the current out of the energy reading by creating three separate sensors so let's start out with the Watts and once again we're just going to give this a name in this case our state topic is a little bit different it's from the right hand side of the documentation there it's Telly washer sensor and we need the value template now one thing to note here if you look at the Json file for that notice that all of the energy readings are nested or they're a subobject the dot notation we showed up here only pull out the top level values we have a situation where we have an object nested like this then we have to use a slightly different value template and it looks like this so in our value Json function we go ahead and give it the top level object name or key name and then we can use a DOT notation to pull any sub value out of that so in this case since power or a watts are listed underneath energy our value template looks like this now for our volts and amps we can just repeat that same process except notice that in this case under our energy key or our energy tag in our Json file we're now just going to pull out voltage for our washer volt sensor and current for our washer amp sensor Json can be a little bit confusing and do note that there are other types of payloads like XML or even something like semicolon limited that some devices may use but you would repeat this same kind of process to be to extract out the particular single value that you want for your mqtt sensor and sometimes it helps to have a utility that you can look at the mqtt values and see exactly what the payload looks like having utility is invaluable especially if you're going to be working quite a bit with mqtt personally I use mqtt Explorer it is a free open- source download and there are versions available for Windows Windows Mac and Linux mqtt Explorer allows you to connect directly to your mqtt broker whether that has the home assistant add-on or a standalone broker so once you connect to your broker you're now able to see all of the mqtt topics messages and payloads that are going in and out of the broker so for example here's the clock we just looked at for creating our sensors we can see the mode and brightness listed right here as well as temperature so let's us know exactly what payload is being sent by the device this can be really useful for troubleshooting because you may be getting a payload slightly different than what you expect and similarly you can also check the messages that you are publishing from home assistant in fact you can actually publish messages directly from here although you can do that in home assistant as well but it's a really handy tool to have especially for troubleshooting mqtt topics and payloads I'll leave a link to this down in the video description now let's move on and take a look at another type of mqtt entity and that's the switch now switches are interesting because the switch shows the current state whether something is off or on but unlike just a sensor it actually allows us to change that state we can turn something off or on so these are actually mqtt switches from my own home assistant but let's take a look and see how we create these in our yo configuration back over here in our configuration file we see where we have all of our previously defined sensors but now to add mqtt switches we need to create a switch section so if a switch doesn't already exist under your mqtt you need to add it and we will Define all of our switches underneath this I'm going to go ahead and just clear all this out just to make it a little bit easier to read so we'll say all of our sensors were defined there and now we're ready to Define our switches so once again let's bring up our documentation and similar to our sensors we start out with the name name but in this case we're going to use a command topic now the command topic is what home assistant is going to use to publish an mqtt message back to the device and looking at this first one for the LEDs we can see our topic is command a clock LEDs now technically this is the only thing that's required by default if a separate State topic isn't listed here home assistant will use whatever is published on the command topic to also indicate the state of the switch device and it also defaults to using a payload of offer on which is what we have here but if your device does offer a separate State topic I highly recommend that you put that in here this one actually has a different state topic otherwise depending on whether that command topic is retained or not you can get ghosting and again go back and watch that initial mqtt video if you want to know more about retained flags and ghosting but in this case we do have a separate State topic so we're going to have a command topic we're going to publish and then we're going to have a state topic where we're going to receive the current state of this switch now if your states are being published in a Json format like before we can easily add a value template here just like we did with the sensors to extract that value for our state payload now there are a couple other things I like to include here even though they are currently the default values that not included I do like to include my payload on and payload off in this case that is what home assistant is going to publish when you change the switch in the dashboard or through home assistant and in this case since I don't have anything separate it's also going to use those values to determine when the state is off or on and the retain flag down there has to do with publishing that uh command again it's not really needed here because the default value if you don't include it is false so again just a review the command topic is what home assistant is going to use to publish a value to the mqtt device it's going to receive the current state of that entity back on the state topic and in this case it's using a payload of off and on not only for publishing the command but also to determine the current state of the device so let's change the documentation up here just a bit to see how we handle situations where the payload isn't the standard value of on or off so now for our second switch which is the sweep we can see from this updated documentation we now have a command payload of one or zero to turn the switch off or on or off and we have a state payload of yes or no to indicate the state of the switch as being on or off so how do we do that well we're going to start out just like we did before by putting in a name and the current command and state topics but now for issuing this command our payload the expected payload for the command topic is no longer on or off so instead we need to specify what it is from the documentation in this case we send a payload of one to turn the switch on and a payload of zero to turn that switch back off but what about the state before I said that if it would use this payload on or off to compare to the state payload to determine the current state of the switch well in this case the payload is yes or no it doesn't match the same payload that we sent for the command so in that case we just specify payloads for the on and off of the state so in this case we compare the state payload to yes for on and no for off and again the retain flag defaults to false so it really isn't necessary here I just like to include it and for our third switch which is the blink again we use the appropriate command and state topics in this case for our Command topic we see we've got a payload of on which is yep and a payload of off which is nope and for our state topic payloads we see that is either blinking for on or solid for off that's really all there is to it now there's a lot of other options available things like availability topics that let you know whether the device is online or offline and you can find that in the documentation on mqtt switches but this is pretty much the basic steps needed to create a switch save your configuration file go out and reload your manual mqtt entities from the developer tools and then you would have three switches available in home assistant so now let's take a look at the final type of mqtt device I'm going to cover in this video and that's the mqtt light now lights are very similar to switches in the fact that you can see the state and you can toggle the state just like with a switch but mqtt lights make a number of additional topics available things such as brightness and even things like color color temperature and effects if your device supports it and and makes those topics available in mqtt in fact mqtt lights and switches are so similar in many cases they're interchangeable if you have a smart bulb and it's just a simple onoff bulb doesn't have any additional features you can Define that as a switch in a similar manner if you have something like a dimmer switch where you need to be able to set a brightness or a dimmer level you can Define that switch as an mqtt light and that will make things like brightness topics available in fact what I'm going to show here is my mqtt light setup for an in the--all dimmer switch he back over in our configuration file and I've gone ahead and remov the switch definitions here just to make it a little bit easier to see but all of your switches would still be defined under switch but an anonym qtt light we now need to add a light section and all of our lights will be defined underneath this tag I'll go ahead and bring up the documentation so we can see the topics and we start out exactly like a switch we give it a name the command and the state topics now for this particular State topics you notice it says the payload is in Json format that means just like we did with the sensor we need to actually add a value template here now to get the right Json key we could use something like mqtt Explorer and bring up an actual payload and see what that looks like fortunately the documentation here was kind enough to tell us exactly what that Json tag is so we just add our value template in this case our state is being orted back in the power key of the Json and now we can add our payload and our states off and on but in this case again they're the default values so we really wouldn't have to include those but at this point everything is basically identical to a switch but now we want to add those topics to be able to control the brightness fortunately mqtt lights have topics available for brightness so first we need to put in a command topic for our brightness and again we get that right out of the documentation in my case it's command basement light dimmer and notice that I added a brightness scale here when you do something like move a brightness slider in home assistant it's going to publish a numeric value back to the device and that's what the device expects is a numeric value but home assistant needs to know what is that maximum value when the brightness is set to 100% in my case it happens to be 100 but some devices may have something like 1028 or even 496 as the top value for the brightness so you need to put that scale in here so home assistant knows for example when you set the brightness to 50% with the slider it knows to send a value like 2048 to the device to set the brightness to 50% and finally we just simply add the state topic for our brightness as well once again this is coming in a Json payload so we need to get the value out of that and again it tells us here in the documentation or you can look at a sample payload and we can see here that it is dimmer so while my particular dimer switch here doesn't support it as I mentioned there are a number of additional State and command topics available for lights for things like colors and effects in fact here's a modified example right out of the home assistant documentation again we can see we've got our Command and our state topics we have to use Json to get the state out of a value template and brightness command and state topics just like in my example but you can see here we've now added additional state and command topics for things like RGB color and effects and there are many additional command and state topics available for lights for things like color temperature rgbw rgbww and even more and it's all going to depend upon what your device supports and what mqtt topics it makes available but my hope here is that by going through this step by step you can now look at that official home assistant documentation and maybe make a little more sense out of it now one note here as we wrap up if you are actually writing your own code and including mqtt in an upcoming video I'm going to show you how to add home assistant mqtt autodiscovery to your code so that your device will natively integrate right straight into home assistant without you or anyone who uses your code having to go through all these manual yaml steps so keep an eye out for that coming soon so I hope that answers some of the questions that I received from the earlier video on mqtt and gives you enough information that you can integrate these custom mqtt DIY devices that don't have native Integrations into your home assistant instance let me know down in the video comments if you have any further questions otherwise I would like to say thank you for watching and I hope to see you [Music] soon

Channel: ResinChem Tech

Views: 15,252

Keywords: Home Assistant, MQTT, DIY MQTT

Id: WYyPMHqMV-w

Length: 28min 51sec (1731 seconds)

Published: Sat Dec 16 2023